Deployment Journeys

Use this page as a scenario walkthrough. For the canonical reference material, rely on the Deployment Guide for CLI/deployment.yaml, Self-Hosted Deployment for proxy + Docker details, and Proxy Reference for config fields.

Self-hosted with Proxy

  1. Clone and install

    git clone https://github.com/nodetool-ai/nodetool-core.git
cd nodetool-core
pip install -e .
pip install -r requirements-dev.txt

  2. Configure environment

    cp .env.example .env.development.local
echo \"AUTH_PROVIDER=static\" >> .env.development.local
echo \"WORKER_AUTH_TOKEN=$(openssl rand -base64 32)\" >> .env.development.local

  3. Start services

    nodetool serve --reload
  4. Add proxy (TLS + auth)
    • Terminate TLS at your proxy (nginx/traefik); forward to 127.0.0.1:8000.
    • Expose /health and /ping without auth; require Bearer tokens elsewhere.

  5. Verify health

    curl https://your-domain/health
curl -H \"Authorization: Bearer $WORKER_AUTH_TOKEN\" https://your-domain/v1/models

  6. Run a workflow remotely

    curl -H \"Authorization: Bearer $WORKER_AUTH_TOKEN\" \\
  -X POST https://your-domain/api/workflows/<workflow_id>/run?stream=true \\
  -d '{\"params\":{}}'

RunPod Serverless

  1. Package and upload — create an image or use the provided RunPod template (see docker/).
  2. Set secrets — in RunPod console set WORKER_AUTH_TOKEN, provider keys, and AUTH_PROVIDER=static.
  3. Deploy endpoint — note the endpoint ID and base URL.

  4. Verify health

    curl https://api.runpod.ai/v2/<endpoint>/health

  5. List models and chat

    curl -H \"Authorization: Bearer $RUNPOD_API_KEY\" https://api.runpod.ai/v2/<endpoint>/v1/models
curl -H \"Authorization: Bearer $RUNPOD_API_KEY\" \\
  -H \"Content-Type: application/json\" \\
  -X POST https://api.runpod.ai/v2/<endpoint>/v1/chat/completions \\
  -d '{\"model\":\"gpt-oss:20b\",\"messages\":[{\"role\":\"user\",\"content\":\"hi\"}],\"stream\":true}'

  6. Run workflow

    curl -H \"Authorization: Bearer $RUNPOD_API_KEY\" \\
  -X POST \"https://api.runpod.ai/v2/<endpoint>/api/workflows/<workflow_id>/run?stream=true\" \\
  -d '{\"params\":{}}'

Cloud Run

  1. Build image

    gcloud builds submit --tag gcr.io/<project>/nodetool:latest .

  2. Deploy

    gcloud run deploy nodetool \\
  --image gcr.io/<project>/nodetool:latest \\
  --allow-unauthenticated=false \\
  --port 8000 \\
  --set-env-vars AUTH_PROVIDER=static,WORKER_AUTH_TOKEN=$(openssl rand -base64 32)
  3. Set secrets
    • Store provider keys in Secret Manager and mount as env vars.
    • Disable terminal WebSocket via NODETOOL_ENABLE_TERMINAL_WS= (empty).

  4. Verify

    curl https://<service-url>/health
curl -H \"Authorization: Bearer $WORKER_AUTH_TOKEN\" https://<service-url>/v1/models

  5. Run workflow

    curl -H \"Authorization: Bearer $WORKER_AUTH_TOKEN\" \\
  -X POST \"https://<service-url>/api/workflows/<workflow_id>/run?stream=true\" \\
  -d '{\"params\":{}}'