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.

Hướng dẫn cài đặt đầy đủ và prompt tích hợp sẽ mở khóa sau khi mua.