arizuko › reference › packages

packages

Run arizuko package add to select a package. arizuko package sync installs the selected packages and their resource rows.

┌──────────────────────────────┐     ┌──────────────────────────┐
│ installed_packages rows      │     │ Local or Git source      │
│ from package add and rm      ├────►│ arizuko.yml and assets   │
└──────────────────────────────┘     └────────────┬─────────────┘
                                                  │ package sync
                                    ┌─────────────▼────────────┐
                                    │ Installed package assets │
                                    │ and owned resource rows  │
                                    └─────────────┬────────────┘
                                                  │ generate
                                    ┌─────────────▼────────────┐
                                    │ Services and compose     │
                                    └─────────────┬────────────┘
                                                  │ deployment
                                    ┌─────────────▼────────────┐
                                    │ Running services         │
                                    └──────────────────────────┘

The installed_packages rows select packages

Each selection is one row in the installed_packages resource. The arizuko.yml file in a package source defines that package and selects nothing. Group arizuko.yml files are not read.

arizuko package add [-g folder] <source>
arizuko package rm [-g folder] <name>
arizuko package sync

add installs a package and records the selection. rm withdraws the selection, its rows and its services. sync installs every selected package again from its source. Without -g, a package applies to the whole instance. With -g folder, it applies to that group only. Use -i/--instance NAME to select another instance. Use -f/--force only to replace an existing destination that no package owns.

Installing github.com/kronael/tools requires uv on the host and can download Python and dependencies. The installed checker runs offline in the guest.

Catalog sources select bundled services. Other sources are local directories or Git repositories; relative paths resolve under HOST_APP_DIR. The same strict YAML format declares package metadata and typed resource documents. A source requires a name, and the name of the source directory does not define the package identity.

Packages supply standard guest assets

Skills, native hooks, manuals and executables stay under packages/NAME/. The renderer mounts selected assets read-only. Executables use /usr/local/bin; hook files use native Claude and Codex configuration paths. Core is an ordinary package installed for every group.

An optional install command runs on the host as the invoking operator during package add and package sync. PREFIX names the installed directory. Builds place executables in $PREFIX/bin/; agent turns run no host installer.

Services provision shared environment values

A service package ships a Docker compose fragment beside its manifest. Only service packages provision shared .env values: generate mints once, default supplies a compose default, and required refuses a missing value. Skills-only requirements are metadata; use scoped group secrets for credentials.

Ownership bounds updates and removal

The existing installed-package resource records source, resolved revision, selected folder, owned row keys and service hashes. package sync replaces package-owned rows. package rm withdraws the rows and services of one package. Unrelated operator rows remain. Edited service fragments refuse replacement.

Group packages cannot supply services or resource rows. Package grant scopes must fit the selection's folders bounds. Reserved core web paths and forged owners refuse before apply.

Later packages override earlier packages

Core comes first. Packages follow in the order the operator added them; to move a package later, run package rm and then package add. A later package overrides an earlier package on the same skill, hook, tool (bin/) or group/ path. package sync prints one line for each override. A local .disabled marker suppresses a packaged skill mount.

demo: kronael-tools overrides core on skills/diary

Group files come from the winning package

The group/ directory of a package holds files for the group folder, at the same relative paths. Each package sync rewrites every such file from the winning package and replaces any edit by the agent. A file that a package stops shipping is removed. A file that no package ships stays the file of the group. The runtime adds the deny rule Edit(~/<path>) to the turn settings for each package file. The rule asks the agent not to edit the file; it is advice and no security boundary. A file that exists and that no package installed stops the command unless you pass -f. The product guide explains workspace templates.

Source: package guide, sync implementation, guest mounts.