tankygranny05 Knowledge: Docker Agent Box
Reference documentation for the Agent Box Docker container.
⚠️ CRITICAL: Shared vs Masked Volumes
| Path | Type | Host↔Container | Issue |
|---|---|---|---|
~/swe |
Shared | Bidirectional sync | Codex binary is macOS, won't run in Linux |
~/.claude |
Shared | Bidirectional sync | .credentials.json works (JSON) |
~/.codex |
Shared | Bidirectional sync | auth.json works (JSON) |
~/centralized-logs |
Shared | Bidirectional sync | ✅ No issues |
node_modules |
Masked | Anonymous volume | Container has own Linux modules |
Problem 1: Codex Binary (macOS ≠ Linux)
~/swe/codex.X.Y.Z/codex-rs/target/release/codex is Mach-O (macOS). Container needs ELF (Linux).
Solution: Build Linux binary separately:
python ~/.claude/skills/agentic-ecosystem-docker/scripts/build_codex_linux_binary.py \
--codex-rs ~/swe/codex.0.88.0/codex-rs \
--out-dir /tmp/codex-linux \
--profile debug
Then mount: -v /tmp/codex-linux/codex:/opt/bin/codex:ro
Problem 2: .env Files (Shared = Conflict)
Host .env has SHIM_HOST=127.0.0.1, container needs 0.0.0.0. Same file = conflict.
Solution: Override via -e flags (don't touch host file):
docker run ... \
-e SHIM_HOST=0.0.0.0 \
-e CODEX_SHIM_HOST=0.0.0.0 \
...
Problem 3: Other Platform-Specific Binaries
| Binary | Cross-platform? | Solution |
|---|---|---|
codex |
❌ Native Rust | Build Linux binary |
claude (cli.js) |
✅ Node.js | Works as-is |
node_modules/*.node |
❌ Native addons | Use anonymous volume mask |
Container Overview
| Property | Value |
|---|---|
| Container Name | agent-box-manual |
| Image | agent-ecosystem-box-agent-box:latest |
| Image Source | ~/Desktop/2026_01_22_old/agent-ecosystem-box/ |
Service Ports
| Service | Container Port | Host Port | Browser URL | Password |
|---|---|---|---|---|
| VNC Server | 5910 | 5910 | - | password |
| noVNC (Web) | 6080 | 6080 | http://localhost:6080/vnc.html | password |
| Agent HQ | 8037 | 38037 | http://localhost:38037 | - |
| Claude Shim | 8787 | 38787 | http://localhost:38787 | - |
| Codex Shim | 9288 | 39288 | http://localhost:39288 | - |
Docker Run Command
docker run -d \
--name agent-box-manual \
-p 127.0.0.1:5910:5910 \
-p 127.0.0.1:6080:6080 \
-p 127.0.0.1:38037:8037 \
-p 127.0.0.1:38787:8787 \
-p 127.0.0.1:39288:9288 \
-v /home/dev/AgenticProjects/agent-box-v1/apps/agent-hq-ui/node_modules \
-v ~/swe:/home/dev/swe \
-v ~/AgenticProjects:/home/dev/AgenticProjects \
-v ~/.claude:/home/dev/.claude \
-v ~/.codex:/home/dev/.codex \
-v ~/centralized-logs:/home/dev/centralized-logs \
-e VNC_PASSWORD=password \
--cap-add SYS_ADMIN \
--security-opt seccomp=unconfined \
--shm-size 2gb \
agent-ecosystem-box-agent-box:latest
Volume Mounts
| Host Path | Container Path | Purpose |
|---|---|---|
~/swe |
/home/dev/swe |
Source code repositories |
~/AgenticProjects |
/home/dev/AgenticProjects |
Agent project data |
~/centralized-logs |
/home/dev/centralized-logs |
Shared telemetry logs |
~/.claude |
/home/dev/.claude |
Claude configuration & auth |
~/.codex |
/home/dev/.codex |
Codex configuration & auth |
Note: The node_modules volume is an anonymous Docker volume that prevents macOS native modules from being used inside Linux.
Troubleshooting
Fix Claude Shim (Symlink)
docker exec -u dev agent-box-manual ln -sf /home/dev/swe/claude-code-2.1.20/cli.js /home/dev/symlinks/claude
Fix Agent HQ (Node Modules)
# If Agent HQ fails with missing native modules (e.g. @rollup/*, @esbuild/*),
# it's usually because macOS node_modules were bind-mounted into Linux.
# One-off fix (will replace node_modules contents for Linux):
docker exec -u dev agent-box-manual bash -c \
"cd /home/dev/AgenticProjects/agent-box-v1/apps/agent-hq-ui && rm -rf node_modules && npm install"
Start Services Manually
# Start Agent HQ
docker exec -d -u dev agent-box-manual bash -c \
"cd /home/dev/AgenticProjects/agent-box-v1/apps/agent-hq-ui && npm run dev:web -- --port 8037 --host 0.0.0.0"
# Start Claude Shim
docker exec -d -u dev agent-box-manual bash -c \
"export CLAUDE_CODE_CLI=/home/dev/symlinks/claude && cd /home/dev/swe/vscode-shims && /home/dev/venv/bin/python src/claude/server.py --host 0.0.0.0"
Start noVNC (Web VNC)
docker exec -d agent-box-manual websockify --web=/usr/share/novnc/ 6080 localhost:5910
Building the Image
cd ~/Desktop/2026_01_22_old/agent-ecosystem-box/
docker compose build