Installing Agents

The Agent Store is agentd's persistent registry of named agent definitions. Installing an agent registers its manifest and install directory so it can be spawned by name, without having to provide a manifest file path each time.

Install an agent

ash agent install path/to/manifest.yaml

agentd reads the manifest file, validates it, and stores the definition in the agent_definitions SQLite table.

With a custom install directory

By default, agentd uses /var/lib/scarab-runtime/agents/<name> as the install directory. Override it with --dir:

ash agent install path/to/manifest.yaml \
  --dir /opt/my-agents/report-agent

The install directory is where the agent binary and any supporting files live. agentd records this path and uses it when spawning the agent.

What gets stored

List installed agents

ash agent list
# alias:
ash agent ls

Output:

NAME            VERSION   RUNTIME  INSTALL DIR                              INSTALLED AT
report-agent    1.0.0     rust     /var/lib/scarab-runtime/agents/report    2026-01-15T10:00:00Z
hello-agent     2.1.0     rust     /opt/my-agents/hello                     2026-01-10T08:30:00Z

Remove an installed agent

ash agent remove report-agent

Removing a definition from the store does not affect agents that are currently running. Use ash kill <agent-id> to stop running instances first.

Capability sheet

Print a Markdown-formatted capability summary for a manifest file. Does not require agentd to be running:

ash agent capability-sheet path/to/manifest.yaml

This renders a human-readable table of the agent's declared capabilities, trust level, resource limits, and network policy, which is useful for security review before installation.

Install directory layout

A typical install directory contains:

/var/lib/scarab-runtime/agents/my-agent/
├── manifest.yaml          ← copy of the manifest
├── my-agent               ← compiled agent binary
└── config/                ← optional agent-specific config files

The manifest's command field should reference the binary relative to the install directory, or as an absolute path.

System vs. user installs

The ash agent install command registers the definition in agentd's runtime store regardless of where the files live on disk.