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. Use dn runtime config-set to change one.

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 and the platform resolves the latest version once, at create time, and pins it into the stored configuration. 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
  exposed_ports:
    - 8080
    - 9229

cpu_cores and memory_mb size the provider instance. exposed_ports lists ports the platform should surface for host-side access. The deprecated workspace_mount field is accepted for existing manifests but ignored; the sandbox workspace is always a local directory. Defaults and valid ranges are in the manifest reference.

Outbound network scope

sandbox.egress.allow bounds what this runtime’s sandbox may reach on the network.

sandbox:
  egress:
    allow:
      - target.example.com
      - '*.internal.corp'
      - 10.20.0.0/16

# or from flags, which add to whatever the file declares
dn runtime create --file runtime.yaml --egress target.example.com

# declare a scope that names nothing — platform destinations only
dn runtime create --key analyst --name Analyst --empty-egress

Declaring anything restricts the sandbox to what you name plus the platform’s own destinations, so an empty list and an omitted key mean different things. The scope covers only the sandbox this runtime starts — a capability borrowed from this runtime does not carry the scope into an evaluation’s agent sandbox.

A declaration only narrows what your deployment already permits, and it is re-checked at every start. If the deployment stops permitting a target after you save it, start fails naming the target rather than starting the sandbox without it. See Scoping what a sandbox can reach.

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
  exposed_ports:
    - 8080

runtime_server:
  env:
    LOG_LEVEL: info

metadata:
  labels:
    team: analysis

Changing a live runtime

Read the stored configuration, then replace it:

# what is stored today
dn runtime config-get analyst

# edit one field, preserve the rest
dn runtime config-set analyst --egress staging.example.com

# replace the whole document from a file
dn runtime config-set analyst --file runtime.yaml

The two forms differ in what they touch. --file is wholesale: a field the file omits is reset to its default, which is why it confirms before writing (--yes skips the prompt). Without --file, flags edit the stored configuration in place and every other field is preserved.

The file carries configuration only. Identity fields — key, name, description — belong to create and are rejected here, so strip them from a manifest you also use to create the runtime, or keep a separate config-only file.

A declared egress target is checked against the deployment’s floor when you save the configuration, so a denied target fails config-set naming it, and checked again at every start.

Reading a config needs workspace read access; replacing one requires owning the runtime. Neither alters a sandbox that is already running — the new configuration applies from the next start.