Sandbox Profiles

Sandbox profiles live in config.toml under [sandboxes.<name>]. The profile name is the stable identifier used by workspaces, child-session grants, API payloads, and the web Sandbox page.

Good profiles answer four questions before a session starts:

Question	Profile fields
Where does the agent run?	`backend`, provider-specific section, `runtime_root`
How do files move?	`sync_mode`, `include`, `exclude`
What survives after stop?	`persistence`
What can the runtime reach?	`env`, `secret_env`, `network`

Minimal local profile

[defaults]
sandbox = "local"

[sandboxes.local]
backend = "local"
sync_mode = "none"
persistence = "reuse"
runtime_root = "~"

The local backend runs through the host process. It is still a sandbox profile so session metadata, workspace resolution, hooks, and extension Host APIs all use one vocabulary.

Use a local profile when you want AGH's session metadata and hooks, but the host workspace already has the right dependencies and isolation boundary.

Daytona profile

[sandboxes.daytona-dev]
backend = "daytona"
sync_mode = "session-bidirectional"
persistence = "reuse"
runtime_root = "/home/daytona/workspace"

[sandboxes.daytona-dev.env]
NODE_ENV = "development"

[sandboxes.daytona-dev.network]
allow_public_ingress = false
allow_outbound = true
allow_list = ["api.example.test"]
deny_list = ["metadata.google.internal"]

[sandboxes.daytona-dev.daytona]
api_url = "https://app.daytona.io/api"
target = "team-default"
snapshot = "snap-agent-base"
image = "ubuntu:24.04"
class = "cpu-2"
auto_stop = "30m"
auto_archive = "24h"

When both snapshot and image are set, AGH resolves startup from snapshot and preserves image as profile metadata.

Resolution order

Rendering diagram...

Sandbox resolution starts from explicit session or spawn input, then falls back through workspace and default profile settings.

AGH resolves the workspace sandbox first, then [defaults].sandbox, then the local backend fallback. The selected profile is copied into the session metadata so later status, events, hooks, and Host API calls describe the environment that actually launched the agent.

Attach a workspace

agh workspace add /Users/you/project --name project --sandbox daytona-dev
agh workspace edit project --sandbox local

If no workspace sandbox is set, AGH uses [defaults].sandbox. If that is empty, the local backend is used.

Safe spawn grants

Child sessions do not inherit every sandbox profile automatically. Grant the profiles a child may use:

agh spawn \
  --agent coder \
  --ttl-seconds 1800 \
  --sandbox-profile daytona-dev \
  --prompt-overlay "Reproduce the failing build"

The permission policy is serialized as sandbox_profiles, and narrowing rules prevent a child from expanding beyond the parent's allowed profiles. The prompt overlay narrows the child session's instructions; follow-up work still happens through the session surfaces.

API shape

Sandbox profile management is config-backed:

GET /api/settings/sandboxes
PUT /api/settings/sandboxes/daytona-dev
DELETE /api/settings/sandboxes/daytona-dev

List responses use a sandboxes array. Detail responses use a sandbox object.

Profile design checks

Check	Why it matters
Prefer stable profile names	Workspaces, child-session permissions, and API payloads reference the name.
Keep `runtime_root` explicit	It prevents sync and launch behavior from depending on provider defaults.
Use `secret_env` for secrets	Secrets resolve at launch and do not need to be copied into prompts.
Start with narrow sync rules	Broad sync can copy build output, caches, and credentials into the runtime.
Choose persistence on purpose	`reuse` is faster; `transient` is cleaner; `archive` is for later forensics.
Treat network policy as intent	The provider backend still has to enforce the requested network boundary.

Sandbox Overview explains where profiles fit into session launch.
Daytona documents the implemented remote sandbox provider.
Safe Spawn explains child-session narrowing with sandbox grants.
config.toml is the full configuration reference.

On this page