Developer Guide

Resources for building custom nodes, extending NodeTool, and integrating workflows programmatically.

Quick Start: Custom Nodes

Creating custom nodes in TypeScript:

import { BaseNode, prop } from "@nodetool-ai/node-sdk";

export class UppercaseTextNode extends BaseNode {
  static readonly nodeType = "mypackage.text.Upper";
  static readonly title = "Uppercase Text";
  static readonly description = "Convert text to uppercase.";
  static readonly metadataOutputTypes = { output: "str" };

  @prop({ type: "str", default: "", title: "Input Text" })
  declare inputText: string;

  async process(): Promise<Record<string, unknown>> {
    return { output: String(this.inputText ?? "").toUpperCase() };
  }
}

Export a register(registry) function and add a nodetool field to package.json ({ "apiVersion": 1, "register": "register" }). At startup the server scans installed packages for that field and calls the export. With NODETOOL_ENV=production or NODETOOL_PACKS_REQUIRE_ALLOWLIST=1, only packs on the allowlist load. @prop needs experimentalDecorators in tsconfig.json.

-> Full Custom Nodes Guide (TypeScript) – End-to-end walkthrough: packaging, governance, streaming, testing, distribution.

Guides

Provider & Model Guides

Custom Providers – Connect an OpenAI-compatible endpoint without writing code.
Provider Guides – Add models & nodes to any provider. Per-provider runbooks (OpenAI, Anthropic, Gemini, xAI, FAL, Replicate, KIE, Together, AtlasCloud, Topaz, MiniMax, Reve, ElevenLabs, HuggingFace, Ollama, local inference, OpenAI-compatible) with exact files, commands, and how past PRs did it. Written for coding agents and contributors.

Custom Node Development (TypeScript)

Custom Nodes Guide – Start here! End-to-end guide for authoring, packaging, and distributing TypeScript node packs.
TypeScript DSL Guide – Type-safe workflow definitions with auto-generated factory functions.

Custom Node Reference (TypeScript)

Node Implementation Quick Reference – Templates and common @prop / process() patterns.
Node Implementation Patterns – Architectural patterns: multi-output, streaming, stateful, secrets.

Python Nodes

Node Implementation Examples – Python node examples for the Python bridge.

Advanced

Suspendable Nodes – Why there is no pause/resume node API, and what WaitNode actually does.
JavaScript Sandbox – The QuickJS guest behind the Code node and agent code actions: capabilities, limits, imports, security model.

Programmatic Workflows

TypeScript DSL Guide – Type-safe workflow definitions with auto-generated factory functions
Portable Workflow Runner – Run a workflow graph from a (Request) => Response handler on Node, Bun, Deno, Vercel, Cloudflare Workers, or in the browser
Example Apps – Runnable apps in examples/: a chat client and Next.js workflow apps for Vercel and Cloudflare

Architecture

Architecture – Packages, execution engine, message types, providers, storage
Execution Strategies – How the kernel schedules actors and how the Code node is sandboxed
Packages – How node packages are structured, registered, and managed from the CLI
Node Packs – Built-in packs, the Package Manager, and installing third-party packs
Python Bridge Protocol – Wire protocol between the TypeScript runtime and the Python worker

API Integration

API Reference – REST API endpoints and authentication
Headless Mode – Run workflows via CLI and HTTP API
Chat API – OpenAI-compatible chat endpoints
Workflow API – Execute workflows programmatically
TypeScript SDK – @nodetool-ai/sdk: a typed tRPC client and the chat WebSocket

Contributing

Contribute to NodeTool on GitHub.

Dev Environment – Installing in locked-down containers and running WebGPU tests without a Vulkan driver.
Harness Reference – nodetool validate, debug, node run, harness gate and the other checks contributors run.

Options:

Publish as a separate npm package
Contribute to the core node library in the repository
Share workflow examples on Discord

Edit this page on GitHub