Your first remote job

Deploy ax to a machine you can reach over SSH, start a command, then return to its result after closing the client.

Run the commands below on your client machine. You need an installed ax client and a Linux runner with systemd, cgroup v2 and an existing non-root SSH account. Replace user@build-host with your SSH destination; buildbox will be its local ax name.

1. Deploy the runner

Check the installation plan, then deploy:

ax deploy ssh user@build-host --name buildbox --plan
ax deploy ssh user@build-host --name buildbox

Signed release clients download a matching published runner binary automatically. For an unpublished version or an uncached offline deployment across platforms, add --bundle ./ax-runner-bundle/manifest.json to both commands after preparing the bundle.

Deployment installs ax under the SSH user's account, configures the service and access, and verifies a supervised command. In JSON output, successful execution readiness is reported as exec_ready: true. SSH installation alone is not enough; ax also checks its own connection to the runner.

Inspect the saved runner:

ax exec info buildbox

This shows the execution account, target, readiness and direct or relay connection. Jobs use the SSH account's permissions. Your SSH configuration and host-key checks still apply during deployment.

2. Run a command and watch it

Submit a short command with visible output and follow it:

ax exec run --node buildbox --follow -- \
  /bin/sh -c 'printf "started\n"; sleep 10; printf "finished\n"'

--follow keeps the command attached to your terminal: you see started, then finished about ten seconds later, then the final outcome. Pressing Ctrl-C stops watching without stopping the job; run ax exec watch "$job_id" to return to it.

The receipt prints request_id, node_id, node_name, target_id and job_id. Retain it for recovery. Set a shell variable using the returned job ID:

job_id='<job_id from the response>'

Without --follow, run returns right after submission, before the command finishes. The runner continues the command independently of this terminal either way, so you can close it and return later.

3. Find the job again

Return to the same local project directory and list its jobs:

ax exec ls --refresh

If you are in another local directory, use ax exec ls -a --refresh to include jobs from your other workspaces. The list includes retained completed jobs, so a fast command is still visible after it finishes.

Use ax exec ls --format json if you did not save the response. Set job_id, then inspect the same job. The local journal resolves its node and target:

ax exec status "$job_id"
ax exec watch "$job_id"

watch prints retained output and follows until the job ends. In this example you should see started and finished, with a successful outcome. Pressing Ctrl-C stops watching; use the same command to return to that job.

4. Run your own work

Choose a directory and executable that already exist on the runner:

ax exec run --node buildbox --cwd /srv/project -- bash scripts/check.sh

--cwd is a remote directory. Deployment does not copy your local project or scripts. Without --cwd, a deployed runner uses its saved working-directory default, normally the job account's home.

Arguments after -- go to the executable exactly as supplied. Use an explicit shell, as in the first example, when you need shell syntax.

Stop a job deliberately

If you need to stop work, cancel its specific job ID and check the result:

ax exec cancel "$job_id"
ax exec status "$job_id"

A cancellation request can take time to reach a terminal outcome. A client timeout or quiet output does not mean the command stopped.

Next, give your agent the ax skill, or read jobs and results for retries and output recovery.