​

Agent Runtime Guide

Status: User-facing guide
Last updated: 2026-02-17
Audience: Operators setting up and running agents in AoA

​

1. What this system does

Agents in AoA do not run continuously.
They run in heartbeats: short execution windows triggered by a wakeup. Each heartbeat:

1. Starts the configured agent adapter (for example, Claude CLI or Codex CLI)
2. Gives it the current prompt/context
3. Lets it work until it exits, times out, or is cancelled
4. Stores results (status, token usage, errors, logs)
5. Updates the UI live

​

2. When an agent wakes up

An agent can be woken up in four ways:

• timer: scheduled interval (for example every 5 minutes)
• assignment: when work is assigned/checked out to that agent
• on_demand: manual wakeup (button/API)
• automation: system-triggered wakeup for future automations

If an agent is already running, new wakeups are merged (coalesced) instead of launching duplicate runs.

​

3. What to configure per agent

​

3.1 Adapter choice

Common choices:

• claude_local: runs your local claude CLI (Claude Code)
• codex_local: runs your local codex CLI (OpenAI Codex)
• cursor: runs the Cursor Agent CLI
• opencode_local: runs OpenCode CLI (multi-provider provider/model)
• gemini_local: runs Google’s Gemini CLI
• hermes_local: runs Hermes Agent (Nous Research) via the hermes CLI
• openclaw: wakes a remote OpenClaw agent over HTTP (SSE or webhook)
• process: generic shell command adapter
• http: calls an external HTTP endpoint

For local CLI adapters, AoA assumes the CLI is already installed and authenticated on the host machine.

​

3.2 Runtime behavior

In agent runtime settings, configure heartbeat policy:

• enabled: allow scheduled heartbeats
• intervalSec: timer interval (0 = disabled)
• wakeOnAssignment: wake when assigned work
• wakeOnOnDemand: allow ping-style on-demand wakeups
• wakeOnAutomation: allow system automation wakeups

​

3.3 Working directory and execution limits

For local adapters, set:

• cwd (working directory)
• timeoutSec (max runtime per heartbeat)
• graceSec (time before force-kill after timeout/cancel)
• optional env vars and extra CLI args
• use Test environment in agent configuration to run adapter-specific diagnostics before saving

​

3.4 Execution targets

AoA currently supports two execution target values in agent.adapterConfig.executionTarget:

• {"type":"local"}: default. Runs the adapter command as a local child process.
• {"type":"sandbox-docker","image":"node:22-bookworm","workdir":"/workspace"}: runs the adapter command through Docker CLI with the workspace bind-mounted at /workspace. The container calls back through host.docker.internal and a run-scoped bridge.

remote-ssh, sandbox-e2b, and sandbox-daytona are reserved for a future execution-target expansion. Do not configure them yet. Execution target configuration stays in the existing adapterConfig JSONB field until a future schema pass. This release does not add a migration.

​

3.5 Prompt templates

You can set:

• promptTemplate: used for every run (first run and resumed sessions)

Templates support variables like {{agent.id}}, {{agent.name}}, and run context values.

​

4. Session resume behavior

AoA stores session IDs for resumable adapters.

• Next heartbeat reuses the saved session automatically.
• This gives continuity across heartbeats.
• You can reset a session if context gets stale or confused.

Use session reset when:

• you significantly changed prompt strategy
• the agent is stuck in a bad loop
• you want a clean restart

​

5. Logs, status, and run history

For each heartbeat run you get:

• run status (queued, running, succeeded, failed, timed_out, cancelled)
• error text and stderr/stdout excerpts
• token usage/cost when available from the adapter
• full logs (stored outside core run rows, optimized for large output)

In local/dev setups, full logs are stored on disk under the configured run-log path.

​

6. Live updates in the UI

AoA pushes runtime/activity updates to the browser in real time. You should see live changes for:

• agent status
• heartbeat run status
• task/activity updates caused by agent work
• dashboard/cost/activity panels as relevant

If the connection drops, the UI reconnects automatically.

​

7. Common operating patterns

​

7.1 Simple autonomous loop

1. Enable timer wakeups (for example every 300s)
2. Keep assignment wakeups on
3. Use a focused prompt template
4. Watch run logs and adjust prompt/config over time

​

7.2 Event-driven loop (less constant polling)

1. Disable timer or set a long interval
2. Keep wake-on-assignment enabled
3. Use on-demand wakeups for manual nudges

​

7.3 Safety-first loop

1. Short timeout
2. Conservative prompt
3. Monitor errors + cancel quickly when needed
4. Reset sessions when drift appears

​

8. Troubleshooting

If runs fail repeatedly:

1. Check adapter command availability (e.g. claude/codex/cursor/opencode/gemini/hermes installed and authenticated).
2. Verify cwd exists and is accessible.
3. Inspect run error + stderr excerpt, then full log.
4. Confirm timeout is not too low.
5. Reset session and retry.
6. Pause agent if it is causing repeated bad updates.

Typical failure causes:

• CLI not installed/authenticated
• bad working directory
• malformed adapter args/env
• prompt too broad or missing constraints
• process timeout

Claude-specific note:

• If ANTHROPIC_API_KEY is set in adapter env or host environment, Claude uses API-key auth instead of subscription login. AoA surfaces this as a warning in environment tests, not a hard error.

​

9. Security and risk notes

Local CLI adapters run unsandboxed on the host machine. That means:

• prompt instructions matter
• configured credentials/env vars are sensitive
• working directory permissions matter

Start with least privilege where possible, and avoid exposing secrets in broad reusable prompts unless intentionally required.

​

10. Minimal setup checklist

1. Choose adapter (claude_local, codex_local, cursor, opencode_local, gemini_local, hermes_local, openclaw, process, or http). See adapter reference docs for prerequisites and config fields.
2. Set cwd to the target workspace.
3. Add bootstrap + normal prompt templates.
4. Configure heartbeat policy (timer and/or assignment wakeups).
5. Trigger a manual wakeup.
6. Confirm run succeeds and session/token usage is recorded.
7. Watch live updates and iterate prompt/config.