# Knowledge Docker Agent Box

> Knowledge: Docker Agent Box

- Skill: `tankygranny05/knowledge-docker-agent-box-2` (Agent Skill)
- Install (CLI): `npx skillmds@latest add tankygranny05/knowledge-docker-agent-box-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tankygranny05/knowledge-docker-agent-box-2/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-22
- Page: https://skillmd.com/skills/tankygranny05/knowledge-docker-agent-box-2

---

# Knowledge: Docker Agent Box
<!-- [Created by Claude: a17cf90b-0acf-4346-aa57-f93f14a3ed18 2026-01-28] -->
<!-- [Edited by Claude: e5f3ca91-5175-41e0-a7b6-5500d03142b5 2026-01-29] -->

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