Jobs and results

Each remote command has a request ID and, after acceptance, a job reference. Use that reference to return to the same execution, including after the client or agent session ends.

Find your work

ax exec ls --refresh
ax exec ls -a --format json

The default list covers the current caller's jobs from your exact local workspace. -a includes that caller's other workspaces. It includes retained completed jobs and submissions whose acceptance is still unconfirmed.

Without --refresh, the list shows cached observations. A failed refresh keeps the previous observation and reports the error. Use ax exec status for a specific job when you need its current recorded state.

The JSON list includes the request ID, node, job/target reference, original command, local workspace and remote cwd. Harness/session labels appear when supplied. The local journal is on your client; the runner retains the execution state and output.

Understand the state

A local submission_unconfirmed entry means the client has no saved acceptance. The command may already have reached the runner. Reconcile it before starting another copy. Likewise, lost requires investigation before a rerun.

Recover output

Set job_id from the submission receipt or JSON job list. For a unique recorded job, ax finds its node and target locally:

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

Use --node and/or --target for an ambiguous job ID. Supply both for a job missing from this caller's journal.

watch prints retained stdout/stderr and follows until the job is terminal and output is drained. wait is an alias. Ctrl-C stops the local watch; it leaves the remote job running.

For a bounded output page, use:

ax exec output "$job_id" \
  --cursor 0 --format json

The result contains chunks, next_cursor, eof and truncated. Chunk bytes are base64 in JSON. Advance to next_cursor to read more without repeating old chunks. Check the final status as well as output EOF.

Output caps limit captured stdout/stderr; they do not reserve disk space or limit files written by the command. Overall disk limits belong to the host OS or filesystem.

The runner bounds output size and retention. Inspect ax exec info buildbox for its limits. New deployments retain output for one day and request identities for seven days; collect output you need to keep longer.

Retry a submission safely

For work you may need to retry, choose a UUID before submitting and pass it with --request-id. The CLI records the exact request before contacting the runner.

After a timeout or lost response, inspect the journal and retry with the same UUID, unchanged arguments and identical stdin bytes when --stdin was used. A saved acceptance returns the existing job reference. The CLI rejects changed arguments and retries outside the original request-retention window. If that window expired, reconcile the original job before deciding whether to launch new work.

A fresh UUID represents a new request. Reconnecting or starting a new harness session does not require one for an existing job.

Stop the intended job

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

Cancellation targets the job's supervised cgroup on the Linux backend, including its descendants. Confirm a terminal state after the request. You do not need to identify processes by matching their command names.

Separate waiting from execution

A harness tool timeout or an interrupted watch stops the client from waiting. run --timeout-ms requests a deadline on the remote execution itself. Jobs have no deadline by default unless the host's policy imposes one.

Quiet output alone does not establish a hang. A failed connection does not establish that the process stopped. Read where jobs run for the failure boundaries, or agent integration for retaining job context across harness calls.