Let your chat hand the work to the coding agent that already has the repo.

The agent in your browser has your instruction. The machine under your desk — or the VM in eu-central-1 — has the checkout, the toolchain, the private registry token, the .env, the datasets and the GPU. AI Commander lets the first one start a headless coding agent on the second: claude -p "…", codex exec "…", or whatever CLI you use, spawned as a detached job that keeps working after the tool call returns and after the conversation ends. You ask how it went later — from another chat, another client, or your phone.

What actually happens

There is no agent-to-agent protocol here, and no ask_agent tool. The mechanism is deliberately boring, which is why it works with every coding agent that has a non-interactive mode:

• Your cloud agent (Claude, ChatGPT, Cursor, Codex) talks to the AI Commander relay over MCP or the REST API.
• It calls remote_job_start with a command. That command happens to be a coding agent's headless invocation, run in the repo directory on the target machine.
• The machine spawns it, writes its stdout and stderr to a file there, and returns a jobId immediately.
• The local coding agent then does what it does — reads the code, edits, builds, runs the tests, retries — for as long as it takes, with no chat in the loop.
• Later, anyone with the jobId calls remote_job_status, remote_job_logs or remote_job_cancel and finds out what happened.

So the cloud agent is the dispatcher and the reporter; the local agent is the one doing the engineering. The only thing crossing the relay is an instruction going in and bounded slices of log coming out.

Why not just let the cloud agent write the code

Sometimes you should. But three things fall out of running the coding agent on the machine that owns the work:

• The repository never gets copied to us. AI Commander does not upload the repo, the .env, the customer dataset, the internal packages or the deploy keys anywhere: they are read where they already live, by a process on your own hardware. What crosses our relay is the instruction going in and the slices of log you ask for, and command text and output are never logged or stored — they stream through the relay's memory and are discarded. That is a statement about us, not about the coding agent you start there. Claude Code and the codex CLI are clients of their own model providers: whatever they read while working — source files, whatever secrets sit in the files they open, test output — is sent to that provider under that provider's terms, exactly as it would be if you ran the same CLI sitting at the machine yourself. So this is not a guarantee that your code stays private; it is a guarantee that AI Commander is not the one moving it. Pick which agent runs there, and what it is allowed to read, on that basis.
• The run is not bounded by the chat. A conversation ends, a client disconnects, a laptop sleeps. The job does not care — it belongs to the machine. A refactor that takes forty minutes and two full test runs does not need you sitting there.
• The environment is already correct. The right Node and Python, the pinned CUDA, the dev database, the licensed simulator, the hardware in the lab. No container to build, no fixture to fake, no "works locally" gap — because it is local, just not to you.

The reverse split is worth naming too: your cloud agent is still the one that talks to you, holds the context of what you actually want, and reads the result critically. It just stops being the thing that has to hold a shell open.

Why this must be a job, not an exec

remote_exec is for commands that finish in seconds or minutes. It has two caps, and they do different things — the difference matters a lot for an agent run:

• 1 hour of wall-clock time is a hard kill. At the deadline the process tree is terminated. A coding agent halfway through a test loop is simply gone.
• 1 MiB of total output only truncates the reply. The relay does send a best-effort stop request, but it crosses several hops and races the command, so the process may well run to completion. A truncated reply is not evidence the work stopped — and a coding agent streaming its thinking, tool calls and test output reaches 1 MiB fast, so you would lose exactly the log you wanted while the run carried on unobserved.

remote_job_start removes both problems by keeping the output on the machine: the log goes to a file, only bounded slices ever cross the relay (each remote_job_logs reply is capped at 256 KiB, and you page forward by feeding nextOffsetBytes back as offset_bytes), and the exit code is recorded to disk. The log file itself is capped at 256 MiB, and on overflow the agent only stops recording — it never kills the job.

cwd must be an absolute path that already exists — point it at the repo — and env takes string values only. There is no elevated option for jobs: a job runs with exactly the rights remote_exec has on that machine, and an explicit elevated: true is refused rather than quietly downgraded. Full shapes and error codes are in the tool reference and the machine-readable OpenAPI spec.

Copy-paste prompts

Paste these into Claude, ChatGPT, or any client with AI Commander connected. Replace dev-box with your machine's saved alias or its AIC-… session code, and the paths with yours. They are written to be pasted as-is — each one names the machine, so no earlier turn is needed.

1. Start a coding agent run and walk away

The client answers with a jobId in a second or two, while Claude Code on dev-box is still reading the failing test. Write the id down — it is how the run is picked up in a later conversation. The codex CLI is the same shape:

2. Ask a longer run to leave you a result file

The job's log already has everything the coding agent printed, but a diff or a report is easier to collect as a file. Make that the last step of the command:

3. Check on it later, from anywhere

A brand new chat, on a different device. Nothing has to be resumed first:

Forgot the id — which is the normal case a day later:

4. Collect the diff

5. Stop a run that has gone wrong

Cancelling kills the coding agent's whole process tree — including any build or test it had spawned. Note that a job killed by a signal writes no exit marker, so a cancelled run settles on unknown rather than an exit code; that is honest, not a bug.

What it looks like end to end

What survives, and what does not

A remote agent run is durable in the ways that matter, and it is worth being exact about the ways it is not:

• Survives the client. Close the chat, quit the app, sign out of that device. The job does not belong to the conversation.
• Survives the network. Your connection dropping changes nothing on the machine; you just cannot query it until you are back. Same if the machine goes offline for an hour — the process is untouched.
• Survives the conversation. Pick it up from a different chat, a different client, or a script hitting the REST API, with the jobId.
• macOS and Windows: survives the AI Commander agent restarting. On macOS the job reparents to PID 1. On Windows it survives the agent process dying by itself, but not a tree kill — "End task", taskkill /T, or an installer that stops the app and everything it started. Auto-updates go through the installer, so treat a Windows run as interruptible and make it resumable.
• Linux: survives the agent restarting, given systemd and root. Each job is launched into its own transient systemd scope, outside the agent service's control group, so stopping, restarting or upgrading the agent leaves it running. That needs a systemd host with the agent running as root, and without both a restart still ends running jobs — the agent reports which of the two it got in one line at startup. On such a box, upgrade between runs, not during one.
• unknown means unknown. If the process is gone with no recorded exit code — an agent restart, a SIGKILL, the OOM killer, any cancellation on Windows — the outcome genuinely cannot be determined. Never read it as success: check the log, git status, and whatever the run was supposed to write.
• Nothing is kept for you. Finished jobs — metadata, log and workspace — are retained for about a week and then swept automatically. Collect what you want to keep well before that.
• A job outlives you, too. A coding agent started by mistake keeps editing until it finishes or is cancelled. Give it a narrow instruction and a clean tree, and prefer runs that leave changes uncommitted so a human still gates the result.

A machine holds at most 32 running jobs; past that a start is refused with too_many_jobs. Nothing queues, schedules or retries on your behalf — it is your hardware and a real shell.

What's Free, and what needs Pro

Starting a coding agent on a remote machine and following it to the end is the Free path in full: remote_job_start, remote_job_list, remote_job_status, remote_job_logs and remote_job_cancel all work on a free account, across up to 10 usable saved machines. Records beyond that stay saved and visible but are marked planRestricted and refuse operations with reason:"plan_device_limit"; the 10 oldest are the usable ones, and deleting one promotes the next.

Pro ($49/month) raises that to every saved record up to the technical ceiling of 100 machines*, and adds built-in file transfer — which is what you need to bring an artifact back rather than read it in place:

• remote_pull(code, path) copies a file off the machine — a diff, a build, a coverage report — into a temporary relay blob and returns a one-hour download link. A single file must be under 100 MiB, and the stored copy becomes unreadable 24 hours after it is created, fetched or not.
• remote_push(code, blob_id, dest_path) goes the other way — writing a spec, a fixture or a patch onto the machine before the run starts.
• Free and anonymous callers cannot initiate a transfer. The free alternative is the one you already know: have the job upload its own artifact as a final step (aws s3 cp, rclone, scp), or just print the diff through a short remote_exec.

Details and the transfer quotas are in Docs → File transfer.

* 100 machines is a technical ceiling, not a policy limit. Need more? Get in touch — we'll sort it out.

Set it up

On the machine that has the repo, install the agent and make sure your coding agent CLI is installed and signed in there:

Follow the install steps for your platform — verify the signed installer before sudo on Linux.

Connect your AI client, save the machine under an alias like dev-box, and paste one of the prompts above.

Working from Claude Code? The whole procedure on this page — the job command shape, the artifacts to write, what the exit code means — is packaged as a skill you can install in one command: /skill/coding-agent/SKILL.md. The companion skills cover the other long-job workflows: training, backup, deploy and incident triage.

FAQ