/docker-agent-run

name: docker-agent-run
description: Use this skill when running a Docker Agent with `docker agent run`, choosing a safety/approval mode, using the `--sandbox` isolation flag, setting up aliases, or troubleshooting a run (missing credentials, worktrees). Even if the user just says they want to "run my agent", "make my agent auto-approve tool calls", "run this agent safely", or "why can't my agent see my API key", this skill applies. Covers `--safety` (strict/balanced/restricted/autonomous), `--yolo`, `--sandbox` and its network allowlist, `--worktree`, `docker agent alias`, and `docker agent doctor`.
license: Apache-2.0
compatibility: Requires the docker-agent CLI plugin (Docker Desktop 4.63+, or standalone via Homebrew/GitHub releases). Sandbox mode (`--sandbox`) additionally requires the `sbx` CLI. Verified against docker-agent as shipped with Docker CLI 29.7.2.

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.

Aliases and default agent

• Register a shortcut once, then run it by name instead of a path:

  docker agent alias add code myorg/notion-expert
  docker agent run code

• For a local run with no agent argument, `docker agent run` discovers

`docker-agent.yaml`, then `docker-agent.yml`, then `docker-agent.hcl` in the current directory (first match wins). Only if none exists does it resolve the `default` alias, falling back to the built-in default agent. The `agent.yaml` examples in these skills pass a filename explicitly; `agent.yaml` is not an auto-discovery name.

• Set the fallback for directories without a project config with a

`default` alias. To select it even when a project config exi