API Server Overview

The unified NodeTool HTTP + WebSocket server — REST routes, workflow execution, and OpenAI-compatible `/v1` endpoints.

NodeTool exposes a single TypeScript HTTP + WebSocket server runtime built on Node.js. The same process serves REST API routes, WebSocket workflow execution endpoints, and OpenAI-compatible /v1 routes.

The server is implemented in the @nodetool-ai/websocket package (packages/websocket/src/server.ts).

Key Modules

  • server.ts – HTTP/WebSocket server entry point. Registers all API routes and starts listeners.
  • unified-websocket-runner.ts – Handles WebSocket connections for workflow execution and chat.
  • http-api.ts – Core REST API routes (workflows, jobs, assets, etc.).
  • models-api.ts – Model management and provider registration.
  • settings-registry.ts – Settings and configuration handling.
  • storage-api.ts – File upload and asset storage endpoints.
  • mcp-server.ts – Model Context Protocol (MCP) server integration.
  • openai-api.ts – OpenAI-compatible /v1/chat/completions and /v1/models endpoints.

Running the Server

# Install the CLI globally (once)
npm install -g @nodetool-ai/cli

# Start the server
nodetool serve --host 127.0.0.1 --port 7777

# Or run without installing globally
npx --package=@nodetool-ai/cli nodetool serve --host 0.0.0.0 --port 7777

Development (from repo root):

npm run build:packages
npm run dev:server   # tsx --watch packages/websocket/src/server.ts

Configuration

The server is configured via environment variables:

Variable Default Description
PORT 7777 HTTP listen port
HOST 127.0.0.1 Bind address
DB_PATH ~/.local/share/nodetool/nodetool.sqlite3 SQLite database path. Do not set together with DATABASE_URL.
DATABASE_URL — PostgreSQL URL (postgres:// / postgresql://) or SQLite URL/path (file: / sqlite:)
ANTHROPIC_API_KEY — Anthropic API key
OPENAI_API_KEY — OpenAI API key
GEMINI_API_KEY — Google Gemini API key
OLLAMA_API_URL http://localhost:11434 Ollama server URL

Health Check

GET /health

Returns 200 OK when healthy (503 when degraded) with a JSON body:

{
  "status": "ok",
  "timestamp": "2026-06-20T00:00:00.000Z",
  "uptime": 123,
  "services": { "database": "ok", "server": "ok" }
}

GET /ready is a simple liveness probe (always 200 with { "status": "ok" }), and GET /api/health returns { version, uptime }. None require authentication.

For deployment setup, see Deployment Guide and Authentication.

Edit this page on GitHub