Build, run, and test IronClaw locally using Docker containers and Chrome MCP browser automation.
Use this skill to build, run, and test IronClaw web gateway changes locally using Dockerfile.test and Chrome MCP browser automation tools.
# Build the test image (libsql-only, no PostgreSQL needed)
docker build --platform linux/amd64 -f Dockerfile.test -t ironclaw-test .
# Run on port 3003 (default)
docker run --rm -p 3003:3003 \
-e ONBOARD_COMPLETED=true \
-e CLI_ENABLED=false \
-e NEARAI_API_KEY=<key> \
ironclaw-test
# Open in browser
# http://localhost:3003/?token=test
The test Dockerfile uses a two-stage build: Rust compilation with --features libsql (no PostgreSQL dependency), then a minimal Debian runtime image.
docker build --platform linux/amd64 -f Dockerfile.test -t ironclaw-test .
Build takes ~5-10 minutes on first run (cached subsequent builds are faster). The --platform linux/amd64 flag avoids QEMU warnings on Apple Silicon but can be omitted if targeting native architecture.
| Variable | Purpose | Default in Dockerfile |
|---|---|---|
ONBOARD_COMPLETED=true | Skip onboarding wizard (exits immediately otherwise) | not set |
CLI_ENABLED=false | Disable TUI/REPL (causes EOF shutdown otherwise) | not set |
Pick ONE of these configurations:
NEAR AI (API key mode):
docker run --rm -p 3003:3003 \
-e ONBOARD_COMPLETED=true \
-e CLI_ENABLED=false \
-e NEARAI_API_KEY=<your-key> \
ironclaw-test
NEAR AI (session token mode):
docker run --rm -p 3003:3003 \
-e ONBOARD_COMPLETED=true \
-e CLI_ENABLED=false \
-e NEARAI_SESSION_TOKEN=<sess_xxx> \
-e NEARAI_BASE_URL=https://private.near.ai \
ironclaw-test
OpenAI:
docker run --rm -p 3003:3003 \
-e ONBOARD_COMPLETED=true \
-e CLI_ENABLED=false \
-e LLM_BACKEND=openai \
-e OPENAI_API_KEY=<your-key> \
ironclaw-test
Anthropic:
docker run --rm -p 3003:3003 \
-e ONBOARD_COMPLETED=true \
-e CLI_ENABLED=false \
-e LLM_BACKEND=anthropic \
-e ANTHROPIC_API_KEY=<your-key> \
ironclaw-test
Dummy run (no LLM, just test the UI loads):
docker run --rm -p 3003:3003 \
-e ONBOARD_COMPLETED=true \
-e CLI_ENABLED=false \
-e NEARAI_API_KEY=dummy \
ironclaw-test
| Variable | Purpose | Example |
|---|---|---|
GATEWAY_PORT | Change the listen port | 3003 (default) |
GATEWAY_AUTH_TOKEN | Auth token for API | test (default) |
NEARAI_MODEL | Override LLM model | claude-3-5-sonnet-20241022 |
RUST_LOG | Logging verbosity | ironclaw=debug |
ROUTINES_ENABLED | Enable routines | true/false |
SKILLS_ENABLED | Enable skills system | true (default) |
Run multiple containers on different host ports:
docker run --rm -d --name ic-test-a -p 3003:3003 -e ONBOARD_COMPLETED=true -e CLI_ENABLED=false -e NEARAI_API_KEY=dummy ironclaw-test
docker run --rm -d --name ic-test-b -p 3004:3003 -e ONBOARD_COMPLETED=true -e CLI_ENABLED=false -e NEARAI_API_KEY=dummy ironclaw-test
Use the Claude for Chrome browser automation tools to test the web UI.
mcp__claude-in-chrome__tabs_context_mcp
Always start here to see current tabs and get fresh tab IDs.
mcp__claude-in-chrome__tabs_create_mcp url=http://localhost:3003/?token=test
mcp__claude-in-chrome__read_page
Check for:
mcp__claude-in-chrome__computer action=screenshot
mcp__claude-in-chrome__resize_window width=375 height=812
mcp__claude-in-chrome__computer action=screenshot
Reset to desktop:
mcp__claude-in-chrome__resize_window width=1280 height=800
mcp__claude-in-chrome__javascript_tool script="document.querySelector('.connection-status')?.textContent"
Click tabs, send messages, search skills — use computer tool with action=click and coordinate-based clicks, or use find + form_input for text entry.
# Stop a specific container
docker stop ic-test-a
# Stop all test containers
docker ps --filter ancestor=ironclaw-test -q | xargs -r docker stop
# Remove the test image
docker rmi ironclaw-test
ONBOARD_COMPLETED=true: The onboarding wizard tries to read stdin, gets EOF, and exits.CLI_ENABLED=false: The REPL channel reads stdin, gets EOF, and shuts down the agent.NEARAI_BASE_URL=https://private.near.ai.--platform linux/amd64 flag causes QEMU emulation warnings — these are harmless.-p 3005:3003.GATEWAY_HOST=0.0.0.0 (set by default in Dockerfile).docker logs <container-id>.?token=test.