Run agents

hal0 can run a bundled agent — Hermes — provisioned into a hal0-managed virtualenv and driven through the hal0 agent CLI. The agent gets a persona (system prompt + tool gating), an approvals queue for gated/destructive actions, and an optional per-persona spending budget.

Note

Only one bundled agent is active at a time (single-pick). hal0 agent lifecycle commands are thin clients over the API; provisioning Hermes runs locally in the foreground because the venv build can’t fit in one HTTP request.

Install Hermes

sudo hal0 agent install hermes

Installing Hermes runs a three-step foreground pipeline:

1. Toolchain — ensures python3 (≥3.11), the venv stdlib, pip, and pipx via the distro helper. Idempotent.

2. Provision — creates the managed venv under /var/lib/hal0/venvs/hermes, pip-installs hermes-agent, installs the hermes shim, and registers the agent.

3. Enable — systemctl enable --now hal0-agent@hermes so the agent runs and survives reboot.

Run it as root: provisioning writes under root-owned /var/lib/hal0 and then chowns the provisioned trees to the hal0 user (the shared agent runtime user). If you run it as a normal user it aborts cleanly up front with a sudo hint rather than crashing mid-build.

Pass --switch to atomically uninstall whatever agent is currently installed before installing this one.

Manage the lifecycle

List / status

hal0 agent list                 # installed bundled agents
hal0 agent list --json
hal0 agent status hermes        # provisioning checkpoint, per phase
hal0 agent peers                # every published agent identity card

list only shows agents installed on this host; peers searches the agents memory dataset for every identity card any host has published (needs the memory API reachable — it dies with a clear error otherwise).

Logs

hal0 agent log hermes
hal0 agent log hermes --phase provision

Per-phase provisioning logs from the agent’s state directory.

Re-run / upgrade

hal0 agent reprovision hermes          # idempotent re-converge
hal0 agent reprovision hermes --repair # force every phase
hal0 agent upgrade hermes              # bump the version pin + repair
hal0 agent upgrade hermes --to 0.15.3  # pin a specific version

reprovision is a stable wrapper over the same state machine that install runs. For finer control — skipping a phase, staging the hermes-agent wheel offline, or a dry run that doesn’t persist the checkpoint — drop to the underlying command directly:

hal0 agent bootstrap hermes --dry-run
hal0 agent bootstrap hermes --repair --verbose
hal0 agent bootstrap hermes --skip-phase provision_venv --offline

To restart the running Hermes process without re-provisioning anything (no config re-render, no ownership reconcile), restart the systemd unit directly or hit its restart endpoint:

sudo systemctl restart hal0-agent@hermes
curl -X POST http://localhost:8080/api/agents/hermes/restart

Uninstall

hal0 agent uninstall hermes
hal0 agent uninstall hermes --keep-memory

Default uninstall tears down the agent’s private memory namespace too; --keep-memory preserves it so a re-install reuses the identity card.

Personas

A persona is a TOML file pairing a system prompt with tool gating. Manage them with the personas sub-app:

hal0 agent personas list                 # list + mark the active one
hal0 agent personas show <id>            # print a persona's TOML (good template)
hal0 agent personas activate <id>        # switch active + nudge a hot-reload

Activating writes the active.txt pointer atomically and best-effort nudges a running Hermes to hot-reload. If Hermes isn’t running, the next restart picks up the new active persona. To author your own, copy personas show output, change the persona id, and save it under the persona store.

The approvals queue

Destructive or gated tool calls don’t execute immediately — they land in an approvals queue you review:

hal0 agent approvals list                # pending requests
hal0 agent approvals approve <id>        # let it run
hal0 agent approvals deny <id>           # reject it

Each pending row shows the request id, the tool, the requesting agent (client_id), when it was enqueued, and a one-line summary built from the tool’s primary argument. The dashboard’s Agent → Approvals tab renders the same queue.

The Operator Board (dashboard ▸ Board) — Hermes agent tasks move across Triage → To-do → Scheduled → Ready lanes.

Spending budget

Each persona can carry spending caps so an autonomous loop can’t drain a paid provider pool. Caps live in the persona’s [persona.budget] sub-table:

[persona.budget]
daily_usd = 5.0
monthly_usd = 50.0
lifetime_usd = 200.0
per_call_max_usd = 0.50
hard_cap = true

Every cap is optional — omit one to leave that window uncapped, or set it to 0.0 to block every paid request. hard_cap = true (the default) denies requests that would overshoot; hard_cap = false lets them through but still reports the breach so the caller can log a warning. Spend is tracked in an append-only ledger per persona, aggregated over daily, monthly, and lifetime windows.

Check the configured caps plus running spend for a persona over the API (there’s no dedicated CLI verb for this yet):

curl http://localhost:8080/api/agents/hermes/personas/hermes/budget

The same route accepts a PUT with a {"daily_usd": ..., ...} body to change the caps without hand-editing the persona TOML.

Audit trail

Every gated tool invocation is journaled. Pull an agent’s recent MCP activity:

curl 'http://localhost:8080/api/agents/hermes/activity?limit=50'

Each row carries tool, args, gated, outcome, timestamp, and the client_id the action was attributed to.

Related

• Enable memory — the recall store agents read and write.
• Connect external providers — wire the paid upstream a budget caps spend against.