Background coding agents

Where should a background agent run?

On a machine of its own, one per task. Agents that share a working tree, ports or services can break each other’s test runs. Keeping them apart on one machine takes separate worktrees and service state. A Sandbox is a whole Linux VM. The agent can install packages with sudo, start the project’s services with Docker or systemd, and run the full test suite without reaching another task.

The machine also has to be ready when the agent starts. Cloning the repository and installing dependencies before every task repeats the same setup and depends on reachable package registries. If the agent runs that setup itself, the long install logs also go into the model’s context. Why Ortam puts example numbers on that.

How do agents start on a ready repository?

• Set up one Sandbox per repository. Clone the repository, install the dependencies, pull the images and run the build.
• Take a Snapshot of it. A Snapshot is a saved copy of a Sandbox’s files that never changes. This one is the repository’s ready state.
• Start a Sandbox from the Snapshot for each task. Each copy starts with the Snapshot’s files and writes to its own disk. Fetch the task’s commit, rebuild images built from its source, and grant its Connection before the agent starts.
• Rebuild the Snapshot when its inputs change, such as the lockfile or the images, so copies match what the repository declares.

Keep environments warm builds this with a script that waits for every step and retries without acting twice.

Can several agents work on the same repository at once?

Yes, with a Sandbox each, all started from the repository’s Snapshot. Copies don’t share files. Agents can try different fixes for the same issue, and you keep the one whose tests pass. How many run at once depends on your plan’s limits, which are to be published.

What happens to a long run when your orchestrator restarts?

It keeps running. Your orchestrator, the service that assigns tasks, can disconnect without cancelling a command. A forty-minute test run keeps going while the orchestrator redeploys. The command keeps its result and output. A program reading the output can reconnect and continue where it stopped. Commands covers results and output.

How does the agent use Claude Code or Codex?

Node.js, Python, git, Claude Code and Codex CLI come preinstalled. Grant the Sandbox a Connection to a Claude or ChatGPT account, and the login stays outside the VM. Your own agent works the same way, as a program you run with a command.

What if a task fails halfway?

If the host fails, Ortam brings the Sandbox back from its last completed save when it’s next started. It reports which commands were running and reruns none of them, because only your orchestrator knows which commands are safe to repeat. Have the agent commit and push to a work branch whenever its tests pass. A failure then costs at most the work since the last push. Host failures lists what to check before rerunning a command.

What does an agent cost while it waits for review?

Storage only. Stop the Sandbox once the agent has pushed its work. The VM goes away. The files stay for reviewers, as of the last completed save. A stopped Sandbox’s saved disk costs $0.01 per GB a month. Delete the Sandbox once the change is merged. Prices are planned for launch.

Common questions

Does the agent’s session survive a stop?

Its files do, as of the last completed save. An agent that writes its session to files, as Claude Code and Codex do, keeps it across a stop and start. Memory and running processes don’t survive.

Can an agent run the project’s Docker Compose stack?

Yes. The agent has sudo in its own VM, so it can install and run Docker. Every save keeps Docker, its images and its volumes with the rest of the disk.

Can a person look at what the agent did?

Yes. Open a terminal into the Sandbox through a private link that expires. After the Sandbox stops, its files and its commands’ results stay readable without starting it. The API routes for files and output are to be published.