Runtimes
Manage agent runtime environments.
$ dn runtime <command>Manage agent runtime environments.
Aliases: ls
$ dn runtime listList runtimes in your workspace.
Runtimes you do not own are listed too — reads span the workspace — and are
marked read-only, since starting, pausing, resuming or resetting one
answers 403. Use --mine to leave them out.
Options
--state,--status— Filter by runtime status (idle,running,paused). Repeatable; values combine with OR. Also accepts--status. [choices: idle, running, paused]--project-id— Only show runtimes belonging to this project UUID.--mine(defaultFalse) — Only show runtimes you own, and can therefore operate.--limit(default50) — Maximum results to show. Server pages are walked internally.--json(defaultFalse) — Output as JSON.
$ dn runtime get <runtime-id>Get details of a runtime.
Options
<runtime-id>,--runtime-id(Required) — Runtime key or UUID, as shown bydn runtime list.--json(defaultFalse) — Output as JSON.
create
Section titled “create”Aliases: new
$ dn runtime createEnsure a runtime exists for a project or the workspace default project.
Idempotent — re-running against an existing runtime returns it unchanged. Re-running with a different config is a conflict, not an update.
Options
<project-ref>,--project-ref— Project key or UUID. Defaults to the active project scope, then workspace default.--key— Runtime key. Required with —name when no project is resolved.--name— Runtime display name. Required with —key when no project is resolved.--description— Optional runtime description.--file— Load runtime.yaml from a file or directory.--egress,--empty-egress— Outbound destination this runtime’s sandbox may reach (e.g. —egress target.example.com, —egress ‘*.internal.corp’, —egress 10.20.0.0/16; repeatable). Adds to any sandbox.egress.allow from —file. A declaration can only narrow what the deployment already permits, and declaring anything restricts the sandbox to what is named plus the platform destinations the platform derives. Pass —empty-egress to declare a scope that names nothing, restricting the sandbox to the platform destinations alone.--json(defaultFalse) — Output as JSON.
$ dn runtime startStart a runtime, creating it first when the target flow requires it.
A cold start provisions a sandbox and can take a couple of minutes. Every successful call returns the runtime’s credential; retry the command if its response is lost.
Options
<target>,--target— Runtime key/UUID, or project key/UUID. Resolved as a runtime first. Defaults to the active project scope.--runtime-id— Start a specific runtime by key or UUID. Mutually exclusive with <target>.--key— Runtime key to ensure before starting.--name— Runtime name to ensure before starting.--description— Optional runtime description when ensuring a runtime.--file— Load runtime.yaml from a file or directory.--json(defaultFalse) — Output as JSON.
$ dn runtime pause <runtime-id>Pause a runtime’s sandbox, preserving its state.
Options
<runtime-id>,--runtime-id(Required) — Runtime key or UUID, as shown bydn runtime list.--json(defaultFalse) — Output as JSON.
resume
Section titled “resume”$ dn runtime resume <runtime-id>Resume a paused runtime’s sandbox.
Resuming does not return an access token. Run dn runtime start afterward
when the credential is needed.
Options
<runtime-id>,--runtime-id(Required) — Runtime key or UUID, as shown bydn runtime list.--json(defaultFalse) — Output as JSON.
keepalive
Section titled “keepalive”$ dn runtime keepalive <runtime-id>Push back a running runtime’s expiry.
Options
<runtime-id>,--runtime-id(Required) — Runtime key or UUID, as shown bydn runtime list.--extend-seconds(default300) — Seconds to extend the runtime’s expiry by.--json(defaultFalse) — Output as JSON.
$ dn runtime reset <runtime-id>Discard a runtime’s sandbox, returning the runtime to idle.
The runtime, its configuration, and its capability bindings survive; only
the compute instance and everything inside it is destroyed. This is how a
configuration change is applied to a running runtime — start never
rebuilds implicitly.
Options
<runtime-id>,--runtime-id(Required) — Runtime key or UUID, as shown bydn runtime list.--yes,-y(defaultFalse) — Skip the confirmation prompt.--json(defaultFalse) — Output as JSON.
config-get
Section titled “config-get”Aliases: config
$ dn runtime config-get <runtime-id>Show a runtime’s durable configuration.
Workspace read access is enough to read a config; only the owner may replace one. Use —json for the full document — the summary shows the fields with a CLI surface.
Options
<runtime-id>,--runtime-id(Required) — Runtime key or UUID, as shown bydn runtime list.--json(defaultFalse) — Output as JSON.
config-set
Section titled “config-set”$ dn runtime config-set <runtime-id>Replace a runtime’s durable configuration.
Only the runtime’s owner may call this, and it does not alter an already running sandbox — the new configuration applies from the next start.
A narrowing egress declaration needs no permission beyond owning the runtime, and is re-checked against the deployment’s egress floor at start, so a target the floor denies fails the start naming the target rather than starting without it.
Options
<runtime-id>,--runtime-id(Required) — Runtime key or UUID, as shown bydn runtime list.--file— Replace the whole configuration with this runtime.yaml. Wholesale, not a merge: a field the file omits is reset to its default. Without —file the stored configuration is edited in place and every other field is preserved.--egress,--empty-egress— Outbound destination this runtime’s sandbox may reach (e.g. —egress target.example.com, —egress ‘*.internal.corp’, —egress 10.20.0.0/16; repeatable). Adds to the scope already stored, or to —file’s when given. Pass —empty-egress to declare a scope that names nothing, restricting the sandbox to the platform destinations alone.--yes,-y(defaultFalse) — Skip the confirmation prompt when replacing wholesale with —file.--json(defaultFalse) — Output as JSON.