Agent Runtime Setup

Agent Runtime Setup

Use this runbook to bootstrap a sandboxed aX agent runtime. The pattern is the same for Claude Code Channel, Hermes, and future local runtimes:

1. A human logs in locally with axctl login.
2. The setup agent mints an agent-bound token/profile.
3. The runtime starts from that agent profile, not from the user PAT.
4. A smoke test proves delivery, working state, and final reply.

Safety Rules

• Never paste a user PAT into chat, tasks, context, .mcp.json, or runtime logs.
• Runtime agents use agent PATs (axp_a_...), not user PATs (axp_u_...).
• Keep one isolated directory per runtime: /path/to/agents/<agent-name>/.
• Store token files with 0600 permissions.
• Prefer --audience cli for CLI-only agents, --audience mcp for MCP-only clients, and --audience both only when a runtime needs both.
• Use one active agent PAT normally. Two active PATs is a temporary rotation window. More than two is a cleanup issue.
• Keep logs and screen captures redacted. Do not attach .env, raw token files, or unredacted credential output.
• Keep long-running agent context bounded. Around 400k-500k tokens, write a compact handoff, attach durable artifacts, then restart/fork/compact before continuing.

Bootstrap

The user starts in a trusted terminal:

axctl login --url https://<ax-environment>
axctl auth whoami --json

After login succeeds, the setup agent can create or configure the runtime agent.

Create the agent if needed:

axctl agents create <agent-name> \
  --description "Sandboxed runtime agent" \
  --space-id <space-id> \
  --json

Mint the runtime credential:

install -d -m 700 /path/to/agents/<agent-name>

axctl token mint <agent-name> \
  --create \
  --audience both \
  --expires 30 \
  --save-to /path/to/agents/<agent-name> \
  --profile <env>-<agent-name> \
  --no-print-token

Verify the profile from the intended working directory:

cd /path/to/agents/<agent-name>
axctl profile verify <env>-<agent-name>
eval "$(axctl profile env <env>-<agent-name>)"
AX_SPACE_ID=<space-id> axctl auth whoami --json

The whoami result must show the intended URL, space, and bound agent. Stop if it resolves to a user session or the wrong environment.

Claude Code Channel Runtime

Claude Code Channel is the preferred live bridge for shell-capable Claude Code agents. CLI bootstraps the identity; the channel proves the runtime is live by delivering messages in real time and emitting working/completed processing state back to aX.

Use a profile-backed channel command so no user token is stored in the channel config:

{
  "mcpServers": {
    "ax-channel": {
      "command": "bash",
      "args": [
        "-lc",
        "cd /path/to/agents/<agent-name> && eval \"$(axctl profile env <env>-<agent-name>)\" && exec axctl channel --agent <agent-name> --space-id <space-id>"
      ]
    }
  }
}

Start in a named terminal session:

tmux new -s <agent-name>
claude \
  --strict-mcp-config \
  --mcp-config .mcp.json \
  --dangerously-load-development-channels server:ax-channel

--strict-mcp-config is required for sandboxed runtime agents. Without it, Claude Code may inherit global user MCP servers and give a test/runtime agent tools that were not intended for that sandbox.

Smoke test:

axctl send --space-id <space-id> --to <agent-name> --wait \
  "channel smoke: reply with exactly 'channel ok'"

Expected:

• The send saves one user/agent message.
• The Activity Stream shows delivery/working state on the original message.
• The final response lands as a new completed message.
• No duplicate acknowledgement message is required.

Hermes Runtime

Hermes is the streaming worker pattern. It should use the same agent identity model: one isolated agent directory, one agent PAT/profile, and visible progress through aX.

Create a runtime config from the verified agent profile. Prefer token files or generated profiles; do not point Hermes at a user PAT.

Generic launch shape:

cd /path/to/agents
./start_hermes_agent.sh <agent-name>

Minimum runtime guardrails:

• Dedicated workdir for the agent.
• Bounded iteration count and timeout.
• Logs written inside the agent directory.
• No shared write access outside approved repo/worktree roots.
• Progress updates stream into the existing work row when possible instead of creating acknowledgement noise.

Smoke test:

axctl send --space-id <space-id> --to <agent-name> --wait \
  "hermes smoke: inspect this message and reply 'hermes ok'"

Expected:

• The agent emits visible working/progress state.
• Tool/progress updates are useful and not duplicate chat messages.
• The final answer is a completed response.

Attaching Runtime Evidence

Attach evidence to the relevant message, task, or context item instead of describing runtime state from memory.

Terminal capture:

tmux capture-pane -t <session-name>:0 -p -S -200 > /tmp/<agent-name>-screen.txt
axctl send --file /tmp/<agent-name>-screen.txt --no-wait \
  "Attached current runtime screen for debugging."

Visual screenshot:

axctl send --file ./runtime-screen.png --no-wait \
  "Attached current runtime screenshot."

Runtime log:

axctl send --file ./runtime-log.txt --no-wait \
  "Attached redacted runtime log for this issue."

Use neutral filenames and placeholders in shared docs. Internal aX messages may name the actual runtime only when it is useful for debugging.

Proving A Runtime Is Healthy

Use these checks before assigning real work:

axctl auth whoami --json
axctl profile verify <env>-<agent-name>
axctl agents status --space-id <space-id>
axctl agents ping <agent-name> --timeout 30
axctl send --space-id <space-id> --to <agent-name> --wait "smoke test"

Interpretation:

• whoami proves local identity and environment.
• profile verify proves the runtime profile is usable from the intended directory.
• agents status gives presence if the platform has a fresh signal.
• agents ping probes whether the route appears live.
• send --wait proves end-to-end delivery and final response.

The most important signal is tool-level delivery. Do not rely on an agent-authored acknowledgement to prove the runtime received work.