Skip to content
Dreadnode Dreadnode Dreadnode

Task environments

Provision, inspect, and tear down task environments — the per-task sandboxed instances agents run against.

Terminal window
$ dn env <command>

Provision and tear down task environments (sandboxed task instances).

create

Section titled “create”
Terminal window
$ dn env create <task-ref>

Provision a task environment.

task_ref follows the canonical [org/]name[@version] format:

  • my-task — latest visible version
  • [email protected] — exact version
  • acme/my-task — cross-org (must be public or owned by you)
  • acme/[email protected] — cross-org exact version

Use --input name=value repeatedly to bind template variables (values are JSON-decoded when possible, falling back to plain strings).

With --wait, poll until the environment is ready (or reaches a terminal failure/torn-down state). Without it, return as soon as the server accepts the request.

Options

  • <task-ref>, --task-ref (Required)
  • --input — Template variable binding (KEY=VALUE, e.g. —input target=https://example.com; JSON value allowed, repeatable).
  • --secret — Secret id to inject into the sandbox (repeatable).
  • --project-id — Optional explicit project UUID.
  • --timeout-sec — Sandbox lifetime in seconds (capped by org max).
  • --wait (default False) — Poll until the environment reaches a terminal state (ready/failed/torn_down).
  • --wait-timeout-sec, --wait-timeout (default 300.0) — Max seconds to wait for —wait (default 300).
  • --poll-interval-sec, --poll-interval (default 2.0) — Seconds between status polls under —wait.
  • --json (default False)

list

Section titled “list”

Aliases: ls

Terminal window
$ dn env list

List task environments in the current workspace.

Options

  • --state, --status — Filter by sandbox state (repeatable: running, paused, killed, etc.).
  • --page (default 1) — 1-indexed page number.
  • --limit (default 50) — Items per page.
  • --json (default False)

get

Section titled “get”
Terminal window
$ dn env get <environment-id>

Fetch a task environment by id.

Options

  • <environment-id>, --environment-id (Required)
  • --json (default False)

wait

Section titled “wait”
Terminal window
$ dn env wait <environment-id>

Block until an environment reaches a terminal state.

Polls until the environment is ready or torn_down, then prints the current detail. Exits non-zero if the wait times out.

Options

  • <environment-id>, --environment-id (Required)
  • --timeout-sec, --wait-timeout-sec, --wait-timeout (default 300.0) — Max seconds to wait (default 300).
  • --poll-interval-sec, --poll-interval (default 2.0) — Seconds between status polls.
  • --json (default False)

delete

Section titled “delete”

Aliases: rm

Terminal window
$ dn env delete <environment-id>

Tear down a task environment (terminates the sandbox).

Options

  • <environment-id>, --environment-id (Required) — The environment ID.
  • --yes, -y (default False) — Skip the confirmation prompt.

exec

Section titled “exec”
Terminal window
$ dn env exec <environment-id>

Run a shell command inside a provisioned task environment.

Requires the per-environment execute token returned by dn env create. The token is not recoverable later — pass it via --token or DREADNODE_ENVIRONMENT_TOKEN.

Exits with the command’s exit code so the CLI composes in shell scripts.

Options

  • <environment-id>, --environment-id (Required)
  • <*> — Command to run inside the environment (pass after --).
  • --token — Execute token from dn env create. Falls back to $DREADNODE_ENVIRONMENT_TOKEN when unset.
  • --timeout-sec (default 30) — Max execution time in seconds (1-600).
  • --json (default False)