ClawMagic Docs

Deployment

ClawMagic runs locally by default. For persistent hosting, deploy as a single-process service with the gateway installer or Docker.

Local (Default)

ClawMagic is designed to run on your machine. The gateway installer sets up ClawMagic as a background service that starts on login.

# Install as background service
node clawmagic.mjs gateway install

# Check status
node clawmagic.mjs gateway status

# Restart after updates
node clawmagic.mjs gateway restart

# Uninstall service
node clawmagic.mjs gateway uninstall

The server binds to 127.0.0.1:18790 by default. No cloud account, no external services required.

Docker

# Build image
docker build -t clawmagic .

# Run with state persistence
docker run -d \
  -p 18790:18790 \
  -v ~/.clawmagic:/root/.clawmagic \
  -v ./state:/app/state \
  -v ./plugins:/app/plugins \
  --name clawmagic \
  clawmagic

Mount ~/.clawmagic, state/, and plugins/ as volumes to persist config, state, and installed plugins across container restarts.

Docker Security Hardening

cap-drop ALL — remove all Linux capabilities by default.
seccomp/AppArmor — kernel-level syscall filtering.
Read-only root filesystem where possible.
Non-root user execution inside the container.
Localhost binding only (do not expose 0.0.0.0 without reverse proxy + auth).

Remote Access (Advanced)

By default, ClawMagic only accepts connections from localhost. To enable remote access:

Set CLAWMAGIC_ALLOW_REMOTE=true in your environment.
Use a reverse proxy (nginx, Caddy) with TLS termination.
Change the default portal password immediately.
Enable API token auth for all programmatic access.
CORS switches from localhost-only to explicit origin allowlist in remote mode.

Health Checks

# CLI health check
node clawmagic.mjs doctor

# HTTP health endpoints
curl http://127.0.0.1:18790/health
curl http://127.0.0.1:18790/ready

The doctor command runs comprehensive checks: server connectivity, provider reachability, state file integrity, plugin validation, and security posture.

Marketplace Deployment (Separate)

The ClawMagic Marketplace is a separate system deployed independently. It uses PostgreSQL, Redis, and Heroku. ClawMagic core connects to the marketplace as an API client — no marketplace infrastructure is needed to run ClawMagic.

If you are deploying the marketplace itself, see the internal deployment runbook at docs/deploy-heroku.md in the marketplace repository.