dkagent

📖 English documentation: README.en.md

一个 bash 命令，把任意目录变成隔离的 AI Agent 运行环境。

基于 Docker 的 AI Agent CLI 运行沙箱。一行命令拉起容器，内置 Claude Code、Gemini CLI、Codex、Pi、OpenCode 五大 Agent，支持逐目录只读挂载、多镜像 profile 切换，并用 🟢🟡🔴 三色让你一眼看清每次给了 Agent 多大权限。

dkagent 本质上就是一个 ~500 行的 bash 脚本，不包含任何自己实现的沙箱逻辑。它做的事只有一件：把 Docker 已有的隔离能力编排成好用的命令行。

• 安全性 = Docker 本身：容器隔离靠的是 Docker 原生的 namespace / cgroup / bind mount，这些是经过十年生产验证的内核机制。dkagent 不重新发明它们，只是按需调用。
• 风险等级 = 你挂了什么：每个 🟢🟡🔴 等级直接对应挂载卷的范围，没有任何隐藏逻辑。--dry-run 能让你在运行前看到完整的 docker run 命令，所见即所得。
• 可审计：整个工具就是一个脚本，没有后台进程、没有 daemon、没有运行时注入。读一遍源码就能完全理解它对你系统做了什么。

这也是为什么 dkagent 能放心地把 --dangerously-skip-permissions 交给 Agent——真正的安全边界是容器，不是 Agent 自己的权限确认。

1. 逐目录读写控制，一行命令搞定 命令行直接挂载多个目录，每个目录独立指定只读或可写，无需写配置文件：

# 原始项目只读参考，副本目录可读写
dkagent -m ./original -r -m ./workspace/my-copy claude

"参考 A 项目代码、改 B 项目"这种场景一行命令就成立——只读目录靠 Docker bind mount 钉死在内核层，写不进去。

2. 多 Agent 统一入口 —— 一套环境切换五个 Agent 不用为每个 Agent 单独配环境、装依赖。dkagent 把 Claude / Gemini / Codex / Pi / OpenCode 都装进同一个镜像，持久化 Home 卷保留所有 Agent 的登录凭证和配置，切换无感。

3. Kali 工具链就绪 —— 安全研究向开箱即用 默认镜像基于 Kali Linux，内置 Playwright 浏览器、nmap、fd、ripgrep、oh-my-zsh 等全套工具。需要更轻量？切换到 slim profile（基于 Debian slim，体积小三分之二）。

推荐先用 slim 镜像（基于 Debian slim，体积小、构建快，约 2-3 分钟），跑通后再按需切换 Kali 镜像。

# 1. 安装 CLI 工具（会自动创建 ~/.config/dkagent/ 并拷贝 .env 模板）
chmod +x install.sh && ./install.sh

# 2. 填入 API Keys（首次安装后在此文件编辑，切勿提交 git）
vi ~/.config/dkagent/.env

# 3. 构建 slim 镜像（快速，约 2-3 分钟）
docker build -t dkagent-slim -f dockerfiles/Dockerfile.slim .

# 4. 在任意目录下，一行命令拉起
cd ~/my-project
dkagent -p slim claude --dangerously-skip-permissions

关于 --dangerously-skip-permissions：因为 dkagent 已用容器做了隔离，可以放心把这个"全自动"标志交给 Agent，让它在容器内免确认地执行命令——这正是容器化的核心收益。

Kali 镜像内置完整安全研究工具链（nmap、metasploit、Playwright 等），但体积约 10GB，首次构建需要 15-30 分钟（取决于网络）：

docker compose build              # 构建 kali 镜像（my-kali-agent）
dkagent claude                    # 默认就用 kali profile

macOS 用户：本脚本用到 bash 4+ 的关联数组，macOS 系统自带 bash 是 3.2（2007），需先 brew install bash 装新版。详见下方平台支持。

dkagent 通过 profile 切换不同的运行环境。所有 profile 共享同一个持久化 Home 卷，切换镜像时你的 zsh 配置、命令历史、Agent 登录凭证全部保留。

# 默认用 kali
dkagent claude

# 切换到精简镜像
docker build -t dkagent-slim -f dockerfiles/Dockerfile.slim .   # 先构建一次
dkagent -p slim claude

# 直接指定任意自定义镜像（escape hatch）
dkagent --image my-custom-agent claude

添加自定义 profile：在 ~/.config/dkagent/profiles 文件里追加一行：

node=my-node-agent
rust=my-rust-agent

之后即可 dkagent -p node claude。

⚠️ 自定义镜像约束：要让持久化 Home 卷能跨镜像复用，自定义镜像的 Dockerfile 必须创建 kali 用户并使用 /home/kali 作为 home 路径（参考 dockerfiles/Dockerfile.slim）。否则需用 -e（临时 Home）模式运行。

如果你已在宿主机登录过某个 Agent，可把登录态一次性拷进 dkagent 持久化卷，避免在容器里重新登录。以下命令在宿主机执行。

# 1. 拷贝 ~/.claude/ 配置目录（含登录凭证）
docker run --rm \
  -v agent_docker_kali-home:/home/kali \
  -v "$HOME/.claude:/src:ro" \
  alpine sh -c "mkdir -p /home/kali/.claude && cp -a /src/. /home/kali/.claude/"

# 2. 拷贝 ~/.claude.json 用户配置文件（注意是文件不是目录）
docker run --rm \
  -v agent_docker_kali-home:/home/kali \
  -v "$HOME/.claude.json:/src:ro" \
  alpine sh -c "cp -a /src /home/kali/.claude.json"

# 前置检查：若 ~/.codex/auth.json 不存在，说明凭证在 keychain，无法用文件迁移
ls ~/.codex/auth.json

docker run --rm \
  -v agent_docker_kali-home:/home/kali \
  -v "$HOME/.codex:/src:ro" \
  alpine sh -c "mkdir -p /home/kali/.codex && cp -a /src/. /home/kali/.codex/"

AI Agent 在执行任务时拥有强大的文件系统权限。为防止 Agent 遭遇恶性提示词或误判时删除、清空宿主机文件（如 rm -rf 风险），dkagent 用 挂载模式 × Home 持久化 两个维度组合出清晰的风险等级，每次运行都会打印当前级别。

  安全性 ▲
        │
   🟢 隔离级别     --no-mount + -e          完全隔离，用完即焚
        │
   🟢 低风险       --no-mount               隔离宿主文件，持久化 home 有配置被改风险
   🟢 低风险       全只读挂载 + -e           只能读取宿主文件，退出不留痕
        │
   🟡 中低风险     全只读挂载               只能读取，但持久化 home 有配置被改风险
   🟡 中风险       有可写挂载 + -e           可操作挂载目录，退出不留痕
        │
   🔴 高风险       有可写挂载               可操作挂载目录 + 持久化 home 可留后门
        │
   ☠️ 逃逸级别     --docker-socket          docker.sock = 宿主 root，无视上述所有档位
        │
        └────────────────────────────────────────────────▶ 便捷性

dkagent 的界面提示会自动识别语言，默认中文，同时完整支持英文：

• 自动识别：读取 $LANG / $LC_ALL——zh_* 用中文，其他用英文
• 手动覆盖：dkagent --lang en（或 zh）
• 持久覆盖：export DKAGENT_LANG=en

优先级：--lang 参数 > DKAGENT_LANG 环境变量 > $LANG/$LC_ALL 自动识别 > 默认中文。

dkagent --lang en --help          # 英文帮助
LANG=en_US.UTF-8 dkagent --help   # 自动识别为英文

SSH 连接物理机运行 Agent 时，经常会遇到终端断开后正在跑的会话丢失——网络抖动、笔记本合盖、切换网络都会断 SSH。

dkagent 默认自动用 tmux 包装（宿主机装了 tmux 时），从根本上解决这个问题：

• 首次运行 dkagent claude：自动在 tmux 会话 dkagent-<当前目录名> 里拉起 Agent
• SSH 断线：tmux server 跑在物理机上不受影响，Agent 进程继续跑
• 重连后：在同一目录再次 dkagent claude（或手动 tmux attach -t dkagent-<目录名>），直接接回原会话

# 第一次 SSH 连上
ssh user@host
cd ~/project-a
dkagent claude            # 自动进入 tmux 会话 dkagent-project-a

# SSH 断了，重新连上
ssh user@host
cd ~/project-a
dkagent claude            # 直接 attach 回原来的会话，Agent 还在跑

会话名默认按工作目录区分（不同项目天然隔离），可用 --tmux-name NAME 或环境变量 DKAGENT_TMUX_SESSION 自定义。

关闭 tmux 包装：

dkagent --no-tmux claude            # 本次禁用，直接 docker run

💡 设计取舍：tmux 包装在宿主机层（不是容器内），容器仍是 --rm 一次性，不引入长期运行的服务进程，零额外资源占用。Agent 正常退出后会话自动销毁。

dkagent [选项] [agent名称] [附加参数...]

# 进入交互式 Kali 命令行（挂载当前目录）
dkagent

# 直接唤醒容器内的 Claude Code
dkagent claude

# 使用临时 Home 卷（用完即焚）
dkagent -e claude

# 挂载多个目录（原项目 + 共享库）
dkagent -m ./my-project -m ./shared-libs claude

# 原始项目只读参考，副本目录可读写
dkagent -m ./my-project -r -m ./workspace/my-copy gemini

# 切换精简镜像
dkagent -p slim claude

# 纯净模式，不挂载任何宿主机目录
dkagent --no-mount

# 容器内可用 docker 命令（⚠️ 最高风险，等同宿主 root）
dkagent --docker-socket claude

镜像优先级：--image > --profile > 环境变量 DKAGENT_PROFILE > 默认 kali

Agent 名称：claude / gemini / pi / codex / opencode，留空则进入交互式 zsh。

如果不想用 dkagent CLI，也可直接通过 docker compose 启动。三种模式均共享同一个持久化 Home 卷（与 CLI 完全互通）。

# 🏠 调试/Shell 模式 - 仅持久化 Home，不挂载工作目录 (🟢)
docker compose run --rm agent-shell

# 🧊 纯净/隔离模式 - 无任何挂载，用完即焚 (🟢)
docker compose run --rm agent-isolated

# 📂 沙盒模式 - 持久化 Home + 挂载 ./workspace (🟡)
docker compose run --rm agent-sandboxed

# 切换镜像（复用同一个 Home 卷）
DKAGENT_IMAGE=dkagent-slim docker compose run --rm agent-shell

.
├── dkagent                  # 核心 bash CLI（参数解析、挂载、风险打印）
├── Dockerfile               # 默认 profile (kali) 构建配置
├── dockerfiles/
│   └── Dockerfile.slim      # slim profile 构建配置（精简 Debian）
├── docker-compose.yaml      # 备用的三种 compose 运行模式
├── install.sh               # 一键安装/卸载脚本
├── .env.example             # API Keys 配置模板
└── workspace/               # 沙盒模式预设的工作目录

• 多目录挂载 + 逐目录只读控制
• 8 档风险分级可视化
• 多镜像 profile 切换
• 容器内运行 Docker（--docker-socket）
• 中英文双语界面（自动识别）
• 网络隔离档位（--net off / --net strict，简单易用，契合多 agent 场景）

MIT