> ## Documentation Index
> Fetch the complete documentation index at: https://docs.archil.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Temporal

> Run each Temporal activity on a worker inside its own sandbox, started and deleted by the workflow.

[Temporal](https://temporal.io) is a good fit for agent pipelines: it retries failed steps, tracks long-running work, and fans out to as many tasks as you need. The hard part is where the activities run. An agent that works for an hour holds a worker for the hour, so worker pools have to be sized and autoscaled for the longest task, and every deploy has to wait for in-flight work to drain.

This guide runs each activity on a Temporal worker inside its own Archil [sandbox](https://docs.archil.com/compute/sandboxes/introduction.md) instead. For each piece of work, the workflow starts a sandbox with the work's disk mounted. A Temporal worker in that sandbox polls a task queue of its own, and the workflow sends the activity there, so it runs next to its data, with your image's tools installed. When the activity is done, the workflow deletes the sandbox. The disk is kept, along with everything the work needs to resume.

The complete example is on GitHub at [archil-data/temporal-archil-agents](https://github.com/archil-data/temporal-archil-agents). Its workflow gives each of a list of URLs to a [Claude Agent SDK](https://code.claude.com/docs/en/agent-sdk) agent, which downloads the data and normalizes it into Parquet. A final step merges every agent's output into one file and returns a signed URL that a warehouse such as ClickHouse can load directly.

```text theme={null}
 Temporal                       control worker                Archil
┌──────────────────────┐       ┌──────────────────┐   ┌─────────────────────────────────────────────┐
│ IngestWorkflow       │       │ start_sandbox ───┼─▶ │ sandbox t000 ── /mnt/archil ◀── disk t000    │
│  ├─ task t000 ───────┼─ ─ ─ ─│─ ─ ─ ─ ─ ─ ─ ─ ─ │─ ─│─▶ Temporal worker ─ run_agent_task (Claude)  │
│  ├─ task t001 ───────┼─ ─ ─ ─│─ ─ ─ ─ ─ ─ ─ ─ ─ │─ ─│─▶ sandbox t001: worker ─ run_agent_task      │
│  ├─ ...              │       │ stop_sandbox     │   │                                              │
│  └─ merge ───────────┼─ ─ ─ ─│─ ─ ─ ─ ─ ─ ─ ─ ─ │─ ─│─▶ sandbox merged: worker ─ assemble          │
│                      │       │ share_file       │   │     /mnt/tasks/* (read-only), /mnt/out       │
└──────────────────────┘       └──────────────────┘   └─────────────────────────────────────────────┘
                                 short activities         each sandbox polls a task queue of its own
```

## Prerequisites

* Python 3.10 or later, and a Temporal server the sandboxes can reach over the internet, such as [Temporal Cloud](https://temporal.io/cloud).
* An Archil API key and a region where sandboxes are available (`aws-us-east-1`, `aws-us-west-2`, or `aws-eu-west-1`).
* An [Anthropic API key](https://console.anthropic.com/settings/keys).
* Docker and a container registry Archil can pull from, for the sandbox [image](https://docs.archil.com/compute/sandboxes/images.md).

```bash theme={null}
git clone https://github.com/archil-data/temporal-archil-agents
cd temporal-archil-agents
python -m venv .venv && source .venv/bin/activate
pip install -e .
cp .env.example .env   # fill in your keys and Temporal endpoint
set -a && source .env && set +a
```

## 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](https://docs.archil.com/compute/sandboxes/introduction.md#hosting-network-services). 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:

```python archil_temporal/control.py theme={null}
@activity.defn
async def start_sandbox(self, req: SandboxRequest) -> SandboxWorker:
    mounts = [
        SandboxMountSpec(disk=(await ensure_disk(m.disk)).id, path=m.path, read_only=m.read_only)
        for m in req.mounts
    ]
    sandbox = await get_or_create_sandbox(cfg, req.name, mounts, network=network_policy(cfg, req.allow_hosts))
    queue = sandbox_queue(req.name)
    await ensure_service(sandbox, "temporal-worker", "python3 -m archil_temporal.sandbox_worker", env={
        **temporal_env(cfg),
        "SANDBOX_ID": sandbox.id,
        "SANDBOX_TASK_QUEUE": queue,
    })
    await self._wait_for_worker(queue, identity=f"sandbox:{sandbox.id}")
    return SandboxWorker(sandbox_id=sandbox.id, task_queue=queue)
```

`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:

```python archil_temporal/sandbox_worker.py theme={null}
client = await config.connect(cfg, identity=f"sandbox:{os.environ['SANDBOX_ID']}")
worker = Worker(
    client,
    task_queue=os.environ["SANDBOX_TASK_QUEUE"],
    activities=[run_agent_task, assemble],
    max_concurrent_activities=1,
)
```

## Send the work to its sandbox

In the workflow, every piece of work goes through `in_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:

```python archil_temporal/workflows.py theme={null}
async def in_sandbox(self, sandbox, activity, arg, result_type, *, timeout, retry_policy):
    worker = await workflow.execute_activity_method(ControlActivities.start_sandbox, sandbox, **_CONTROL)
    try:
        result = await workflow.execute_activity(
            activity,
            arg,
            result_type=result_type,
            task_queue=worker.task_queue,
            schedule_to_close_timeout=timeout,
            schedule_to_start_timeout=self.start_timeout,
            heartbeat_timeout=timedelta(minutes=1),
            retry_policy=retry_policy,
        )
    except (Exception, asyncio.CancelledError):
        await workflow.execute_activity_method(ControlActivities.stop_sandbox, sandbox.name, **_CONTROL)
        raise
    await workflow.execute_activity_method(ControlActivities.stop_sandbox, sandbox.name, **_CONTROL)
    return result
```

This is simplified: the version in the repository also starts a new sandbox on the same disk if nothing picks the activity up within `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:

```python archil_temporal/workflows.py theme={null}
outcomes = await asyncio.gather(*[
    self.in_sandbox(agent_sandbox(task), "run_agent_task", task, TaskResult,
                    timeout=timedelta(hours=6),
                    retry_policy=RetryPolicy(maximum_attempts=3, non_retryable_error_types=["AgentGaveUp"]))
    for task in tasks
], return_exceptions=True)
```

The control worker only runs the workflow and activities that take seconds. You can deploy it, scale it, or restart it at any time, without draining it, because no agent runs on it. A sandbox keeps the image it was started with until its work is done, while new work gets the new image, so rolling out a new image never interrupts work in flight.

## 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:

```python archil_temporal/agent.py theme={null}
@activity.defn
async def run_agent_task(task: AgentTask) -> TaskResult:
    sid = session_id(task)  # uuid5 of the workflow ID and task key
    async with heartbeating():
        if session_exists(sid):
            results = [await turn(RESUME_PROMPT, options(resume=sid))]
        else:
            results = [await turn(TASK_PROMPT.format(...), options(session_id=sid))]
        ...
```

| What happens | What happens next | The agent |
| - | - | - |
| Agent finishes | The workflow deletes the sandbox | Done. The disk is kept for the merge step |
| Agent fails (crash, invalid output) | Temporal retries the activity on the same sandbox's worker | Resumes the same Claude session against the same files |
| The worker process in the sandbox dies | The Archil service restarts it, and Temporal retries the activity there | Resumes its Claude session |
| The sandbox itself is lost | Nothing picks the activity up, so the workflow starts a new sandbox on the same disk | Resumes its Claude session |
| Control worker deployed, scaled in, or restarted | Nothing. Another control worker continues the workflow | Keeps running, undisturbed |
| Workflow cancelled | The agent is cancelled through its heartbeat, then the workflow deletes the sandbox | Stopped |

The workflow ends with a cleanup step that deletes any sandbox still there. Each sandbox is also created with a [max TTL](https://docs.archil.com/compute/sandboxes/introduction.md#setting-a-time-to-live), 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](https://docs.archil.com/compute/sandboxes/firewall.md) 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](https://docs.archil.com/compute/sandboxes/firewall.md#credential-brokering), so the sandbox only ever sees a placeholder:

```python archil_temporal/sandboxes.py theme={null}
anthropic = SandboxEgressRule(
    target="api.anthropic.com",
    transform=SandboxEgressTransform(headers={"x-api-key": cfg.anthropic_api_key}),
)
network = SandboxNetwork(egress=SandboxEgressPolicy(
    default="deny",
    allow=[anthropic, cfg.temporal_host, urlparse(task.url).hostname],
))
```

Nothing the agent runs or downloads can read the real key or send it anywhere. Network policies need a paid plan; on the Free plan, set `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](https://docs.archil.com/concepts/sharing-disks.md) to a disk, so this works even while other clients have the task disks open:

```python archil_temporal/workflows.py theme={null}
SandboxRequest(
    name=merged_name(workflow_id),
    mounts=[Mount(disk=merged_name(workflow_id), path="/mnt/out")]
    + [Mount(disk=t.disk, path=f"/mnt/tasks/{t.key}", read_only=True) for t in tasks],
)
```

Inside, DuckDB streams every agent's Parquet files into one, spilling to the Archil disk, so the result can be larger than the sandbox's memory. Then a control activity creates a signed URL for the file, which anyone can download without Archil credentials:

```python archil_temporal/control.py theme={null}
share = await disk.share.aio("merged.parquet", expires_in=24 * 3600)
```

You can load that URL into ClickHouse directly:

```sql theme={null}
INSERT INTO observations
SELECT * FROM url('<download_url>', 'Parquet');
```

## 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:

```bash theme={null}
docker buildx build --platform linux/amd64 -f image/Dockerfile -t ghcr.io/you/archil-agent:v1 --push .
python -m archil_temporal.build_image ghcr.io/you/archil-agent:v1
# prints ARCHIL_IMAGE_ID=...; add it to .env
```

Start a control worker, then start a workflow. With no arguments, the starter uses three public CSV datasets:

```bash theme={null}
python -m archil_temporal.worker
python -m archil_temporal.starter
```

The repository's end-to-end test runs real agents this way. While they work, it replaces the control worker, as a deploy would, and restarts the Temporal worker inside one agent's sandbox. One run printed:

```text theme={null}
2 agents, each on a Temporal worker in its own sandbox; 64s total.
- ✅ all 2 tasks succeeded (failed: none)
- ✅ each agent ran on the Temporal worker inside its own sandbox
- ✅ replacing the control worker mid-run didn't interrupt any agent (t000 finished on attempt 1)
- ✅ after its sandbox's worker restarted, t001 was retried in the same sandbox and resumed its Claude session (attempt 2)
- ✅ merged.parquet downloads from its signed URL with 18332 rows
- ✅ every sandbox was deleted when its work was done (0 left)
```

## 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:

```bash theme={null}
python -m archil_temporal.cleanup <workflow-id> --disks
```

## Next steps

> [card] [Claude Code](https://docs.archil.com/guides/agents/claude-code.md)
>
> Run Claude Code headlessly in a sandbox, with its sessions on a disk.

> [card] [Parallel agents](https://docs.archil.com/guides/agents/parallel-agents.md)
>
> Fork one prepared sandbox per agent and keep the best result.

> [card] [Sandbox firewall](https://docs.archil.com/compute/sandboxes/firewall.md)
>
> Egress policies, credential brokering, and forwarding.

> [card] [Persistent sandboxes](https://docs.archil.com/compute/sandboxes/introduction.md)
>
> Lifecycle, services, time to live, and forking in detail.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.