Docker Agent Run

Docker Agent: Running and Operating Agents

Overview

This skill owns the operational side of Docker Agent: invoking docker agent run against a local config, an alias, or a registry reference; choosing how much autonomy the agent gets over tool calls; isolating it in a sandbox VM; and diagnosing why a run fails. It assumes the agent.yaml already exists — see Related skills for authoring it.

When to use this skill

Activate this skill when:

• The user wants to run an agent interactively or headlessly (--exec).
• The user is choosing or debugging --safety, --yolo, or approval behavior for tool calls.
• The user wants to isolate an agent's shell/filesystem access with --sandbox, or hit a sandbox network-policy error.
• The user wants a reusable shortcut (docker agent alias), a scoped git worktree (--worktree), or is debugging credentials/model availability (docker agent doctor).

Do not use this skill when

Do not use this skill when:

• The task uses standalone sbx run/create/stop/rm rather than docker agent run --sandbox — use docker-sandboxes-lifecycle.
• The task is standalone sbx policy or sbx secret configuration — use docker-sandboxes-network-credentials. Establish which CLI is in use before recommending commands when the request only says "my sandbox".
• The task is writing or editing the agent.yaml itself (models, toolsets, sub_agents) — use docker-agent-config.
• The task is exposing an agent as a server (serve), sharing it via a registry (share), or evaluating it (evaluation sessions, --baseline regression gates) — use docker-agent-deploy.

Core guidance

Safety modes

• docker agent run supports four --safety modes; choose the least permissive one that still lets the task finish:
  • strict — ask for approval before every tool call.
  • balanced — auto-approve calls classified as safe, ask for the rest.
  • restricted — auto-approve safe calls, deny the rest outright. Use for unattended/CI runs where no human can answer a prompt.
  • autonomous — approve everything automatically. Equivalent to --yolo.
• Never default an unattended run (cron, CI, a server endpoint) to autonomous/--yolo. Use restricted for unattended runs so an unexpected tool call fails closed instead of running unreviewed; reserve autonomous/--yolo for a sandboxed or fully trusted interactive session.

  # CI-safe: unreviewed tool calls are denied, not silently approved.
  docker agent run --exec --safety restricted ./agent.yaml "Triage the failing test"

• Bake a safety default into an alias so callers don't have to remember it, and note that an explicit CLI --safety/--yolo on docker agent run still overrides the alias:

  docker agent alias add safe-coder myorg/coder --safety balanced

Sandbox isolation

• --sandbox runs the agent inside an isolated microVM managed by the sbx CLI (a separate prerequisite — install and configure it first). All shell, filesystem, and process activity started by built-in toolsets happens inside the VM; only the working directory (and, unless --no-kit, a staged "kit" of skills/prompt files) is mounted in. Exception: a local stdio MCP server declared on the agent runs as a host process outside the sandbox VM — treat any such MCP server as a trusted host integration, not a sandboxed one.

  docker agent run --sandbox ./agent.yaml

• The sandbox network proxy is default-deny: only the model provider, models.dev, and hosts the toolset resolver can infer are open. A custom MCP server or third-party API often needs an explicit allowlist entry — add it permanently rather than re-discovering it every run:

  docker agent sandbox allow api.example.com
  docker agent sandbox list
  docker agent sandbox deny api.example.com

• Prefer baking runtime: {sandbox: true} into the agent's own agent.yaml over remembering --sandbox on every invocation of that agent; an explicit --sandbox=false on the CLI still overrides the config default for a single debug run.
• Sandboxes persist and are reused across runs from the same workspace — they are not torn down when the session ends. Don't expect a clean VM on every run; if you need one, change the mount set (e.g. a new kit) to force recreation.