Declarative YAML Configuration

AgentsSandbox supports declarative YAML configuration for sandbox creation. Instead of assembling all parameters in code, define the sandbox environment as YAML content and send it through the SDK.

YAML Schema

The YAML schema is a 1:1 mapping of the proto CreateSpec message. Every field in CreateSpec has a corresponding YAML key; no extra fields are allowed.

image: coding-runtime:latest

copies:
  - source: /absolute/path/to/project
    target: /workspace
    exclude_patterns: [".venv", "__pycache__", "node_modules"]

mounts:
  - source: /host/data
    target: /data
    writable: true

builtin_tools: ["claude", "git", "uv", "npm"]

labels:
  team: my-team

envs:
  APP_ENV: production

required_services:
  postgres:
    image: postgres:16-alpine
    envs:
      POSTGRES_DB: app_local
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      start_period: 20s
      start_interval: 1s
      retries: 12
    post_start_on_primary: ["psql -U postgres -c 'CREATE EXTENSION IF NOT EXISTS vector'"]

optional_services:
  redis:
    image: redis:7-alpine
    healthcheck:
      test: ["CMD-SHELL", "redis-cli ping"]
      interval: 5s
      start_period: 10s
      start_interval: 1s
      retries: 6

Field Reference

YAML Key	Proto Field	Type	Description
image	CreateSpec.image	string	Container image for the primary sandbox
copies	CreateSpec.copies	list of CopySpec	Files to copy into the container
mounts	CreateSpec.mounts	list of MountSpec	Bind mounts from host to container
builtin_tools	CreateSpec.builtin_tools	list of string	Built-in resources to provision
required_services	CreateSpec.required_services	map of ServiceSpec	Services that must be healthy before READY
optional_services	CreateSpec.optional_services	map of ServiceSpec	Services started concurrently, not blocking READY
labels	CreateSpec.labels	map of string	Labels attached to the sandbox
envs	CreateSpec.envs	map of string	Env vars on primary container, inherited by all execs

CopySpec Fields

source (absolute host path), target (absolute container path), exclude_patterns (glob patterns to exclude). For detailed copy semantics and symlink handling, see Container Dependency Strategy.

MountSpec Fields

source (absolute host path), target (absolute container path), writable (default: false). For detailed mount semantics, see Container Dependency Strategy.

ServiceSpec Fields

Services use a map format where the YAML key becomes ServiceSpec.name. Fields: image, envs, healthcheck, post_start_on_primary. For service startup behavior and required vs optional semantics, see Container Dependency Strategy.

HealthcheckConfig Fields

Duration fields (interval, timeout, start_period, start_interval) accept a duration string in YAML (e.g., "5s", "1m30s"). The daemon parses this into google.protobuf.Duration.

YAML Key	Description
test	Healthcheck command (e.g., ["CMD-SHELL", "pg_isready"])
interval	Check interval
timeout	Check timeout
retries	Max retry count
start_period	Grace period before checks count
start_interval	Check interval during start period

SDK Usage

Python SDK

sandbox = await client.create_sandbox(config_yaml=yaml_config)

# YAML with parameter overrides
sandbox = await client.create_sandbox(
    config_yaml=yaml_config,
    image="custom:latest",
    labels={"team": "my-team"},
)

Go SDK

sandbox, err := client.CreateSandbox(ctx, sdkclient.WithConfigYAML(configYAML))

// YAML with parameter overrides
sandbox, err := client.CreateSandbox(ctx,
    sdkclient.WithConfigYAML(configYAML),
    sdkclient.WithImage("custom:latest"),
)

Override Semantics

When both YAML and explicit parameters are provided, explicit parameters override YAML values following JSON Merge Patch (RFC 7396) semantics:

Field Type	Override Behavior
Scalar (image)	Non-empty explicit value overwrites YAML
Repeated (mounts, copies, etc.)	Non-empty explicit value replaces YAML entirely
Map (labels, envs)	Key-level merge: explicit keys overwrite; YAML-only keys preserved

Known limitation: callers cannot use explicit parameters to clear a repeated field defined in YAML. Empty values are treated as "not set."

Environment Variable Inheritance

Sandbox-level envs are applied to the primary container at creation time and inherited by all exec commands. Exec env_overrides merge on top with exec keys taking precedence.

Architecture

YAML parsing is implemented in the daemon, not in SDKs. SDKs send raw YAML bytes via config_yaml in CreateSandboxRequest, avoiding duplicating parsing logic. The daemon uses strict parsing that rejects unknown fields.

Service ordering: when converting YAML service maps to proto repeated ServiceSpec, services are sorted alphabetically by name. For required_services, this determines sequential startup order. For optional_services, services start concurrently regardless of sort order.