Skip to main content

Run agents in a cloud sandbox (Daytona)

Daytona runs agent code in an isolated cloud sandbox instead of the runner container. Enable it when your deployment is multi-user or exposed. For the trust model, see Sandbox isolation and security.

Configure Daytona on the runner service only. The variable names and defaults are in the runner reference.

Prerequisites​

  • A Daytona account and an API key.
  • A running deployment. See the Quick start.

1. Enable the provider​

Set the enabled providers and pick a default. To serve both local and Daytona runs from one runner:

AGENTA_RUNNER_ENABLED_SANDBOX_PROVIDERS=local,daytona
AGENTA_RUNNER_DEFAULT_SANDBOX_PROVIDER=daytona

To run only Daytona (no harness ever runs in the runner container):

AGENTA_RUNNER_ENABLED_SANDBOX_PROVIDERS=daytona
AGENTA_RUNNER_DEFAULT_SANDBOX_PROVIDER=daytona

The default must be one of the enabled providers, or the runner fails to start.

2. Set the Daytona credentials​

AGENTA_RUNNER_DAYTONA_API_KEY=<daytona-api-key>
AGENTA_RUNNER_DAYTONA_API_URL=https://app.daytona.io/api
AGENTA_RUNNER_DAYTONA_TARGET=eu

The API key is required whenever daytona is enabled. The URL and target are optional.

For Helm:

agentRunner:
  providers:
    enabled: [local, daytona]
    default: daytona
    daytona:
      apiKeySecretRef:
        name: agenta-runner-daytona
        key: api-key
      apiUrl: https://app.daytona.io/api
      target: eu

Daytona runs start faster from a prepared snapshot that already contains the harness runtimes. Agenta ships the build recipe, not a prebuilt snapshot. Build it in your own Daytona account:

cd services/runner/images/sandbox/daytona
DAYTONA_API_KEY=<daytona-api-key> DAYTONA_TARGET=eu uv run build_snapshot.py --force

The recipe builds a snapshot named agenta-agent-sandbox-v1. Point the runner at it:

AGENTA_RUNNER_DAYTONA_SNAPSHOT=agenta-agent-sandbox-v1

For Helm:

agentRunner:
  providers:
    daytona:
      snapshot: agenta-agent-sandbox-v1

AGENTA_RUNNER_DAYTONA_SNAPSHOT and AGENTA_RUNNER_DAYTONA_IMAGE are mutually exclusive. Set a snapshot or an image, not both. If you set neither, the runner uses its pinned default artifact.

If a snapshot or image is missing the pinned Pi runtime, the runner installs it before the session and logs the repair, so runs still work. Building the snapshot avoids that per-sandbox install cost.

The recipe here builds the runner's sandbox. It does not build the runner service image and it does not build the custom-code evaluator sandbox. To add your own binaries or dependencies to agent runs, see Customize the agent runtime.

Do not reuse the code evaluator's snapshot

If your deployment already runs the custom-code evaluator on Daytona, it has a DAYTONA_SNAPSHOT (or DAYTONA_SNAPSHOT_CODE) of its own, often a plain runtime image such as daytona-small. The two sandboxes may share the Daytona account, meaning the same api key, url, and target, but they cannot share the snapshot. The evaluator's image has no agent harness installed, so an agent booted into it cannot run. Give the agent runner its own agenta-agent-sandbox-v1 snapshot from the recipe above, and never copy DAYTONA_SNAPSHOT into AGENTA_RUNNER_DAYTONA_SNAPSHOT.

4. Make the store reachable​

Daytona sandboxes run in the cloud and mount durable working directories over the public internet. The store endpoint must be publicly reachable, or durable directories degrade to ephemeral ones.

  • Local Docker Compose: enable the with-tunnel profile, which starts an ngrok tunnel to the store. It needs an NGROK_AUTHTOKEN.
  • Railway and Kubernetes: the store endpoint is already public. No tunnel is needed.

See the networking page and the store reference.

5. Smoke test​

Recreate the runner and run an agent with the Daytona sandbox selected. In the runner logs, the startup summary confirms the resolved configuration:

runner providers enabled=[local,daytona] default=daytona
runner daytona target=eu artifact=snapshot:agenta-agent-sandbox-v1

A first run creates a sandbox in your Daytona account. Later turns reuse a warm sandbox until it stops or is deleted. See warm sessions and lifecycle.

Personal subscriptions are not supported on Daytona​

A run that requests Daytona with a self-managed credential (your own Pi, Claude, or ChatGPT/Codex login) is not supported. Personal subscription mounts are local-only and never travel to a sandbox. Use a managed model key for Daytona runs. See Use your own subscription.

Troubleshooting​

A run fails with Sandbox provider 'daytona' is not enabled on this deployment. Add daytona to AGENTA_RUNNER_ENABLED_SANDBOX_PROVIDERS and recreate the runner.

The runner fails to start with AGENTA_RUNNER_DAYTONA_API_KEY is required when 'daytona' is in AGENTA_RUNNER_ENABLED_SANDBOX_PROVIDERS. Set AGENTA_RUNNER_DAYTONA_API_KEY.

The runner fails to start with AGENTA_RUNNER_DAYTONA_SNAPSHOT and AGENTA_RUNNER_DAYTONA_IMAGE are mutually exclusive. Set only one of the two.

A run fails naming a missing Pi executable. The snapshot or image lacks Pi and the runtime install failed. Rebuild the snapshot with the recipe in step 3, or check the runner logs for the install error.

Durable working directories do not persist across turns. The store is not reachable from the sandbox. The runner logs a mount-degradation warning. Make the store public (step 4).