Set Up Claude Code to Build, Deploy, and Run Kestra Flows

Set up Claude Code so it can write a flow, deploy it to your Kestra instance, and run it from a single prompt.

This page is for anyone who wants to point a coding agent at Kestra and describe the flow they need. In about 15 minutes, you connect four pieces and finish with a flow running on your instance. The steps use Claude Code. If you use Cursor or Codex, pick its tab wherever the commands differ. To compare this setup with AI Copilot in the Kestra UI, see Develop with AI.

What you set up

Prerequisites

• Claude Code installed, or Cursor or Codex. For other agents, see Docs MCP server.
• A terminal on macOS or Linux. On Windows, use WSL.
• Node.js to install the skills with npx. You can also install them manually without Node.js.
• A running Kestra 2.0 instance. If you don’t have one, start one locally in the next step.

Step 1: Start Kestra locally

Skip this step if you already have a Kestra URL and credentials.

With Docker running, start Kestra with the same command as the Quickstart:

docker run --pull=always --rm -it -p 8080:8080 --user=root \
  --name kestra \
  -v kestra_data:/app/storage \
  -v kestra_db:/app/data \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /tmp:/tmp \
  kestra/kestra:latest-slim server local

Open http://localhost:8080 and create your user when the UI prompts you. Keep the username and password: kestractl uses them in Step 5.

For a persistent setup with PostgreSQL, see Docker Compose installation. For Kubernetes and cloud installs, see the Installation guide.

Step 2: Connect the Docs MCP server

The Docs MCP server is a public, read-only endpoint hosted by Kestra at https://api.kestra.io/v1/mcp. It needs no account or API key, and it doesn’t connect to your instance.

Add the server, then list your servers to check that kestra appears:

claude mcp add kestra --transport http https://api.kestra.io/v1/mcp
claude mcp list

{
  "mcpServers": {
    "kestra": {
      "url": "https://api.kestra.io/v1/mcp"
    }
  }
}

codex mcp add kestra --url https://api.kestra.io/v1/mcp
codex mcp list

Cursor has no CLI command for this: save the JSON as .cursor/mcp.json in your project, then check that kestra appears under Cursor Settings > MCP.

Your agent can now look up plugin schemas, search blueprints, and search the Kestra docs. To try it, ask: What properties does the io.kestra.plugin.core.log.Log task accept?

Step 3: Install the Agent Skills

Skills are SKILL.md files that tell your agent how to work with Kestra. From your project folder, run the installer for your agent:

npx skills add kestra-io/agent-skills --agent claude-code

npx skills add kestra-io/agent-skills --agent cursor

npx skills add kestra-io/agent-skills --agent codex

The installer writes the skills to .claude/skills/ for Claude Code, and to .agents/skills/ for Cursor and Codex. To make the skills available in every project, add --global.

This guide uses two of the skills: kestra-flow writes flow YAML against the live flow schema, and kestra-ops validates, deploys, and runs flows with kestractl. For the other skills, see Available skills. To install without Node.js, see Manual installation.

Step 4: Install kestractl

Install kestractl, the Kestra CLI that the kestra-ops skill drives:

curl -fsSL https://raw.githubusercontent.com/kestra-io/kestractl/main/install-scripts/install.sh | bash

The script installs the latest kestractl 3.x release, which works with Kestra 2.x and Kestra 1.3. For an earlier Kestra version, or to choose the install folder, see Installation. For Windows and other platforms, download a binary from the kestractl releases.

Confirm the install:

kestractl --help

Step 5: Connect kestractl to your instance

Add a context with the URL, tenant, and credentials for your instance. A context is a named connection; the commands below name it default and make it the one kestractl uses. Use the command that matches your edition.

For Kestra Open Source, including the local instance from Step 1, use your username and password. The tenant is main:

kestractl config add default http://localhost:8080 main \
  --username YOUR_USERNAME --password YOUR_PASSWORD --default

For Kestra Enterprise, use an API token and your tenant ID:

kestractl config add default https://kestra.example.com YOUR_TENANT \
  --token YOUR_API_TOKEN --default

kestractl saves the context in ~/.kestractl/config.yaml. Check the connection:

kestractl config show
kestractl flows list

The connection works if kestractl flows list returns without an error. An empty list is expected on a new instance.

To manage several instances, add one context per instance and switch with kestractl config use <name>. See Configuration for contexts and environment variables.

Step 6: Write, deploy, and run a flow

Start your agent from your project folder:

claude

cursor .

codex

In Cursor, start a chat in Agent mode once the folder opens.

Ask it to write, deploy, and run a flow in one prompt:

Use kestra-flow to write a flow in the tutorial namespace that calls
https://api.github.com/repos/kestra-io/kestra every hour and logs the
star count. Save it as ./flows/github_stars.yaml. Then use kestra-ops
to deploy it to my Kestra instance, run it, and tell me the result.

The agent uses kestra-flow to look up the HTTP and Log task schemas on the Docs MCP server and write the flow file. It then uses kestra-ops to validate, deploy, and run the flow with kestractl.

To deploy and run the flow yourself instead, run the same commands the agent uses:

kestractl flows validate ./flows/
kestractl flows deploy ./flows/ --override
kestractl executions run tutorial github_stars --wait

Open the Kestra UI. The github_stars flow appears in the tutorial namespace, with one execution that logs the star count.

The flow’s Schedule trigger runs it every hour from now on. When you finish testing, ask the agent to disable the trigger or delete the flow, or do it from the flow page in the UI.

Troubleshooting

Next steps

Try these prompts on your flows:

• Use kestra-flow-hardening to audit ./flows and add retries, timeouts, and failure alerts.
• Find a blueprint for triggering a flow when a file lands in S3.
• What properties does the io.kestra.plugin.jdbc.postgresql.Query task accept?

To go further:

• Agent Skills has more example prompts and explains how to write custom skills.
• kestractl lists every command your agent can run on your instance.
• The Tutorial explains the inputs, outputs, triggers, and error handling in the flows your agent writes for you.
• Ask questions and share what you build in the Kestra community Slack.