local-test

name	local-test
version	0.1.0
description	Build, run, and test ThreatClaw locally using Docker containers and Chrome MCP browser automation.
activation	{"keywords":["test locally","local test","docker test","test my changes","test in docker","test web gateway","spin up test","test container"],"patterns":["test.*local","docker.*test","spin.*up.*test","test.*changes.*docker"],"max_context_tokens":3000}

Local Testing with Docker + Chrome MCP

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

Quick Start

# Build the test image (libsql-only, no PostgreSQL needed)
docker build --platform linux/amd64 -f Dockerfile.test -t threatclaw-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> \
  threatclaw-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.

docker build --platform linux/amd64 -f Dockerfile.test -t threatclaw-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):

docker run --rm -p 3003:3003 \
  -e ONBOARD_COMPLETED=true \
  -e CLI_ENABLED=false \
  -e NEARAI_API_KEY=<your-key> \
  threatclaw-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 \
  threatclaw-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> \
  threatclaw-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> \
  threatclaw-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 \
  threatclaw-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	(provider-specific)
RUST_LOG	Logging verbosity	threatclaw=debug
ROUTINES_ENABLED	Enable routines	true/false
SKILLS_ENABLED	Enable skills system	true (default)

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 threatclaw-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 threatclaw-test

Browser Testing

Open http://localhost:3003/?token=test and verify:

• "Connected" indicator in top-right
• All tabs visible: Chat, Memory, Jobs, Routines, Extensions, Skills
• Test mobile viewport (375x812) and desktop (1280x800)

Cleanup

# Stop a specific container
docker stop ic-test-a

# Stop all test containers
docker ps --filter ancestor=threatclaw-test -q | xargs -r docker stop

# Remove the test image
docker rmi threatclaw-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.