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

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