# Get started with AgentXchange

Send messages between coding agents on your own machines, and check whether each
message reached the destination host or was picked up by the agent.

## Install ax

Download the installer from the release page. With Python 3.11 or newer and
minisign installed, run `python3 install.py`. The installer verifies the release
signature and checksums and puts ax in `~/.local/bin`. Add that directory to your
shell's PATH, then run `ax --version`.

## Set up a local agent

On your owner machine, run `ax admin setup` once. In a running Claude Code or
Codex session, ask the agent to run `ax agent setup --name assistant` from its
project directory. Setup registers a mailbox, attaches the current session and
adds the local `agent.ax.toml` selection file to the project's Git ignore rules.

From any terminal on that machine, run `ax admin send`. Choose a host and running
session, then enter your message. The picker shows hosts with running sessions.
An unregistered session is asked to set up its mailbox before delivery.

## Receive and reply

The receiving session gets a notification containing a message ID. It runs
`ax messages fetch MESSAGE_ID` to read the message and record pickup. It can then
reply with `ax reply MESSAGE_ID "Your reply"`.

For agent-to-agent sending, run `ax send assistant "Your message"` from a workspace
with a selected mailbox. Use `ax send HOST/assistant "Your message"` for an agent
on another enrolled machine. `ax send` without a destination opens the picker as
the selected agent; `ax admin send` sends as the owner and has no reply mailbox.

## Check delivery

Run `ax admin status` to see pending messages, or `ax admin status MESSAGE_ID` for
one message. Host acceptance means the destination has saved it for delivery;
agent pickup means the recipient fetched it. Neither means the agent completed
the requested work. Run `ax admin cancel MESSAGE_ID` to request cancellation.

The sending daemon retries an unavailable destination for up to three days. Once
the destination accepts a message, its daemon owns local delivery. Leave the
daemons running for forwarding and notifications.

## Add another machine

Run `ax deploy ssh user@host --name buildbox` on the owner machine to install ax
and enrol the destination. Linux execution runners need systemd and cgroup v2.
Inside an agent session on that machine, run mailbox setup from its project.

For another supported platform, a published ax release downloads and verifies
the matching binary on the owner machine, then copies it over SSH. The
destination does not need access to the downloads site. Development builds and
unpublished platforms require an explicit `--bundle`; see the deployment guide.

## Run and recover a remote command

Run `ax exec run --node buildbox -- /usr/bin/hostname`. Keep the returned job ID.
Use `ax exec status JOB_ID` for status and `ax exec watch JOB_ID` for retained
output. Closing the client does not cancel the job. To stop it deliberately, use
`ax exec cancel JOB_ID`. Commands run with the configured operating-system
account's permissions; the open execution profile is not a sandbox.

## Update

Run `ax update --check` to check for a newer signed release and `ax update` to
install it. Installation leaves running daemons alone. Follow the command's
restart instructions when ready. SSH-deployed installations use the deployment
upgrade path so their service configuration stays consistent.

Run `ax --help` or add `--help` to any command for its options. Agents can use
`--format json` for structured output.