runtime.yaml reference

Every field of the runtime manifest, accepted values, and defaults.

The runtime.yaml manifest describes a runtime’s durable configuration — the identity record plus the config that persists across sandbox lifecycle. This page enumerates every field the CLI and platform accept.

For authoring guidance, see Configuration.

Top-level fields

Field	Type	Required	Default	Notes
`version`	string	No	`v2`	Must be `v2`. Rejected if any other value.
`capabilities`	list	No	`[]`	Capability bindings installed on the runtime. See below.
`defaults`	object	No	`{}`	Defaults new sessions inherit when they don’t specify their own. See below.
`secrets`	object	No	`{}`	User secrets to inject as environment variables in the sandbox. See below.
`build`	object	No	`{}`	Build profile and source for the sandbox image. See below.
`resources`	object	No	`{}`	CPU and memory shape of the sandbox. See below.
`sandbox`	object	No	`{}`	Sandbox lifecycle and host-side exposure. See below.
`runtime_server`	object	No	`{}`	Environment for the runtime server process inside the sandbox. See below.
`metadata`	object	No	`{}`	Free-form labels attached to the runtime record.

Identity

Identity lives outside the durable configuration. Set fields inline at the top level or under an identity: block — the two forms are mutually exclusive per field.

Field	Type	Required	Notes
`project`	string	No	Project key or UUID. Falls back to active profile project, then workspace default.
`key`	string	When project is omitted	Workspace-scoped runtime key.
`name`	string	When project is omitted	Display name (1–100 characters).
`description`	string	No	Free-text description (up to 500 characters).

`capabilities[]`

Each entry is a capability binding.

Field	Type	Required	Default	Notes
`name`	string	Yes	—	Capability name. Must be non-empty.
`version`	string	No	latest	Pin to a specific version; omit to track the latest.
`enabled`	boolean	No	`true`	`false` installs the capability but leaves it inactive.

`defaults`

Field	Type	Default	Notes
`capability`	string	none	Capability name used as the default agent source for new sessions.
`agent`	string	none	Agent name used when a session doesn’t specify one.
`model`	string	none	Model identifier used when a session doesn’t specify one.
`system_prompt`	string	none	Extra system instructions appended to new sessions.

`secrets`

Specify one of secret_ids or selectors. Mixing both in one manifest fails validation.

Field	Type	Notes
`secret_ids`	list of UUIDs	Exact IDs of configured workspace secrets.
`selectors`	list of strings	CLI-only. Name-based patterns (glob `*`, `?`, `[...]`) resolved against workspace secrets.

The CLI resolves selectors into secret_ids before submitting the manifest. Exact selector names are strict; glob selectors are best-effort. Duplicates are de-duplicated.

`build`

Field	Type	Default	Notes
`profile`	string	`default`	Build profile name. Must be non-empty.
`provider`	`auto` \| `docker` \| `e2b`	`auto`	Which sandbox provider to target.
`source.kind`	string	`builtin`	Source type for the build.
`source.ref`	string	`runtime`	Source reference within `source.kind`.

`resources`

Field	Type	Default	Range
`cpu_cores`	integer	`2`	1–32
`memory_mb`	integer	`2048`	512–131072

`sandbox`

Field	Type	Default	Notes
`timeout_seconds`	integer	none	Sandbox expiry in seconds. Minimum 60. Omit for provider default.
`workspace_mount`	boolean	`true`	Mount the project workspace into the sandbox.
`exposed_ports`	list of ints	`[]`	Ports to expose for host-side access. Must be 1–65535. Deduplicated.

`runtime_server`

Field	Type	Default	Notes
`env`	mapping of string → string	`{}`	Environment variables for the runtime server process.

Use this for operational variables that control how the runtime server itself behaves (log level, proxy configuration). For secrets the agent should see, use secrets instead.

`metadata`

Field	Type	Default	Notes
`labels`	mapping of string → string	`{}`	Free-form labels for search, filtering, and inventory.

Example

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

version: v2

defaults:
  capability: dreadairt
  agent: planner
  model: openai/gpt-4.1-mini
  system_prompt: |
    You are a security research assistant.

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

secrets:
  selectors:
    - OPENAI_API_KEY
    - 'AWS_*'

build:
  profile: default
  provider: auto

resources:
  cpu_cores: 4
  memory_mb: 8192

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

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

metadata:
  labels:
    team: analysis
    environment: staging