docs: document --sandbox auto-kit and --no-kit flag#2867
Conversation
docker-agent
left a comment
docker-agent
left a comment
There was a problem hiding this comment.
Assessment: 🟡 NEEDS ATTENTION
Documentation is well-structured and covers the new --no-kit flag and auto-kit subsystem clearly. Two medium-severity documentation inconsistencies were found in the new docs/configuration/sandbox/index.md content.
|
|
||
| ## Auto-Kit | ||
|
|
||
| The sandbox VM has its own filesystem and `$HOME` — none of the host's `~/.agents/skills/`, `~/.claude/skills/`, project-level `.agents/skills/`, or prompt files like `AGENTS.md` and `CLAUDE.md` are visible inside it. To bridge that gap, docker-agent automatically builds a **kit**: a self-contained directory staged on the host before the sandbox starts and bind-mounted read-only into the VM at the same path. |
There was a problem hiding this comment.
[MEDIUM] Incomplete list of inaccessible host skill paths — ~/.codex/skills/ is missing
The Auto-Kit intro paragraph lists the host paths that are inaccessible inside the sandbox VM:
"none of the host's
~/.agents/skills/,~/.claude/skills/, project-level.agents/skills/, or prompt files …"
But ~/.codex/skills/ is omitted from this list, even though the very next subsection ("What gets staged", line 91) includes it as one of the global skill paths that the kit stages:
"global
~/.codex/skills/,~/.claude/skills/,~/.agents/skills/, plus project.claude/skills/and.agents/skills/"
A reader of the intro paragraph alone could reasonably conclude that ~/.codex/skills/ is accessible inside the sandbox (since it isn't listed as inaccessible), which is the opposite of reality. Consider adding ~/.codex/skills/ to the list, or noting that the list is non-exhaustive.
|
|
||
| ### Caching | ||
|
|
||
| Kits are stored under the docker-agent cache directory (`~/Library/Caches/cagent/sandbox-kits/<hash>` on macOS) keyed by a content hash of the agent reference. Reusing the same agent across runs reuses the same kit directory in place; disk usage is bounded by the number of distinct agents you have run. Kits are deliberately kept on disk between runs because the reused sandbox VM holds a hard reference to the kit's bind-mount path — deleting it would leave the sandbox un-startable. |
There was a problem hiding this comment.
[MEDIUM] "Content hash of the agent reference" — ambiguous cache-invalidation semantics
The Caching section says:
"keyed by a content hash of the agent reference"
"Agent reference" is ambiguous. It could mean:
- The agent YAML file path/identifier (cache never busts when skill
.mdfiles change) - The full content of the agent YAML file (same — editing a skill file doesn't change the YAML)
- The YAML plus all staged skill files (cache invalidates when any skill file changes)
If interpretation 1 or 2 is correct, users who edit a skill file will silently run with a stale kit in subsequent --sandbox runs, with no indication that their edits are not reflected. The current wording does not allow users to know whether --no-kit or a forced re-run is needed after skill edits.
Consider clarifying what "agent reference" means in this context, or documenting whether skill file changes trigger a rebuild.
aheritier
added
area/cli
dgageot
force-pushed
the
docs/sandbox-auto-kit
branch
from
480b484 to
b8938b2
Compare
4 participants
The
--no-kitflag ondocker agent runand the auto-kit subsystem were previously undocumented. This PR adds comprehensive documentation covering how docker-agent stages local skills and prompt files into a kit directory on the host, bind-mounts it read-only into the sandbox VM, redacts secrets via portcullis, and enforces minimal per-toolset network allowlisting (resolved against the aqua registry with a fallback union).The sandbox lifecycle description is also corrected: VMs are reused across runs rather than stopped and removed at session end, and the Limitations section is updated accordingly. Secret-redaction wording is tightened to accurately reflect that portcullis is best-effort and pattern-based, rather than a guarantee.