Docker One-Click Deployment Tutorial

This guide is for users who want to run NextClaw directly in Docker.
Goal: start with one command and get URLs you can open immediately.

Prerequisites

• Docker is installed and running (Docker Desktop or Docker Engine).
• Your machine can access:
  • https://nextclaw.io (install script)
  • Docker image registry (to pull node:22-bookworm-slim)
  • npm registry (to install nextclaw)
• Default ports are available:
  • UI: 55667
  • Gateway: 18890

One-Click Command

curl -fsSL https://nextclaw.io/install-docker.sh | bash

What You Will See After Startup

When startup succeeds, output looks like:

UI: http://127.0.0.1:55667
API: http://127.0.0.1:55667/api
Gateway (direct): http://127.0.0.1:18890
Data dir: /Users/<you>/.nextclaw-docker
Container: nextclaw

Like nextclaw start, you can open the UI URL directly.

What The Script Actually Does

• The runtime image defaults to node:22-bookworm-slim, and the script uses docker run --init when supported by your Docker runtime.
• Inside the container, startup flow is:
  • npm i -g nextclaw@latest (or the version set by NEXTCLAW_DOCKER_INSTALL_TARGET)
  • nextclaw init (ensures config/workspace initialization)
  • exec nextclaw serve --ui-port <port> (foreground process, container-friendly)

Useful Operations

View logs:

docker logs -f nextclaw

Restart:

docker restart nextclaw

Stop:

docker stop nextclaw

Remove container (data directory stays):

docker rm -f nextclaw

Customize Port / Data Directory / Container Name

Option 1: Environment Variables (most common)

NEXTCLAW_DOCKER_UI_PORT=18991 \
NEXTCLAW_DOCKER_API_PORT=18990 \
NEXTCLAW_DOCKER_CONTAINER_NAME=nextclaw-prod \
NEXTCLAW_DOCKER_DATA_DIR="$HOME/.nextclaw-docker-prod" \
curl -fsSL https://nextclaw.io/install-docker.sh | bash

Option 2: Script Flags

curl -fsSL https://nextclaw.io/install-docker.sh | bash -s -- \
  --ui-port 18991 \
  --api-port 18990 \
  --container-name nextclaw-prod \
  --data-dir "$HOME/.nextclaw-docker-prod"

Dry Run (preview only)

curl -fsSL https://nextclaw.io/install-docker.sh | bash -s -- --dry-run

Upgrade to Latest

Run the same one-click command again.
The script recreates the same container name while keeping data in the mounted directory (default ~/.nextclaw-docker).

If you want to pin a version:

NEXTCLAW_DOCKER_INSTALL_TARGET=[email protected] \
curl -fsSL https://nextclaw.io/install-docker.sh | bash

Common Issues

Error: docker is required

Docker is not available in PATH. Install Docker and verify docker version.

Error: docker daemon is not reachable

Docker service is not running. Start Docker Desktop/daemon first.

Error: health check timeout (/api/health)

Check container logs:

docker logs --tail 120 nextclaw

Common reasons:

• slow network while pulling image/installing npm package
• first-run nextclaw init work (config/template initialization)
• port conflict prevented service startup

Port Conflict

Re-run with custom ports. See customization examples above.

Related Docs

• Quick Start
• Configuration
• Troubleshooting