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. ```bash # 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: ```bash 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. ```bash 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: ```bash 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: ```bash 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 exists, pass `default` explicitly: ```bash docker agent alias add default ./my-agent.yaml docker agent run default ``` - CLI flags on `docker agent run <alias>` always override the alias's own stored options (e.g. `docker agent run yolo-coder --yolo=false`). ### Worktrees - Use `--worktree` (`-w`) to isolate an agent's file edits from your current checkout — it runs the agent inside a fresh git worktree. For an **interactive** session, a clean worktree (no uncommitted changes, untracked files, or new commits) is removed automatically when the session ends; one with work prompts you to keep or remove. A **headless** run (`--exec`) never auto-cleans its worktree, regardless of state — it is left in place for inspection: ```bash docker agent run ./agent.yaml --worktree=auth-refactor --worktree-base origin/main ``` - `--worktree` cannot be combined with `--remote` or `--sandbox`. To resume a worktree run, pass `--session -1` (or the session id) — do not re-pass `--worktree`, which fails because the worktree already exists. ### Troubleshooting - "No model is currently available" or "model ... is not pulled" means the agent's provider has no usable credential, or (for `dmr/`) the model hasn't been pulled. Run `docker agent doctor ./agent.yaml` first — it reports the resolved model/provider and whether credentials were found — before touching the YAML. If credentials are missing, export the provider's API key; if a DMR model is missing, run `docker model pull <model>`. Rerun `doctor` before retrying the task. - An agent that only *describes* a plan instead of executing it is usually missing the tool it needs (add `type: shell` or `type: todo` in `agent.yaml`), not a model failure — hand this back to `docker-agent-config`. - A `403 Blocked by network policy` error inside a sandbox run means the destination isn't allowlisted; use `docker agent sandbox allow <host>`. ## Related skills - For standalone `sbx` lifecycle commands, use `docker-sandboxes-lifecycle`. - For standalone `sbx policy` and `sbx secret`, use `docker-sandboxes-network-credentials`. - For writing or changing the underlying `agent.yaml` (models, toolsets, sub_agents), use `docker-agent-config`. - For serving, sharing, or evaluating the agent, use `docker-agent-deploy`. ## References - `references/safety-and-sandbox.md` — full safety-mode/flag interaction table and sandbox trust-boundary details. - `references/sources.md` — provenance of every rule in this skill. ## Assets - None. ## Checks - `checks/verification.md` — Verification runbook for a `docker agent run` invocation.