Running the agent

Running the agent

There are four ways to run Holaryn Agent: an attended terminal session, the persistent host, the desktop app, and a native OS service. They all share the same state directory, event stream, and approval model.

Attended sessions: holaryn run

holaryn run starts a one-off attended session in your terminal. Pass a task to run it once, or omit it for an interactive REPL:

holaryn run "Rename every .txt file in ./notes to .md"
holaryn run

Approvals happen inline: when the agent wants to take a consequential action, it prints the request and waits for your answer. Useful flags:

• --autonomy {ask,selective,allow-all,unrestricted} — the autonomy posture for this session. The default is ask (everything consequential waits for you); selective lets reversible actions proceed and asks for irreversible ones. See Autonomy and approvals.
• --allow-all yes / --unrestricted yes — explicit arming shortcuts for the permissive postures; no forces ask.
• --policy <file.toml> — a policy profile with fine-grained per-category and per-tool rules that override the posture.
• --model <id> — run on a specific model from your registry instead of the default.
• --profile <name> — apply a saved config profile (model, persona, posture, overrides).
• --dry-run — stage irreversible actions into a reviewable plan instead of executing them; review later with holaryn plan.

In the REPL, /commands and @target mentions route before the agent sees the line — see Slash commands.

The persistent host: holaryn serve

holaryn serve

holaryn serve runs the always-on supervisor: the web UI (on by default at http://127.0.0.1:8765), the scheduler, subagents, teams, peers, live steering, operator questions, and parked approvals. Turn the web UI off with --no-web, or change the bind address with --host and --port. Add --auth-token <token> to require a token on the local HTTP API, and pass the same token to CLI commands that talk to the host.

Stop the host with Ctrl+C; it checkpoints its state and releases its lock on the way down.

The desktop app

The desktop app wraps the same web UI in a native window with a tray icon. On launch it starts a host — or, if one is already running for the state directory (for example the OS service), it attaches to the running host instead of starting a second one. Closing the window hides to the tray; the agent keeps running. See Desktop app.

The OS service: holaryn service

To keep the host running across logouts and reboots, register it as a native service — systemd on Linux, launchd on macOS, or the Windows Service Control Manager:

holaryn service install --platform linux --state-dir /var/lib/holaryn --env-file /etc/holaryn/holaryn.env
holaryn service status --platform linux

On Windows, run these from an elevated PowerShell:

holaryn service install --platform windows --state-dir C:\ProgramData\holaryn
holaryn service status --platform windows

holaryn service status reports both the OS service state and the host's own status, and warns when another process (such as the desktop app) already owns the state directory. Use --print-artifact with install to preview the generated unit/plist/SCM definition without changing the machine. Put provider keys in the service environment or the referenced env file — never in config files.

The state directory

All durable state lives in one directory: C:\ProgramData\holaryn on Windows, /Library/Application Support/holaryn on macOS, and /var/lib/holaryn on Linux by default. Override it with --state-dir on most commands or the HOLARYN_STATE_DIR environment variable. Inside you will find, among others:

• jobs.sqlite3 — scheduler jobs (schedules survive restarts).
• memory.sqlite3 — the agent's memory.
• run-journal.sqlite3 — every turn of live runs, so a crashed host can resume them.
• parked-approvals.sqlite3 and parked-questions.sqlite3 — decisions waiting on you.
• steer-queue.sqlite3 — queued steering directives.
• providers.json and secrets.json — the model registry and its secret store.
• logs/host.log — the host log.
• holaryn-host.lock and host-status.json — the instance lock and status file.

One host per state directory. The lock file guarantees only one host process owns a state directory at a time; a second holaryn serve against the same directory refuses to start. This is why the desktop app attaches to an existing host rather than competing with it.

Steering a live run

You can redirect a running task without interrupting it:

holaryn steer "Focus on the failing retry path"
holaryn steer web/sub:1 "Stop and summarize what you found"

The directive is injected into the run's transcript at the next turn boundary — it never interrupts a tool call already in flight. Omit the session id to target the lead web session. Queued directives survive a host restart.

Resume after a restart

When the host starts, it resumes non-terminal runs from the run journal. Completed tool calls are replayed, not re-executed. If a side-effectful tool call was in flight when the host stopped and its outcome is unknown, the run parks a resume decision instead of silently retrying:

holaryn resume list
holaryn resume decide <decision-id> rerun   # or: skip, abort

The same decisions appear in the web UI's Approvals inbox. Check overall host state — including resumable runs and pending decisions — with:

holaryn status

Full flag listings for every command are in the CLI reference.