Configuration

Keep a runtime's defaults, capabilities, secrets, and resource shape in a versioned runtime.yaml that survives sandbox replacement.

Every runtime has a durable configuration that persists across sandbox lifecycle. Start from a runtime.yaml so the configuration lives in source control — the CLI loads it, resolves secret selectors against your workspace, and submits the normalized config to the platform.

For the exhaustive schema, see the manifest reference.

A minimal manifest

key: analyst
name: Analyst Runtime

defaults:
  agent: planner
  model: openai/gpt-4.1-mini

# ensure the runtime exists in the active project
dn runtime create --file runtime.yaml

# ensure and start in one step
dn runtime start --file runtime.yaml

--file also accepts a directory, in which case the CLI loads runtime.yaml from inside it. Explicit CLI flags (--key, --name, --description) override manifest identity values.

If the runtime already exists with a different durable configuration, the ensure/create call fails instead of silently mutating it — edit through the config endpoint to change a live runtime.

Identity

The manifest can set identity inline or under an identity: block — pick one and stay consistent.

# inline
key: analyst
name: Analyst Runtime
project: lab
description: Daily driver for the analysis team.

# nested
identity:
  key: analyst
  name: Analyst Runtime
  project: lab
  description: Daily driver for the analysis team.

project accepts a project key or a project UUID. If you omit it, the CLI uses the active project scope on your profile, then falls back to the workspace default.

Defaults for new sessions

defaults sets the agent, model, capability, and system prompt that new sessions inherit when they don’t specify their own.

defaults:
  capability: dreadairt
  agent: planner
  model: openai/gpt-4.1-mini
  system_prompt: |
    You are a security research assistant. Prefer read-only commands
    and ask before escalating.

Sessions can still override these per launch — the defaults are the floor, not a ceiling.

Capability bindings

List the capabilities this runtime should always have installed. Bindings persist across pause, resume, reset, and reprovision — configure them once and they come back every time.

capabilities:
  - name: dreadairt
    version: '0.4.1'
    enabled: true
  - name: cookbook
    enabled: false

version is optional; omit it to track the latest. enabled: false installs the capability but leaves it inactive.

See Capabilities for authoring, and Installing capabilities for the ad-hoc install flow if you want to attach capabilities without editing the manifest.

Secrets

Declare secrets two ways. The CLI supports name-based selectors with glob patterns; the platform stores IDs.

# by name selector — CLI resolves against your workspace secrets
secrets:
  selectors:
    - OPENAI_API_KEY
    - "AWS_*"

# by explicit UUID — exact and source-controlled
secrets:
  secret_ids:
    - 11111111-2222-3333-4444-555555555555

Selectors resolve when the CLI submits the manifest. Exact names are strict (the CLI fails if a name isn’t configured); globs are best-effort (silently skipped when nothing matches). The two forms are mutually exclusive in a manifest.

Secrets you declare here are injected as environment variables into the sandbox the next time it starts.

Resources and sandbox shape

resources:
  cpu_cores: 4
  memory_mb: 8192

sandbox:
  timeout_seconds: 1800
  workspace_mount: true
  exposed_ports:
    - 8080
    - 9229

cpu_cores and memory_mb size the provider instance. workspace_mount controls whether your project workspace is mounted read-write. exposed_ports lists ports the platform should surface for host-side access. Defaults and valid ranges are in the manifest reference.

Runtime server environment

Environment variables for the sandbox’s runtime server process (not the agent’s own environment — that’s what secrets is for).

runtime_server:
  env:
    LOG_LEVEL: debug
    HTTPS_PROXY: http://proxy.internal:3128

Metadata labels

Free-form string labels attached to the runtime record for search, filtering, and inventory purposes.

metadata:
  labels:
    team: analysis
    environment: staging

Full example

key: analyst
name: Analyst Runtime
project: lab
description: Daily driver for the analysis team.

defaults:
  capability: dreadairt
  agent: planner
  model: openai/gpt-4.1-mini

capabilities:
  - name: dreadairt
    version: '0.4.1'

secrets:
  selectors:
    - OPENAI_API_KEY
    - 'AWS_*'

resources:
  cpu_cores: 4
  memory_mb: 8192

sandbox:
  timeout_seconds: 1800
  workspace_mount: true
  exposed_ports:
    - 8080

runtime_server:
  env:
    LOG_LEVEL: info

metadata:
  labels:
    team: analysis