Required dependencies

This is a Rust workspace, not a Node.js package. There are no npm install steps. Build and runtime requirements are:

# System dependencies (Debian/Ubuntu)
apt-get install -y \
  build-essential \
  pkg-config \
  libssl-dev \
  libpq-dev \
  libsasl2-dev \
  cmake \
  git \
  curl

# Rust toolchain (stable, 1.76+)
curl https://sh.rustup.rs -sSf | sh -s -- -y --default-toolchain stable
source "$HOME/.cargo/env"

# sqlx-cli for running migrations manually
cargo install sqlx-cli --no-default-features --features postgres

# Optional: cargo-watch for development
cargo install cargo-watch

Native build notes:

• DuckDB FFI (windmill-duckdb-ffi-internal) requires cmake and will compile DuckDB from source on first build.
• The QuickJS evaluator (windmill-jseval) compiles embedded C; ensure clang or gcc is present.
• Deno runtime (windmill-runtime-nativets) may download a Deno binary at build time; outbound internet access is required during build unless DENO_DIR is pre-populated.

Project setup

1. Copy the entire source/ directory into your repository root or a dedicated subdirectory (e.g. ./windmill-backend/).

2. Ensure PostgreSQL 14+ is running and create the database:

   createdb windmill
   export DATABASE_URL="postgresql://postgres:password@localhost:5432/windmill"
   

3. Run all SQL migrations:

   cd source/
   sqlx migrate run --database-url "$DATABASE_URL"
   

4. Set required environment variables (minimum set):

   export DATABASE_URL="postgresql://postgres:password@localhost:5432/windmill"
   export BASE_URL="http://localhost:8000"
   export JWT_SECRET="change-me-in-production-min-32-chars"
   export MODE="server"          # "server" | "worker" | "standalone"
   export WORKER_GROUP="default"
   export NUM_WORKERS="1"
   

5. Build and run in standalone mode (API + one worker in-process):

   cd source/
   cargo build --release -p windmill
   ./target/release/windmill
   

6. For separate server and worker processes (production):

   MODE=server  ./target/release/windmill &
   MODE=worker  ./target/release/windmill &
   

7. The REST API is available at http://localhost:8000. Import openapi-bundled.yaml into any OpenAPI-compatible client generator to produce typed clients in TypeScript, Python, Go, etc.:

   npx @openapitools/openapi-generator-cli generate \
     -i source/openapi-bundled.yaml \
     -g typescript-fetch \
     -o ./generated-client
   

Public API

Because this is a Rust binary with an HTTP interface (not a TypeScript library), the "public API" is the REST surface defined in openapi-bundled.yaml. The symbols below are HTTP endpoints, shown as TypeScript fetch signatures for use with a generated client.

POST /api/w/{workspace}/jobs/run/p/{script_path}

async function runScriptByPath(
  workspace: string,
  scriptPath: string,
  body: { args: Record<string, unknown>; scheduled_for?: string },
  token: string
): Promise<{ uuid: string }>

Submits a script for async execution. Returns a job UUID. Use this to enqueue work from any external system.

GET /api/w/{workspace}/jobs_u/completed/get/{id}

async function getCompletedJob(
  workspace: string,
  jobId: string,
  token: string
): Promise<{
  id: string;
  success: boolean;
  result: unknown;
  logs: string;
  started_at: string;
  duration_ms: number;
}>

Retrieves the final result and logs of a completed job. Poll this after enqueuing until success is defined.

POST /api/w/{workspace}/flows/run/f/{flow_path}

async function runFlowByPath(
  workspace: string,
  flowPath: string,
  body: { args: Record<string, unknown> },
  token: string
): Promise<{ uuid: string }>

Enqueues a multi-step flow for execution. Flows chain scripts with branching, loops, and error handlers defined in the flow YAML/JSON.

GET /api/w/{workspace}/jobs/queue

async function listQueuedJobs(
  workspace: string,
  token: string,
  params?: { page?: number; per_page?: number; script_path?: string }
): Promise<Array<{ id: string; script_path: string; created_at: string; running: boolean }>>

Returns all currently queued or running jobs. Useful for building operator dashboards or autoscaling triggers.

Working examples

Scenario - Submit a job and poll for completion

A Node.js service submits a Python data-processing script and waits for the result.

const BASE = "http://localhost:8000";
const WS   = "my-workspace";
const TOKEN = process.env.WINDMILL_TOKEN!;

async function runAndWait(
  scriptPath: string,
  args: Record<string, unknown>
): Promise<unknown> {
  const submitRes = await fetch(
    `${BASE}/api/w/${WS}/jobs/run/p/${scriptPath}`,
    {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${TOKEN}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ args }),
    }
  );
  if (!submitRes.ok) throw new Error(await submitRes.text());
  const { uuid } = await submitRes.json();

  // Poll until complete
  for (let i = 0; i < 120; i++) {
    await new Promise(r => setTimeout(r, 2000));
    const res = await fetch(
      `${BASE}/api/w/${WS}/jobs_u/completed/get/${uuid}`,
      { headers: { "Authorization": `Bearer ${TOKEN}` } }
    );
    if (res.status === 200) {
      const job = await res.json();
      if (!job.success) throw new Error(`Job failed: ${job.logs}`);
      return job.result;
    }
  }
  throw new Error("Timed out waiting for job");
}

const result = await runAndWait("u/admin/process_csv", { file_url: "s3://bucket/data.csv" });
console.log("Result:", result);

Scenario - Trigger a flow and stream logs via SSE

An Express route enqueues a flow and streams live logs back to the browser.

import express from "express";

const app = express();
const BASE  = "http://localhost:8000";
const WS    = "my-workspace";
const TOKEN = process.env.WINDMILL_TOKEN!;

app.get("/run-flow", async (req, res) => {
  // Enqueue flow
  const submitRes = await fetch(
    `${BASE}/api/w/${WS}/flows/run/f/f/onboarding/welcome_flow`,
    {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${TOKEN}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ args: { user_email: req.query.email } }),
    }
  );
  const { uuid } = await submitRes.json();

  // Proxy SSE logs
  res.setHeader("Content-Type", "text/event-stream");
  res.setHeader("Cache-Control", "no-cache");

  const sseRes = await fetch(
    `${BASE}/api/w/${WS}/jobs_u/completed/get_logs/${uuid}`,
    { headers: { "Authorization": `Bearer ${TOKEN}` } }
  );

  const reader = sseRes.body!.getReader();
  const decoder = new TextDecoder();
  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    res.write(decoder.decode(value));
  }
  res.end();
});

app.listen(3001);

Scenario - Inspect the queue and cancel stale jobs

An operator script cancels any job queued more than 10 minutes without starting.

const BASE  = "http://localhost:8000";
const WS    = "my-workspace";
const TOKEN = process.env.WINDMILL_TOKEN!;

async function cancelStaleJobs(maxAgeMs = 10 * 60 * 1000) {
  const res = await fetch(
    `${BASE}/api/w/${WS}/jobs/queue?per_page=100`,
    { headers: { "Authorization": `Bearer ${TOKEN}` } }
  );
  const jobs: Array<{ id: string; created_at: string; running: boolean }> = await res.json();
  const now = Date.now();

  for (const job of jobs) {
    if (job.running) continue;
    const age = now - new Date(job.created_at).getTime();
    if (age > maxAgeMs) {
      await fetch(
        `${BASE}/api/w/${WS}/jobs_u/queue/cancel/${job.id}`,
        {
          method: "POST",
          headers: {
            "Authorization": `Bearer ${TOKEN}`,
            "Content-Type": "application/json",
          },
          body: JSON.stringify({ reason: "Cancelled by stale-job operator" }),
        }
      );
      console.log(`Cancelled stale job ${job.id} (age ${Math.round(age / 1000)}s)`);
    }
  }
}

await cancelStaleJobs();

File walkthrough

• .cargo/ - Cargo registry and compiler flag configuration; sets linker options for faster incremental builds.
• .sqlx/ - Cached sqlx query metadata enabling compile-time SQL type checking without a live DB during CI.
• .vscode/ - Recommended extensions and Rust Analyzer settings for the workspace.
• api/ - Raw OpenAPI source fragments merged into the bundled spec.
• custom_migrations/ - One-off SQL scripts for data migrations too complex for standard migration files.
• generate_mcp_endpoints_tools/ - Binary crate that generates tool definitions for the MCP integration from the OpenAPI spec.
• migrations/ - Sequential sqlx migration files; applied automatically at server startup.
• parsers/ - Crates that parse script source code to extract typed argument schemas for UI generation.
• src/ - Binary entry point: CLI parsing, server/worker mode dispatch, signal handling, startup sequencing.
• windmill-ai/ - Handlers for AI code completion, fix suggestions, and OpenAI-compatible proxy endpoints.
• windmill-alerting/ - Alerting rules evaluation and notification dispatch (webhooks, email, PagerDuty).
• windmill-api/ - Central Axum router that registers all sub-routers; middleware stack (auth, CORS, tracing).
• windmill-api-agent-workers/ - REST handlers for agent-mode workers that pull jobs over HTTP rather than direct DB access.
• windmill-api-assets/ - Serves bundled frontend assets and static files.
• windmill-api-auth/ - Login, token issuance, session validation, SSO callback handlers.
• windmill-api-client/ - Typed HTTP client used internally by workers to report results back to the API.
• windmill-api-configs/ - CRUD endpoints for workspace-level and global configuration key-value pairs.
• windmill-api-debug/ - Heap profiling, pprof, and internal state inspection endpoints (disabled in prod builds).
• windmill-api-embeddings/ - Endpoints that compute and store vector embeddings for semantic script/flow search.
• windmill-api-flow-conversations/ - Stores and retrieves AI conversation history scoped to a flow editor session.
• windmill-api-flows/ - Flow CRUD, versioning, and execution submission endpoints.
• windmill-api-groups/ - Group membership and permission management for workspaces.
• windmill-api-inputs/ - Saved/pinned input sets for scripts and flows.
• windmill-api-integration-tests/ - End-to-end HTTP tests exercising the full API stack against a real DB.
• windmill-api-jobs/ - Job submission, result retrieval, log fetching, and cancellation endpoints.
• windmill-api-npm-proxy/ - Proxies npm registry requests and caches packages for TypeScript workers.
• windmill-api-openapi/ - Serves the bundled OpenAPI spec and Swagger UI.
• windmill-api-schedule/ - Schedule (cron) CRUD and next-run computation endpoints.
• windmill-api-scripts/ - Script CRUD, deployment, archival, and hash-based retrieval.
• windmill-api-settings/ - Instance-wide and per-workspace settings management.
• windmill-api-sse/ - Server-sent event streams for real-time job log tailing.
• windmill-api-users/ - User registration, password management, API token issuance, and permission checks.
• windmill-api-workers/ - Worker registration, heartbeat, and capacity reporting endpoints.
• windmill-api-workspaces/ - Workspace creation, deletion, member management, and export endpoints.
• windmill-audit/ - Records and queries audit log entries for compliance.
• windmill-autoscaling/ - Monitors queue depth and emits scaling signals for worker fleets.
• windmill-common/ - DB connection pool, error types, config structs, and utility functions shared across all crates.
• windmill-dep-map/ - Resolves transitive script dependencies to order execution and caching.
• windmill-duckdb-ffi-internal/ - Unsafe FFI bindings to DuckDB for in-process analytical queries.
• windmill-git-sync/ - Implements push/pull sync between workspace state and a Git repository.
• windmill-indexer/ - Tantivy-based full-text search index for scripts, flows, and job logs.
• windmill-jseval/ - Evaluates JavaScript expressions in flow step conditions using an embedded QuickJS engine.
• windmill-macros/ - Procedural macros for reducing boilerplate in handler and error definitions.
• windmill-mcp/ - Implements the Model Context Protocol server so AI agents can invoke Windmill tools.
• windmill-native-triggers/ - Base infrastructure for all native event-source triggers.
• windmill-oauth/ - OAuth2 client for connecting third-party services and SSO login.
• windmill-object-store/ - Abstraction over S3/GCS/Azure Blob for job large-input and large-result storage.
• windmill-operator/ - Kubernetes CRD operator for declarative Windmill resource management.
• windmill-queue/ - Core job queue: enqueue, dequeue with locking, priority, retry, and concurrency limits.
• windmill-runtime-nativets/ - Deno-based TypeScript/JavaScript execution runtime with npm support.
• windmill-store/ - Persistent key-value state store accessible from running scripts.
• windmill-test-utils/ - Shared test database setup, fixture factories, and mock helpers.
• windmill-trigger/ - Orchestrates trigger lifecycle: start, stop, error recovery, and job dispatch.
• windmill-trigger-azure/ - Azure Service Bus consumer that fires jobs on new messages.
• windmill-trigger-email/ - IMAP poller that fires jobs on incoming email matching filters.
• windmill-trigger-gcp/ - GCP Pub/Sub subscriber trigger.
• windmill-trigger-http/ - Receives inbound HTTP webhooks and maps them to job submissions.
• windmill-trigger-kafka/ - Kafka consumer group trigger for event-driven workflows.
• windmill-trigger-mqtt/ - MQTT broker subscriber trigger.
• windmill-trigger-nats/ - NATS subject subscriber trigger.
• windmill-trigger-postgres/ - Postgres logical replication listener trigger.
• windmill-trigger-sqs/ - AWS SQS long-poll consumer trigger.
• windmill-trigger-websocket/ - WebSocket client trigger that fires jobs on incoming frames.
• windmill-types/ - Canonical domain type definitions (Job, Flow, Script, QueuedJob, CompletedJob, etc.).
• windmill-worker/ - Main worker loop: job dequeue, language runtime dispatch, result reporting, log capture.
• windmill-worker-volumes/ - Manages ephemeral bind-mount volumes for isolated worker job execution.
• build.rs - Detects optional native features (DuckDB, Deno) and sets compile-time environment flags.
• Cargo.toml - Workspace-level manifest with feature flags controlling optional subsystems.
• openapi-bundled.yaml - Single-file OpenAPI 3.0 spec for the complete REST API; use to generate clients.
• openapi-deref.yaml - Same spec with all $ref fully inlined; preferred for code generators that choke on refs.
• oauth_connect.json - Static registry of supported OAuth providers for resource connection.
• oauth_login.json - Static registry of supported OAuth providers for SSO login.
• CLAUDE.md - Notes for AI coding assistants on workspace conventions and build commands.

Common pitfalls and fixes

• DATABASE_URL not set at build time: sqlx macros verify queries at compile time and fail with DATABASE_URL must be set. Fix: set DATABASE_URL in your environment or create a .env file before running cargo build, or use SQLX_OFFLINE=true with the pre-generated .sqlx/ metadata.
• DuckDB compile failure on ARM: The DuckDB FFI crate builds from source and may fail on aarch64 without cmake >= 3.21. Fix: apt-get install cmake and ensure you have at least 8 GB RAM available during the build.
• Deno binary not found at runtime: The TypeScript worker requires a deno binary on PATH or the path set in DENO_PATH. Fix: set DENO_PATH=/path/to/deno or install Deno system-wide.
• Migration hash mismatch: Editing an already-applied migration file causes sqlx to refuse startup with a checksum error. Fix: never edit applied migrations; create a new migration file for any schema change.
• Worker cannot connect to API in split mode: Workers in MODE=worker call back the API using BASE_INTERNAL_URL. If unset, they default to BASE_URL which may be a public hostname with TLS. Fix: set BASE_INTERNAL_URL=http://windmill-server:8000 to use internal cluster networking.
• Token expiry in long-running operator scripts: Default API tokens expire. Fix: create a non-expiring service account token in the Windmill UI under Settings > Tokens, and store it in a secret manager rather than a plain env var.

Vibe-coding prompt template

I have the Windmill backend source in the `source/` directory and a `USAGE.md`
integration guide alongside it.

My project: [describe your project - e.g. "a Node.js Express API that needs to
submit background jobs and retrieve results from a self-hosted Windmill instance"].

Please do the following step by step:

1. Read `USAGE.md` fully to understand the Windmill backend's architecture,
   environment variables, and HTTP API surface.

2. Read `source/openapi-bundled.yaml` to understand the exact request/response
   shapes for the endpoints I need.

3. Generate a typed TypeScript client module (`windmillClient.ts`) using the
   real endpoint paths from the OpenAPI spec. Include functions for:
   - Submitting a script job by path
   - Polling a completed job result
   - Listing queued jobs
   - Cancelling a job by ID
   - Submitting a flow by path

4. Wire `windmillClient.ts` into my existing Express routes at
   [describe your route file location].

5. Add the required environment variables (`DATABASE_URL`, `BASE_URL`,
   `WINDMILL_TOKEN`) to my `.env.example`.

6. Show me how to start the Windmill backend (`source/`) in standalone mode
   alongside my Express app using Docker Compose, mapping port 8000 internally.

7. Highlight any common pitfalls from `USAGE.md` that apply to my setup.

Upstream package: windmill (Rust workspace, AGPLv3).
Source directory: source/
Integration guide: USAGE.md

License and credit

The Windmill backend is licensed under the GNU Affero General Public License v3.0 (AGPLv3). See source/LICENSE for the full text. Commercial licenses and dedicated hosting are available from Windmill Labs.

Upstream project: https://github.com/windmill-labs/windmill Documentation: https://www.windmill.dev/docs/intro/

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.