Local 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

LLM Backend Configuration

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

Common Overrides

Multi-Instance Testing

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

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

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