# Knowledge Docker Agent Box

> Reference documentation for the Agent Box Docker container. Use when starting/restarting the container, troubleshooting services (Agent HQ, Claude Shim, Codex Shim), looking up ports/volumes, or building the Docker image.

- Skill: `tankygranny05/knowledge-docker-agent-box` (Agent Skill)
- Install (CLI): `npx skillmds@latest add tankygranny05/knowledge-docker-agent-box`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tankygranny05/knowledge-docker-agent-box/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: tankygranny05 (https://skillmd.com/u/tankygranny05)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/tankygranny05/knowledge-docker-agent-box

---

<!-- [Created by Claude: a17cf90b-0acf-4346-aa57-f93f14a3ed18 2026-01-28] -->

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