Runbook for deploying NodeTool with nodetool serve: a local server, a Supabase-backed server, and Docker or Podman containers.
Runs: on any host with Node.js, or in a Docker or Podman container. Needs:
DB_PATHorDATABASE_URL, a master key (SECRETS_MASTER_KEY, or a keychain), and for remote authSUPABASE_URLandSUPABASE_KEY. Ports:7777by default. Hardware: not measured.
What Runs in Production
The server entrypoint is:
nodetool serve --host 0.0.0.0 --port 7777
nodetool serve accepts only --host (default 127.0.0.1) and --port (default 7777). It sets HOST and PORT and starts the server from the built @nodetool-ai/websocket package. Auth and runtime behavior come from environment variables. The Docker image runs node backend/server.mjs, where HOST defaults to 0.0.0.0 in production mode.
- Auth is enforced when both
SUPABASE_URLandSUPABASE_KEYare set. Otherwise the server uses the local auth provider.servereads noAUTH_PROVIDERswitch. NODETOOL_ENV=productionselects production mode (the container also setsNODE_ENV=production). It turns off the/mcpmount and the Python bridge until you opt in. See Self-Hosted Deployment.- The master key comes from
SECRETS_MASTER_KEY, then the system keychain, and is generated into the keychain when neither exists. A headless Linux host must setSECRETS_MASTER_KEY. The Docker image generates one into/workspace/.secrets_master_keywhen unset. /health(503 when the database check fails or the server is draining),/ready(liveness), and/api/health(version and uptime) need no authentication.
Prerequisites
- The NodeTool CLI (
@nodetool-ai/cli), see Installation. - Docker or Podman, and an image. Build one from the repository root:
docker build -t nodetool:local . # or: podman build -t nodetool:local .
1) Local / Desktop Runtime (no remote auth)
With no SUPABASE_* variables set, the server uses the local auth provider.
export DB_PATH=/path/to/workspace/nodetool.db
export HF_HOME=/path/to/hf-cache
nodetool serve --host 127.0.0.1 --port 7777
Verify:
curl -s http://127.0.0.1:7777/health
curl -s http://127.0.0.1:7777/ready
2) Supabase-Backed Server
Setting both SUPABASE_URL and SUPABASE_KEY enforces Supabase auth.
export NODETOOL_ENV=production
export SUPABASE_URL=https://<project>.supabase.co
export SUPABASE_KEY=<service-role-or-server-key>
export SECRETS_MASTER_KEY=<strong-random-secret>
export DB_PATH=/workspace/nodetool.db
export HF_HOME=/hf-cache
nodetool serve --host 0.0.0.0 --port 7777
Verify:
curl -i http://<host>:7777/health
curl -i http://<host>:7777/api/workflows
/health returns 200 without auth. /api/workflows without a token returns 401.
Containerized End-to-End Run
Docker
docker run --rm -p 7777:7777 \
-e NODETOOL_ENV=production \
-e SECRETS_MASTER_KEY=<secret> \
-e DB_PATH=/workspace/nodetool.db \
-e HF_HOME=/hf-cache \
-v $(pwd)/workspace:/workspace \
-v $(pwd)/hf-cache:/hf-cache \
nodetool:local
To enable Supabase auth, add -e SUPABASE_URL=… -e SUPABASE_KEY=… and -e SUPABASE_ANON_KEY=… for the login screen. Without Supabase, the server runs in Local mode and rejects requests that do not come from loopback or a network in NODETOOL_TRUST_LOCAL_NETWORKS, which docker run does not set. See Authentication.
Podman
Use the same command with podman run. Docker and Podman keep separate image stores, so build the image with the runtime you run it with.
Workflow Sync to a Deployed Server
Create the deployment config with nodetool deploy init and nodetool deploy add <name> --type docker (the file is deployment.yaml in the NodeTool config directory, ~/.config/nodetool/ on Linux). The deployment’s host and container.port give the server URL. Pass an admin bearer token with --token or NODETOOL_ADMIN_TOKEN, then sync:
export NODETOOL_ADMIN_TOKEN=<admin token>
nodetool deploy workflows sync <deployment-name> <workflow-id>
Sync pushes the workflow definition only. Assets and models are not copied.
List remote workflows:
nodetool deploy workflows list <deployment-name>
Run synced workflow via REST:
curl -s -X POST http://<host>:7777/api/workflows/<workflow-id>/run \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{}'
Production Checklist
NODETOOL_ENV=productionSECRETS_MASTER_KEYset, or a persistent/workspacevolume so the image keeps its generated keySUPABASE_URLandSUPABASE_KEYset if you need remote auth/healthand/readyreturn200- Protected endpoints without a token return
401 - Workflow sync and workflow run both succeed
If it fails
ERROR: No database configured. Set DATABASE_URL (PostgreSQL) or DB_PATH (SQLite).: the Docker image exits at once without one of them.- Exit on startup outside the image: a host with no keychain exits when
SECRETS_MASTER_KEYis missing. Generate one withopenssl rand -base64 32. docker runorpodman runreports “image not found”: check the runtime you run with (docker image ls | grep nodetool,podman image ls | grep nodetool), then rebuild and tag there.401 "Remote access requires authentication"in the container without Supabase: Local mode trusts only loopback andNODETOOL_TRUST_LOCAL_NETWORKS. See Authentication.