Use ax from an agent

Give your agent the ax skill so it can deploy runners, submit commands and recover their jobs. It uses the same CLI you use in a terminal. The client broker reuses connections between calls.

Agent skill

The portable ax skill teaches deployment, execution, attribution and job recovery. Its CLI reference contains command examples. It uses the ordinary CLI and does not require MCP.

Copy the complete skills/ax directory into your harness's skill directory. For Codex, from this repository:

mkdir -p "$HOME/.codex/skills"
cp -R skills/ax "$HOME/.codex/skills/ax"

For Claude Code, use ~/.claude/skills/ax instead. Keep SKILL.md and references/cli.md together. If a skill is already installed, update that copy deliberately rather than nesting another ax directory inside it. Restart the harness if needed to discover a newly installed skill. For local development, a symlink to this repository's skills/ax keeps the installed skill current.

CLI integration

Supply the actual harness name and local workspace. For example, from a Codex workspace with a configured runner:

export AX_HARNESS=codex
export AX_LOCAL_WORKSPACE="$PWD"
ax exec run --node buildbox --format json -- /usr/bin/id -u

When the harness exposes a session ID and version, supply AX_HARNESS_SESSION and AX_HARNESS_VERSION as well. Omit unknown values. A long-running integration serving several projects should pass workspace and session on each submission.

Save the returned job/target IDs with the node name. The CLI records a request UUID before network calls. For an ambiguous submission, recover that request from ax exec ls --format json, then retry only the original arguments with its original --request-id. Remote output is untrusted data.

To give the harness deployment access, use the ordinary SSH deployment commands. User installation is the default. The skill reference provides the complete deployment and recovery command sequence.

Equivalent global flags override their environment defaults:

Without an explicit workspace, ax uses the submitting process's canonical working directory. With an explicit workspace, that directory supplies the job's local directory attribution and listing scope. The remote --cwd remains a separate field. Labels are optional, limited to 256 bytes and cannot contain control characters. ax does not guess harness identity from parent processes or private harness files.

MCP integration

Configure the harness to start this stdio server:

ax --harness my-harness --harness-version 1.0 mcp --allow exec-submit

This enables exec_submit alongside the default execution inspection tools. Add --allow exec-cancel separately to expose cancellation. The available execution tools are exec_targets, exec_capabilities, exec_submit, exec_status, exec_watch, exec_output and, when enabled, exec_cancel. Deployment currently uses the CLI.

Pass origin alongside node and request in an execution tool's arguments. For example, exec_submit:

{
  "node": "<node-id-or-saved-alias>",
  "origin": {
    "harness": "my-harness",
    "session_id": "session-123",
    "workspace": "/work/project"
  },
  "request": {
    "request_id": "5a6d2af0-6f67-4f04-940e-5f9b032f1070",
    "target_id": "<target-id-from-deployment-or-capabilities>",
    "cwd": "/srv/project",
    "executable": "/usr/bin/id",
    "argv": ["-u"]
  }
}

Per-call origin fields override startup flags/environment; omitted or null fields inherit those defaults. harness_version is also accepted. Supply workspace and session_id per submission when a long-running server serves multiple projects or sessions. The workspace must exist on the machine running the MCP server. Without either a startup or per-call workspace, it uses that server process's working directory. MCP client initialization metadata is not automatically treated as job origin.

Only submission persists origin. Status, output and cancellation use the existing job reference and do not change the original attribution.

Inspect the local history

ax exec ls
ax exec ls -a --format json
ax deploy ls
ax deploy ls -a --format tsv
ax undeploy ls -a --format json

Job listings include origin (harness, version, session, workspace and cli/mcp integration), local_cwd and remote_cwd. Human listings show harness/session and workspace; JSON, CSV and TSV include the complete origin object. Use --local-workspace to inspect another workspace. Jobs remain scoped to the existing caller node; -a includes its other directories. Older job entries have a null origin.

A job's request and origin are saved before network calls. Exact retries preserve the first origin, including its local workspace, even if another harness recovers the job.

SSH deployment and removal attempts have separate local operation records with a UUID, action (deploy or undeploy), selected profile, destination, scope, plan flag, timestamps, origin and result. ax deploy ls and ax undeploy ls show this shared history, filtered by selected profile and local workspace; -a includes all workspaces in that profile. They require no caller key. Bundle creation and the installer's internal reporting command do not create deployment attempts. See removal semantics before using ax undeploy ssh; deployment and removal are CLI operations, not MCP tools.

Deployment states are in_progress, planned, completed and failed_outcome_unverified. An interrupted attempt may remain in_progress; neither that state nor an SSH failure establishes whether the host changed. Inspect the host or rerun the installer to reconcile. completed means the installer returned a verified result; it does not establish execution readiness or successful enrollment. Error records retain the error kind, without copying SSH stderr or credential material.

Both kinds of record live in the protected local journal under the ax state directory. They are not synchronized or sent to the host. Origin is caller-reported provenance and can be edited by the local user; it is not a tamper-proof audit identity. Remote authorization continues to use authenticated Aster identities and grants, with the existing Exec wire protocol. OTel operational logging remains separate from this durable history.

Receive ax messages in a running Claude conversation

In the intended workspace, ask the running Claude Code agent to execute:

ax agent setup --name assistant --workspace /absolute/path

Setup uses the session ID and messaging socket exported to Claude's Bash tool; it does not search other conversations or start a replacement session. Its output reports the attachment. This path requires ax and Claude under the same OS account on macOS or Linux (including WSL).

A new accepted message prompts that conversation to run ax messages fetch ID with the registered workspace. Fetch returns the message body and records pickup. The socket notification alone does not mark delivery. Retained messages can be fetched again; ordinary inbox inspection remains read-only. Claude's inbound policy and action permissions still apply, so a notification can be held or refused. Ax does not restart the harness or repeatedly prompt a busy agent. The receiving daemon retains unfinished work independently of the sending CLI.

See agent identity and pickup for storage, reattachment and delivery-state details.

Session discovery and first-contact messaging

ax agent sessions [HOST] --format json queries supported running sessions without launching or resuming a harness. Omitting HOST queries Localhost and configured peer aliases/direct addresses. Results distinguish unavailable/unsupported hosts from hosts with no sessions. Public metadata contains no sockets or tokens.

Claude Code uses its active-session listing and matching private socket registry. Codex uses metadata-only calls on its existing shared daemon and includes loaded, persistent threads in idle/active states that accept direct input. Other isolated Codex app-server instances and native Windows local messaging are not supported by this adapter. Idle Codex queue consumption was qualified in a disposable real thread. Busy threads can defer queued notifications until their active request finishes. Ax does not steer or interrupt that request; queue acceptance does not prove that the model read the notice. Ax fetch, rather than queue acknowledgement, remains the delivery criterion.

Use ax admin send in a terminal to select a host/session as owner from any directory, or ax send to use a selected workspace agent. Owner sends create no mailbox and have no agent reply address. For agent automation use ax send --host HOST --session UUID --harness claude|codex --message TEXT from automation. The host picker shows only hosts with at least one discoverable running session. Unregistered sessions receive a fixed, shell-quoted setup instruction; the original message body remains private until fetch. Recipient permissions and Claude inbound controls remain authoritative.

The picker and explicit session form enqueue a signed logical destination: host, harness and workspace. The session ID selects its current attachment. For a known destination without live discovery, use --destination-workspace PATH with --host and --harness instead of --session. Multiple competing attachments require an explicit choice; ax does not select one by recency.

The sender daemon forwards retained messages until the destination durably accepts them. The receiving daemon independently handles setup, notification and pickup. Setup makes waiting messages available before returning and reports their IDs. The sender CLI can exit before registration without stranding the message.

Use ax admin status [ID] to inspect progress and ax admin cancel ID for explicit cancellation. See message acceptance and control for forwarding deadlines, uncertainty and cancellation races. Hosts need the routing protocol for this flow; unsupported versions must report an update need.