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:

bash

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):

bash

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

bash

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)

bash

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)

bash

# 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

bash

# 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)

bash

docker exec -d agent-box-manual websockify --web=/usr/share/novnc/ 6080 localhost:5910

Building the Image

bash

cd ~/Desktop/2026_01_22_old/agent-ecosystem-box/
docker compose build