> ## Documentation Index
> Fetch the complete documentation index at: https://agent-compass.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Daytona

> Run remote sandbox sessions with Daytona recipes.

Daytona provides provider-managed remote sandboxes. Use it when you want a remote workspace per task without consuming local compute, especially for SWE-bench and Terminal-Bench smoke tests.

## Official Setup Links

| Need                                   | Link                                                           |
| -------------------------------------- | -------------------------------------------------------------- |
| Create an account and manage sandboxes | [Daytona Dashboard](https://app.daytona.io/)                   |
| Create API keys                        | [Daytona API keys page](https://app.daytona.io/dashboard/keys) |
| Getting started docs                   | [Daytona documentation](https://www.daytona.io/docs/en/)       |
| API key docs                           | [Daytona API keys](https://www.daytona.io/docs/en/api-keys/)   |

## First-Time Setup

1. Create a Daytona account from the official dashboard.
2. Open the API keys page and create a key with sandbox permissions.
3. Export the key in the shell that runs AgentCompass.
4. Run a single task before increasing concurrency.

```bash theme={"system"}
export DAYTONA_API_KEY="..."
export DAYTONA_API_URL="https://your-daytona-api"  # optional
export DAYTONA_TARGET="your-target"               # optional
```

`DAYTONA_API_KEY` is the only value most users need. `DAYTONA_API_URL` and `DAYTONA_TARGET` are optional and should be set only when your Daytona workspace requires a non-default API endpoint or target.

AgentCompass authentication precedence is:

| Source                               | Use when                                                         |
| ------------------------------------ | ---------------------------------------------------------------- |
| `environments.daytona.api_key`       | You intentionally keep credentials in a private `--config` file. |
| `DAYTONA_API_KEY`                    | Recommended for shell sessions, CI, and shared scripts.          |
| `DAYTONA_API_URL` / `DAYTONA_TARGET` | Optional endpoint and target overrides.                          |

<Note>
  Do not commit Daytona API keys to `config/defaults.yaml`. Use environment variables or a private config file passed with `--config`.
</Note>

## Verify Credentials

The most useful verification is an AgentCompass smoke test because it checks credentials, sandbox startup, recipe image selection, file operations, and harness execution together.

## Single Terminal-Bench Instance

```bash theme={"system"}
agentcompass run \
  terminal_bench_2 \
  terminus2 \
  "$MODEL_NAME" \
  --env daytona \
  --benchmark-params '{"sample_ids":["<task-id>"]}' \
  --model-base-url "$MODEL_BASE_URL" \
  --model-api-key "$MODEL_API_KEY"
```

This is the recommended provider smoke test because it runs one task and lets the recipe infer the task image.

## Provider Params

Common Daytona overrides live under `environments.daytona` or `--env-params`:

| Field                                            | Default                                   | How to use it                                                                                                                       |
| ------------------------------------------------ | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `api_key`                                        | `DAYTONA_API_KEY`                         | Prefer the environment variable; use this field only in a private config.                                                           |
| `api_url` / `target`                             | Environment variables or provider default | Set only for a self-hosted endpoint or an explicitly selected target.                                                               |
| `jwt_token` / `organization_id`                  | Environment variables or unset            | Supply them only when the Daytona deployment requires those authentication fields.                                                  |
| `connection_pool_maxsize`                        | `250`                                     | Keep the default unless a high-concurrency runner exhausts the provider client's HTTP pool.                                         |
| `name`                                           | Generated                                 | Use a stable name only for focused debugging; concurrent tasks need unique sandboxes.                                               |
| `language`                                       | `python`                                  | Accepts `python`, `typescript`, or `javascript`; a benchmark image normally determines the actual task runtime.                     |
| `image`                                          | Unset                                     | Let a recipe select the task image. Set it for an intentional custom-image run.                                                     |
| `snapshot`                                       | Unset                                     | Use a maintained Daytona snapshot when it replaces the complete task image and workspace contract.                                  |
| `dockerfile` / `compose_file`                    | Unset                                     | Reserved configuration fields; the direct provider currently rejects these strategies. Build a single image first.                  |
| `os_user`                                        | Provider default                          | Set only when the image requires a specific user for workspace permissions or installed tools.                                      |
| `auto_stop_interval`                             | `15`                                      | Provider auto-stop setting. Increase only when valid idle periods would otherwise stop a running task.                              |
| `auto_archive_interval` / `auto_delete_interval` | Unset                                     | Use for provider lifecycle policy, not as a replacement for normal AgentCompass cleanup.                                            |
| `ephemeral`                                      | `false`                                   | Enable when the Daytona account and image workflow are designed for disposable ephemeral sandboxes.                                 |
| `delete_on_close`                                | `true`                                    | Set `false` for focused debugging; AgentCompass stops rather than deletes the sandbox on close.                                     |
| `default_workspace_root`                         | `workspace/`                              | Prefer the recipe-provided root for public benchmarks.                                                                              |
| `env_variables`                                  | `{}`                                      | Inject sandbox variables. Keep credentials in environment references or a private config.                                           |
| `labels`                                         | `{}`                                      | Add provider-side labels for ownership, cost tracking, or cleanup automation.                                                       |
| `resources`                                      | `{}`                                      | Pass integer `cpu`, `memory`, `disk`, or `gpu` values supported by the selected Daytona target. Start from task metadata and quota. |
| `sandbox_start_timeout`                          | `60`                                      | Increase when a valid image or snapshot consistently needs longer to start.                                                         |
| `operation_timeout`                              | `1800`                                    | Increase only for legitimate long provider operations; harness command limits remain separate.                                      |

The provider also exposes Daytona-native `network_block_all`, `network_allow_list`, and `domain_allow_list` creation
fields. Prefer [provider-neutral phase policies](/en/user_guide/modules/environments/network), especially when setup, rollout, and
verification need different access. Daytona cannot mix domain and IPv4 network allowlists in one policy.

## SWE-bench Verified

```bash theme={"system"}
agentcompass run \
  swebench_verified \
  mini_swe_agent \
  "$MODEL_NAME" \
  --env daytona \
  --benchmark-params '{"sample_ids":["astropy__astropy-12907"]}' \
  --model-base-url "$MODEL_BASE_URL" \
  --model-api-key "$MODEL_API_KEY"
```

Recipes set compatible images and workspaces for supported benchmark/provider pairs. Pass `--env-params` only for deliberate overrides.

Use `agentcompass config docs env daytona` to inspect the live field types and defaults in the installed revision.

## Related Pages

* [Environments Overview](/en/user_guide/modules/environments/overview)
* [Network Policy](/en/user_guide/modules/environments/network)
* [Sandbox Resource Limits](/en/user_guide/modules/environments/resource_limits)
* [agentcompass run](/en/user_guide/cli/run#control-task-execution)
* [Configuration Reference](/en/user_guide/overview#configuration-files-and-precedence)