docker-agent-run

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Docker Agent: Running and Operating Agents

Docker Agent：运行和操作 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.

此技能负责 Docker Agent 的操作层面：针对本地配置、别名或注册表引用调用

docker agent run

；选择 agent 在工具调用上的自主程度；将其隔离在沙箱虚拟机中；以及诊断运行失败的原因。它假设

agent.yaml

已存在——有关编写该文件的内容，请参阅相关技能。

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
```
).

在以下情况下激活此技能：

用户希望以交互式或无人值守方式（
```
--exec
```
）运行 agent。
用户正在选择或调试
```
--safety
```
、
```
--yolo
```
或工具调用的审批行为。
用户希望使用
```
--sandbox
```
隔离 agent 的 shell/文件系统访问，或遇到沙箱网络策略错误。
用户想要一个可复用的快捷方式（
```
docker agent alias
```
）、一个隔离的 git worktree（
```
--worktree
```
），或正在调试凭据/模型可用性（
```
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 (
```
eval
```
) — use
```
docker-agent-deploy
```
.

不要使用此技能的情况：

任务使用独立的

sbx run/create/stop/rm

而不是

docker agent run --sandbox

—— 请使用

docker-sandboxes-lifecycle

。

任务是独立的
```
sbx policy
```
或
```
sbx secret
```
配置 —— 请使用
```
docker-sandboxes-network-credentials
```
。当请求仅提到“my sandbox”时，先确定正在使用哪个 CLI，然后再推荐命令。
任务是编写或编辑
```
agent.yaml
```
本身（模型、工具集、子代理） —— 请使用
```
docker-agent-config
```
。
任务是将 agent 作为服务器暴露（
```
serve
```
）、通过注册表共享（
```
share
```
）或评估（
```
eval
```
） —— 请使用
```
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
```

```
docker agent run
```
支持四种
```
--safety
```
模式；请选择既能完成任务又限制最少的模式：
- ```
strict
```
  —— 每次工具调用前都请求审批。
- ```
balanced
```
  —— 自动批准被分类为安全的调用，其余调用需请求审批。
- ```
restricted
```
  —— 自动批准安全调用，直接拒绝其余调用。适用于无人值守/CI 运行，此时没有人可以回答提示。
- ```
autonomous
```
  —— 自动批准一切操作。等同于
```
--yolo
```
  。
永远不要将无人值守运行（cron、CI、服务器端点）默认为
```
autonomous
```
/
```
--yolo
```
。对无人值守运行应使用
```
restricted
```
，这样意外的工具调用会失败关闭，而不是未经审查就执行；
```
autonomous
```
/
```
--yolo
```
仅保留给沙箱化或完全受信任的交互式会话。
bash
```
# CI-safe: unreviewed tool calls are denied, not silently approved.
docker agent run --exec --safety restricted ./agent.yaml "Triage the failing test"
```
将安全默认值烘焙到别名中，这样调用者就不必记住它；请注意，在
```
docker agent run
```
上显式使用 CLI 的
```
--safety
```
/
```
--yolo
```
仍会覆盖别名：
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.

```
--sandbox
```
将 agent 运行在由
```
sbx
```
CLI 管理的隔离微型虚拟机中（这是一个单独的依赖项——请先安装并配置它）。内置工具集启动的所有 shell、文件系统及进程活动都发生在该虚拟机内；只有工作目录（以及，除非使用
```
--no-kit
```
，一个包含技能/提示文件的暂存“kit”）会被挂载进去。例外情况： agent 上声明的本地 stdio MCP 服务器会作为宿主机进程运行在沙箱虚拟机之外——请将任何此类 MCP 服务器视为受信任的宿主机集成，而非沙箱化的。
bash
```
docker agent run --sandbox ./agent.yaml
```
沙箱网络代理默认拒绝所有：只有模型提供方、
```
models.dev
```
以及工具集解析器能推断出的主机是开放的。自定义 MCP 服务器或第三方 API 通常需要显式的白名单条目——请永久添加，而不是每次运行时重新发现：
bash
```
docker agent sandbox allow api.example.com
docker agent sandbox list
docker agent sandbox deny api.example.com
```
更倾向于将
```
runtime: {sandbox: true}
```
烘焙到 agent 自己的
```
agent.yaml
```
中，而不是在每次调用该 agent 时记住
```
--sandbox
```
；但 CLI 上显式的
```
--sandbox=false
```
仍会覆盖配置默认值，以便进行单次调试运行。
沙箱是持久的，并且会在同一工作区的多次运行之间复用——它们不会在会话结束时被销毁。不要期望每次运行都是干净的虚拟机；如果需要干净环境，请更改挂载集（例如新的 kit）以强制重建。

Aliases and default agent

别名与默认 agent

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
```
).

注册一次快捷方式，然后通过名称而不是路径来运行它：
bash
```
docker agent alias add code myorg/notion-expert
docker agent run code
```
对于不带 agent 参数的本地运行，
```
docker agent run
```
会在当前目录中依次查找
```
docker-agent.yaml
```
、
```
docker-agent.yml
```
、
```
docker-agent.hcl
```
（第一个匹配项生效）。仅当这些文件都不存在时，它才会解析
```
default
```
别名，并回退到内置的默认 agent。这些技能中的
```
agent.yaml
```
示例都是显式传递文件名；
```
agent.yaml
```
不是自动发现名称。
为没有项目配置的目录设置一个
```
default
```
别名作为回退。即使存在项目配置，也要显式传入
```
default
```
来选中它：
bash
```
docker agent alias add default ./my-agent.yaml
docker agent run default
```
```
docker agent run <alias>
```
上的 CLI 标志始终会覆盖别名自身存储的选项（例如
```
docker agent run yolo-coder --yolo=false
```
）。

Worktrees

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.

使用
```
--worktree
```
（
```
-w
```
）可以将 agent 的文件编辑与当前检出隔离——它会在一个新的 git worktree 中运行 agent。对于交互式会话，干净的 worktree（没有未提交的更改、未跟踪的文件或新提交）会在会话结束时自动移除；有工作内容的 worktree 会提示你保留或移除。无人值守运行（
```
--exec
```
）无论状态如何，都不会自动清理其 worktree——它会保留在原处以供检查：
bash
```
docker agent run ./agent.yaml --worktree=auth-refactor --worktree-base origin/main
```
```
--worktree
```
不能与
```
--remote
```
或
```
--sandbox
```
结合使用。要恢复 worktree 运行，请传入
```
--session -1
```
（或会话 ID）——不要重新传入
```
--worktree
```
，因为该 worktree 已存在，这样做会失败。

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>
```
.

“没有当前可用的模型”或“模型 ... 尚未拉取”意味着 agent 的提供方没有可用的凭据，或者（对于
```
dmr/
```
）模型尚未被拉取。在修改 YAML 之前，请先运行
```
docker agent doctor ./agent.yaml
```
——它会报告解析后的模型/提供方以及是否找到了凭据。如果缺少凭据，请导出提供方的 API 密钥；如果缺少 DMR 模型，请运行
```
docker model pull <model>
```
。在重试任务前重新运行
```
doctor
```
。
一个只描述计划而不执行计划的 agent，通常是缺少它所需的工具（在
```
agent.yaml
```
中添加
```
type: shell
```
或
```
type: todo
```
），而不是模型故障——请将此问题交回给
```
docker-agent-config
```
。
沙箱运行中出现
```
403 Blocked by network policy
```
错误，意味着目标主机不在白名单中；请使用
```
docker agent sandbox allow <host>
```
。

Related skills

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.

```
references/safety-and-sandbox.md
```
—— 完整的安全模式/标志交互表及沙箱信任边界详情。
```
references/sources.md
```
—— 本技能中每条规则的来源。

Assets

资产

None.

无。

Checks

检查

```
checks/verification.md
```
— Verification runbook for a
```
docker agent run
```
invocation.

```
checks/verification.md
```
——
```
docker agent run
```
调用的验证手册。