tankygranny05 Knowledge: Docker Agent Box
Reference documentation for the Agent Box Docker container. Use this skill when:
- Starting or restarting the agent-box-manual container
- Troubleshooting Agent HQ, Claude Shim, or Codex Shim inside the container
- Looking up port mappings or volume mounts
- Fixing broken services after container restart
- Building or modifying the Docker image
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