docker-agent-run
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`.
docker · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add docker/skills --skill 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/rmrather thandocker agent run --sandbox— usedocker-sandboxes-lifecycle. - The task is standalone
sbx policyorsbx secretconfiguration — usedocker-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.yamlitself (models, toolsets, sub_agents) — usedocker-agent-config. - The task is exposing an agent as a server (
serve), sharing it via a registry (share), or evaluating it (eval) — usedocker-agent-deploy.
Core guidance
Safety modes
docker agent runsupports four--safetymodes; 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. Userestrictedfor unattended runs so an unexpected tool call fails closed instead of running unreviewed; reserveautonomous/--yolofor 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/--yoloondocker agent runstill overrides the alias:docker agent alias add safe-coder myorg/coder --safety balanced
Sandbox isolation
--sandboxruns the agent inside an isolated microVM managed by thesbxCLI (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 ownagent.yamlover remembering--sandboxon every invocation of that agent; an explicit--sandbox=falseon 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 rundiscoversdocker-agent.yaml, thendocker-agent.yml, thendocker-agent.hclin the current directory (first match wins). Only if none exists does it resolve thedefaultalias, falling back to the built-in default agent. Theagent.yamlexamples in these skills pass a filename explicitly;agent.yamlis not an auto-discovery name. - Set the fallback for directories without a project config with a
defaultalias. To select it even when a project config exists, passdefaultexplicitly: