Local Testing with Docker + Chrome MCP

Use this skill to build, run, and test IronClaw web gateway changes locally using Dockerfile.test and Chrome MCP browser automation tools.

Quick Start

bash

# 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

Building the Image

The test Dockerfile uses a two-stage build: Rust compilation with --features libsql (no PostgreSQL dependency), then a minimal Debian runtime image.

bash

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.

Running Containers

Required Environment Variables

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

LLM Backend Configuration

Pick ONE of these configurations:

NEAR AI (API key mode):

bash

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):

bash

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:

bash

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:

bash

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):

bash

docker run --rm -p 3003:3003 \
  -e ONBOARD_COMPLETED=true \
  -e CLI_ENABLED=false \
  -e NEARAI_API_KEY=dummy \
  ironclaw-test

Common Overrides

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)

Multi-Instance Testing

Run multiple containers on different host ports:

bash

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

Chrome MCP Testing Workflow

Use the Claude for Chrome browser automation tools to test the web UI.

Step 1: Get Browser Context

mcp__claude-in-chrome__tabs_context_mcp

Always start here to see current tabs and get fresh tab IDs.

Step 2: Open the Gateway

mcp__claude-in-chrome__tabs_create_mcp  url=http://localhost:3003/?token=test

Step 3: Verify the Page

mcp__claude-in-chrome__read_page

Check for:

"Connected" indicator in top-right
All tabs visible: Chat, Memory, Jobs, Routines, Extensions, Skills

Step 4: Take Screenshots

mcp__claude-in-chrome__computer  action=screenshot

Step 5: Test Mobile Viewport

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

Step 6: Run JavaScript Checks

mcp__claude-in-chrome__javascript_tool  script="document.querySelector('.connection-status')?.textContent"

Step 7: Test Interactions

Click tabs, send messages, search skills — use computer tool with action=click and coordinate-based clicks, or use find + form_input for text entry.

Cleanup

bash

# 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

Troubleshooting

Container exits immediately

Missing ONBOARD_COMPLETED=true: The onboarding wizard tries to read stdin, gets EOF, and exits.
Missing CLI_ENABLED=false: The REPL channel reads stdin, gets EOF, and shuts down the agent.

"Model not found" or LLM errors

Check that your API key/token is valid and the model name is correct.
For NEAR AI session token mode, you also need NEARAI_BASE_URL=https://private.near.ai.

Platform mismatch warnings on Apple Silicon

The --platform linux/amd64 flag causes QEMU emulation warnings — these are harmless.
Alternatively, omit the flag and build natively if your dependencies support ARM64.

Port already in use

The dev server defaults to port 3001; the test Dockerfile defaults to 3003 to avoid conflicts.
Use a different host port: -p 3005:3003.

Cannot connect from browser

Verify GATEWAY_HOST=0.0.0.0 (set by default in Dockerfile).
Check the container logs: docker logs <container-id>.
Make sure you include the token query param: ?token=test.