Prerequisites
- Python 3.10 or later, and a Temporal server the sandboxes can reach over the internet, such as Temporal Cloud.
- An Archil API key and a region where sandboxes are available (
aws-us-east-1,aws-us-west-2, oraws-eu-west-1). - An Anthropic API key.
- Docker and a container registry Archil can pull from, for the sandbox image.
Start a sandbox for each piece of work
Starting a sandbox is a short activity,start_sandbox, that runs on a control worker. It finds or creates the sandbox for the work, with the work’s disk mounted, and starts a Temporal worker in it as an Archil service. The service restarts the worker if it ever exits. The sandbox and its task queue are named after the work, so a retried start_sandbox finds the same sandbox instead of creating a second one:
archil_temporal/control.py
ensure_service runs archil services create in the sandbox, unless the service already exists. _wait_for_worker returns once the sandbox’s worker shows up as a poller on its queue, so the activity sent there next starts right away.
The worker inside the sandbox is an ordinary Temporal worker. It runs your activities, and polls only its sandbox’s queue:
archil_temporal/sandbox_worker.py
Send the work to its sandbox
In the workflow, every piece of work goes throughin_sandbox: start the sandbox, run the activity on the sandbox’s queue, and delete the sandbox when the activity has finished, failed, or been cancelled:
archil_temporal/workflows.py
schedule_to_start_timeout, which means the sandbox was lost. It doesn’t use finally, because a finally block also runs when a control worker shuts down and Python closes the workflow’s coroutines. The workflow isn’t over then: another control worker carries on with it, and the sandbox must stay.
Each agent task, and the merge at the end, is one call:
archil_temporal/workflows.py
Resume from the disk
Everything the agent needs to resume lives on its disk, mounted at/mnt/archil: its downloads, its output, and Claude Code’s session transcript (CLAUDE_CONFIG_DIR=/mnt/archil/.claude). The session ID is derived from the workflow ID and the task key, so any attempt finds the conversation an earlier one started, and continues it:
archil_temporal/agent.py
The workflow ends with a cleanup step that deletes any sandbox still there. Each sandbox is also created with a max TTL, which pauses it if nothing ever deletes it, such as when the workflow is terminated; a paused sandbox uses no CPU.
Keep the API key out of the sandbox
The agent runs with every permission in its sandbox, and it downloads data from URLs it’s given. A network policy limits what it can reach: Temporal, the Anthropic API, the host of its URL, and nothing else. Archil’s egress proxy adds the Anthropic API key to the agent’s requests on the way out, using credential brokering, so the sandbox only ever sees a placeholder:archil_temporal/sandboxes.py
RESTRICT_EGRESS=false in .env to pass the key into the sandbox instead.
Merge next to the data
When the agents are done, the merge runs the same way, in one more sandbox. That sandbox mounts every task’s disk read-only, plus one writable output disk. A read-only mount doesn’t take exclusive access to a disk, so this works even while other clients have the task disks open:archil_temporal/workflows.py
archil_temporal/control.py
Run it
Build the sandbox image, which installs the example’s package with the Claude Agent SDK, pandas, pyarrow, and DuckDB, and register it with Archil once:Clean up
Each task’s disk is kept after the workflow finishes, so you can read an agent’s files and transcript afterwards. To delete a workflow’s disks, and any sandboxes left by a workflow that was terminated rather than cancelled:Next steps
Claude Code
Run Claude Code headlessly in a sandbox, with its sessions on a disk.
Parallel agents
Fork one prepared sandbox per agent and keep the best result.
Sandbox firewall
Egress policies, credential brokering, and forwarding.
Persistent sandboxes
Lifecycle, services, time to live, and forking in detail.