What is ax

ax turns a remote command into a job with its own ID. The runner supervises it after the client exits and keeps its status and output, so another session can come back to it. Use it when your terminal closes or a tool call times out and the work has to continue on another machine, or when the next agent session needs to know what happened.

Why ax exists

Agents use SSH the way people do: a command, a wait loop, a process search, and a log read. That works while the connection and the session last. When either ends, the next session has to reconstruct what is still running from process names and partial output.

SSH under agents

Two failures recur in our own Claude Code and Codex sessions. A wait loop matches its own command line and never exits:

Two leftover shells from my own waiting loop 36 hours ago are stuck because their pgrep -f matches their own command — I'll kill those, leaving the other two untouched since they belong to a different session.

— a Claude Code session

A cleanup command matches the shell that is running it:

The combined remote command was killed by the broad pkill pattern matching the shell command itself.

— a Codex session

An SSH timeout fails differently: the client knows it stopped waiting, but not what happened on the host. The process may still be running, may have finished, or may have printed output that never reached the next session.

File transfer

File transfer breaks the same way. rsync, tar over scp, and nested remote shells work until an agent has to quote a path through another shell, resume a partial transfer, or prove which bytes arrived. A failed transfer can look like a successful command with missing files.

ax's workspace transfer moves selected project files over the same authenticated connection, in either direction. It checks the bytes on arrival and keeps the transfer tied to the job that uses it. Workspace file transfer covers what the current build supports.

A network the laptop cannot reach

A Portal Desktop networking change had to be measured on a shaped WAN path: a test host on another network, an emulated link at 50 ms each way with a 100 Mbit/s shaper, a 256 MiB file and 10,000 small files. Testing from a VPN-bound laptop is often impossible because two VPNs cannot run in parallel. With ax, the harness ran the test commands on the remote host and recovered their results in later client calls.

Check your own sessions

Have your harness audit its own saved session transcripts. The audit is read-only: it finds the SSH commands, wait loops and transfer attempts, then reports what each one cost.

Read your own saved session transcripts from the last 30 days, read-only.
Find SSH commands, `pgrep -f` and `pkill -f` wait loops, and `rsync`, `scp`
or `tar` transfers to a remote host. For each distinct failure, report the
command with private host names and paths removed, what went wrong, and how
long it blocked the session. Group repeated descriptions of the same incident
instead of counting it twice. Do not run remote commands, edit files or install
anything. End by saying which of these failures a submitted job with a durable
ID and retained output would have removed.

The transcript-mining commands and prompts for runner discovery, job recovery and messaging are in the agent prompts guide. We found both quotes by auditing our own sessions the same way.

What ax does

Aster Exec

Aster Exec submits an executable and argument array to a runner and returns a job reference at once. Status and output stay on the runner after the client is gone. Come back with the same job ID to read output from a cursor, wait again or cancel the job.

ax exec run --node buildbox --cwd /srv/project --format json -- \
  bash scripts/check.sh
ax exec ls --refresh
ax exec status "$job_id"
ax exec watch "$job_id"

The client submits once and receives a job ID; the runner supervises the process, retains status and output, and the same job ID recovers the work from another session.

AgentXchange messaging

AgentXchange messaging sends a signed message from a selected agent identity to a named or discovered recipient. The host's acceptance and the agent's pickup are separate states. The sender daemon keeps and forwards the original message for three days. The recipient's fetch records pickup, and a reply goes back to the authenticated sender.

From install to a recovered job

Install ax on macOS, Linux, or Windows with WSL, deploy a runner over SSH, submit a command, close the client, then recover the same job by ID. Your first remote job covers deployment, submission and recovery on a Linux runner with systemd. Install ax prepares the client, and Where jobs run covers the macOS backend and the WSL path on Windows.