How to Use Windmill.dev: The Beginner's Guide (First Deploy, First Script, First Flow, and the Scripts-Are-the-Product Rule)

CodexFuse Team · 2026-11-01T06:05:07.582Z · 14 min read

Windmill.dev is the open-source workflow engine that turns plain Python or TypeScript scripts into internal tools with auto-generated UIs, REST APIs, and cron schedules. This beginner's guide covers the first deploy with Docker Compose, the workspace lesson, your first script and its auto-generated UI, calling it as an API, scheduling, your first flow, and storing secrets the right way.

This guide answers how to use windmill.dev — the open-source workflow engine and developer platform, not the spinning kind. If you searched "how to use windmill" expecting the software, you are in the right place: Windmill (windmill.dev) turns plain scripts in Python, TypeScript, Go, and more into internal tools with auto-generated UIs, REST APIs, and cron schedules, with almost no boilerplate. This is a beginner's guide in the windmill tutorial tradition that skips the feature list and runs one complete arc: deploy, workspace, first script, the auto-UI moment, API, schedule, first flow, and secrets. If you plan to self-host, start with our Docker beginner guide — you will need Docker and Docker Compose before anything else works.

What is Windmill.dev, exactly?

Windmill.dev is an open-source developer platform and workflow engine for building, deploying, and monitoring internal automation and tooling. You write a normal script with typed function parameters; Windmill turns it into a runnable tool with a generated form UI, an API endpoint, a webhook, and a cron schedule — all automatically. Its public repo (windmill-labs/windmill) has around 18,343 stars and 1,135 forks as of November 2026, and the codebase is licensed under AGPLv3 by default.

The one-sentence difference between Windmill and the tools people confuse it with: n8n is no-code-first (drag nodes, optionally write code), Kestra is declarative (define flows in YAML), and Windmill is code-first — the script is the product, and everything else is generated from it. That makes Windmill the lane for developers who already think in functions, not boxes. Code-first workflow automation is the whole pitch: your scripts become the company's internal tools, APIs, and scheduled jobs. If you search for "code first workflow automation" tools, Windmill is the lane where the developer writes plain code instead of dragging boxes.

How do you use Windmill.dev for the first time?

Here is the full beginner arc, end to end. Each step below gets its own section later with the details.

1. Choose Windmill Cloud (free to start, no credit card) or self-host with Docker Compose.
2. Deploy it: one compose file spins up the server, workers, database, and reverse proxy.
3. Sign in and land on the workspace selection screen — create your first workspace.
4. Learn the workspace lesson: everything in Windmill lives inside a workspace.
5. Click + Script and write your first script: one Python function with typed parameters.
6. Watch the auto-UI moment: Windmill builds a working form from your function signature.
7. Hit Test and see the job run with streaming logs, memory usage, and JSON results.
8. Call the same script as a REST API with a single curl command.
9. Turn the script into a scheduled job with a cron expression.
10. Chain scripts into your first flow, then store secrets as variables and resources instead of hardcoding them.

Windmill Cloud vs self-hosted: which one should you pick?

Decide this once, before you deploy — switching later means migrating workspaces. Both paths are legitimate; the trade-off is convenience versus control and cost shape.

The one cost lesson beginners miss: on Windmill Cloud the bill follows worker concurrency, so a flow that fans out into dozens of parallel steps costs more than the same logic run sequentially. Self-hosted, the same parallelism costs only the server you already pay for. Pick Cloud to learn, self-host when your automations become load-bearing.

How do you deploy Windmill with Docker Compose?

You deploy Windmill self-hosted by cloning its repo and starting one compose file — no manual database setup, no separate reverse proxy to configure. You need Docker and Docker Compose on a machine you control; a small VPS works fine (see our guide on what is VPS hosting if that concept is new). The official compose file lives in the windmill-labs/windmill repo:

git clone https://github.com/windmill-labs/windmill.git
cd windmill
docker compose up -d

That one command starts seven services. The official stack is small and readable:

For larger production environments the vendor recommends Kubernetes with their Helm chart instead; for a first deploy, Compose is the documented simple path. If you prefer, generate your starting compose file with our docker-compose generator and paste Windmill's services into it.

What is the workspace lesson every beginner must learn?

Everything in Windmill lives inside a workspace — scripts, flows, variables, resources, and run history are all scoped to one. Right after sign-in you land on a workspace selection screen where you join existing workspaces or create a new one; this is Windmill's team-oriented unit, so treat one workspace as one project or one team. Inside, the sidebar gives you Runs, Variables, Resources, Assets, and Triggers, and the big + Script, + Flow, and + App buttons make the three things you build obvious from the start.

Do not skip naming your workspace well and do not create personal scratch scripts in the shared workspace — the first week of every Windmill install is decided by workspace hygiene.

How do Windmill scripts work, and what is the auto-UI moment?

A Windmill script is a single function with typed parameters — that signature is the entire contract. Click + Script, pick Python, and write something like this:

# refund_tool.py — this becomes an internal tool automatically
def main(customer_email: str, refund_amount: float, reason: str) -> dict:
    """Process a customer refund."""
    # your logic here
    return {"refunded": customer_email, "amount": refund_amount}

The auto-UI moment is what sells Windmill: it reads your function's parameters, derives a JSON Schema input specification from the type annotations, and renders a working form — a text field for the email, a number field for the amount — with zero frontend code. You can refine each field (titles, placeholders, enums, formats like email or date-time, password masking) from the script's Generated UI tab. Hit Test and the job runs immediately: logs stream on the right, you see dependency installation and peak memory usage, and the Result tab shows your return value as JSON.

This is the scripts-are-the-product rule: the function you already know how to write IS the internal tool. The UI, the API, and the schedule are all derived artifacts, never separate things to build.

How do you run a Windmill script as an API?

Every deployed script is automatically an HTTP endpoint — no route file, no server code, no deployment step. Call it with curl using your workspace id and the script's path:

curl -X POST 'http://localhost:8000/api/w/myworkspace/jobs/run/p/f/myfolder/refund_tool' \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"customer_email": "[email protected]", "refund_amount": 42.5, "reason": "damaged"}'

The script also gets a webhook URL for event-driven triggers. This is what makes the windmill api lane different from a plain script folder: each script is a version-controlled, observable, triggerable artifact, and the API exists the moment the script does.

How do you schedule a Windmill script?

Scheduling in Windmill means attaching a cron trigger to a script or flow — that is the entire ceremony. From the script's Triggers tab (or the API's schedules/create endpoint) you set a cron expression and the script becomes a recurring job with full run history, logs, and failure visibility. If you are replacing cron-spaghetti, this is the upgrade: every scheduled run is recorded in the workspace's Runs view with its inputs, logs, and result JSON, instead of vanishing into a server's syslog. The windmill schedule lane is a first-class concept, not a plugin.

How do you build your first Windmill flow?

A flow chains scripts into a workflow: each step is essentially a script, and the canvas orchestrates them. Click + Flow and Windmill opens a guided 18-step tutorial that walks you through inputs, adding nodes, connecting outputs, and writing inline code — take it, because it teaches how Windmill thinks (per the hands-on comparison published October 2026, which confirms the tutorial exists in-product). Then build a real one: a trigger input, a branching step (TypeScript/Bun works well for keyword routing), a storage step using a configured resource, and a notification step using a built-in integration like Slack.

Flows support branches, for-loops, approvals, and retries natively — the four constructs beginners keep re-implementing by hand in plain scripts. A flow's auto-generated UI is built from its flow inputs, so the whole workflow inherits the same form treatment as a single script.

Where do Windmill variables, resources, and secrets go?

They go in the workspace's Variables and Resources sections — never in the script code. A resource is a configured connection (a PostgreSQL database, a Slack workspace, an S3 bucket); a variable holds a value or secret. Scripts read them at runtime, which means you can share a script with a teammate without sharing the credentials it uses. The one beginner mistake that breaks every first Windmill install: hardcoding an API key in the script, then sharing the script. Create the variable first, reference it in code, and let Windmill mask it in the UI.

What is the Windmill Hub, and can you trust its scripts?

The Windmill Hub (hub.windmill.dev) is a public library of community scripts and flows you can fork into your workspace — the fastest way to learn the platform's idioms is to read good ones. The rule: Hub scripts are community code, so audit before production. Read the script, check what resources and permissions it needs, pin what you fork, and treat a forked script as yours from that moment — you own its maintenance. For a beginner, the Hub is a tutorial library first and a dependency source second.

Windmill.dev vs n8n vs Kestra: which lane are you in?

All three are open-source workflow engines, and they do not compete on features so much as on who writes the automation. Windmill is the code-first lane: developers write Python/TypeScript and get UIs, APIs, and cron for free. n8n is the no-code lane: drag-and-drop nodes with optional code, friendlier for mixed technical and non-technical teams (our n8n beginner guide covers it). Kestra is the declarative lane: define everything in YAML for version-controlled, data-engineer-style orchestration.

Pick Windmill when the people building automations are developers who would rather write a function than drag a node. The windmill vs n8n question is really a team-composition question, and the honest answer is that many teams run both: Windmill for the code-first internals, n8n for the visual multi-service workflows.

How do you develop Windmill scripts locally?

You do not have to live in the browser. Windmill ships a wmill CLI with wmill sync pull and wmill sync push to synchronize your workspace to a local directory you can version with GitHub or GitLab, plus a VS Code extension that shows the auto-inferred UI preview next to your code as you edit. Deno scripts use a .deno.ts extension while plain .ts defaults to Bun. The recommended loop is: develop locally with the extension, sync to a staging workspace, test, then promote — Git-based deployment to production is a supported workflow, not an afterthought.

Sources

• Windmill, "Getting started with Windmill" (windmill.dev/docs/getting_started/how_to_use_windmill, fetched 2026-11-01) — Cloud Community Plan terms, SSO sign-up, self-host options, New-button creation options, Hub, local development.
• Windmill, "Auto-generated UIs" (windmill.dev/docs/core_concepts/auto_generated_uis, fetched 2026-11-01) — main-function parameters to JSON Schema to rendered form UI.
• Windmill, "VS Code extension" (windmill.dev/docs/cli_local_dev/vscode-extension, fetched 2026-11-01) — wmill sync pull/push, .deno.ts vs default Bun .ts, UI preview.
• GitHub API, windmill-labs/windmill (fetched 2026-11-01) — ~18,343 stars, 1,135 forks, created 2022-05-05; latest release v1.855.1 published 2026-10-30.
• windmill-labs/windmill LICENSE (raw, fetched 2026-11-01) — AGPLv3 by default, some files Apache-2.0, proprietary license for certain enterprise features.
• windmill-labs/windmill docker-compose.yml (raw main branch, fetched 2026-11-01) — db (postgres:18), windmill_server, windmill_worker, windmill_worker_native, windmill_indexer, windmill_extra, caddy (caddy-l4:2.11.4-1).
• HostAdvice, "Windmill vs n8n: Best Automation Tool for 2026" (2026-10-27, fetched 2026-11-01) — in-product 18-step flow tutorial, first-script experience, teams-under-10 self-host terms, code-first framing.
• dev.to, "Windmill Has a Free Workflow Engine" (2026-03-28, fetched 2026-11-01) — docker compose up -d quick start, script-to-UI/API/cron arc, Cloud free tier 1,000 executions/month.
• dev.to, "Windmill Has a Free API" (2026-03-29, fetched 2026-11-01) — API run path pattern, schedules/create endpoint, auto-UI and approval flows.
• devopspack, "Windmill: Turn Scripts Into Workflows, APIs, and Internal Apps" (fetched 2026-11-01) — Rust backend, Svelte frontend, PostgreSQL as the only database dependency, language list.

Frequently Asked Questions

Is Windmill.dev free for beginners?

Yes, in two ways. Windmill Cloud starts with a Community Plan that includes 1,000 monthly executions and requires no credit card — enough to run this whole windmill for beginners arc. Or self-host for free with Docker Compose; teams under 10 users can self-host for free with some limitations. Watch one cost rule on Cloud: worker concurrency decides the bill as you scale.

How is Windmill different from n8n?

n8n is no-code-first: you drag nodes and optionally write code. Windmill is code-first: you write a function and get the UI, API, and schedule automatically. Developers who think in functions reach for Windmill; mixed teams often prefer n8n's visual canvas.

What programming languages does Windmill support?

Python, TypeScript (Bun runtime by default, Deno via .deno.ts files), Go, Bash, SQL, Rust, GraphQL, and PowerShell, among others. The windmill scripts lane starts with one typed function in any of these — the language choice does not change the UI/API/schedule generation.

Do I need Kubernetes to run Windmill?

No. Kubernetes with the official Helm chart is the recommendation for large production environments, but windmill self hosted starts with Docker Compose on a single machine. The only hard infrastructure requirement is a Postgres database, which the compose file provides.

Can Windmill replace my cron jobs?

That is one of its best beginner use cases. Attach a schedule to any script or flow with a cron expression and every run gets inputs, logs, and JSON results recorded in the workspace — the windmill flows and windmill docker beginner who is drowning in crontab entries usually migrates here first.