How the Kestra Webserver Serves the API and UI

For the complete documentation index, see llms.txt. For a full content snapshot, see llms-full.txt. Append .md to any kestra.io/docs/* URL for plain Markdown.

The Webserver is the server component that serves the Kestra API and UI.

It is the only component that serves user traffic. It also receives webhook calls, streams live execution updates to the UI, and checks every request against your authentication settings. Each section below links to the page that documents how to configure the feature.

What the Webserver does

The Webserver listens on port 8080 by default. Change it with micronaut.server.port or the --port option of any kestra server command. To serve Kestra under a path such as /kestra, set micronaut.server.context-path; the UI follows it. See reverse proxy configuration.

The Webserver serves:

  • The REST API under /api/v1/{tenant}/.... In the open-source edition, a request without a tenant, such as /api/v1/flows/search, is served as the main tenant, which is the only allowed tenant. A request for any other tenant returns 400. See the API reference.
  • The UI under /ui, and the OpenAPI specification under /swagger.
  • Live update streams for executions and logs.
  • Webhook trigger calls.
  • File uploads and downloads, such as execution files, file inputs, and namespace files, which it reads from and writes to internal storage.
  • The MCP server and AI Copilot endpoints.

The Webserver doesn’t run tasks, and it doesn’t evaluate Schedule or polling triggers. Those run on Workers and the Scheduler.

Embedded Indexer and Worker Controller

By default, kestra server webserver also starts an embedded Indexer and an embedded Worker Controller. With the defaults, a Webserver process therefore also listens on the Worker Controller’s gRPC port, 50051, and writes logs, metrics, and execution statistics.

To run those components separately, start the Webserver with --no-indexer or --no-controller. See kestra server webserver.

How execution actions work

The Webserver doesn’t change executions itself, because only the Executor writes them. When you create, restart, replay, pause, resume, kill, or relabel an execution, the Webserver sends a command or a kill request to the Executor and waits for the Executor to apply it. Creating an execution works the same way: the execution is saved by the Executor, not by the Webserver.

  • A single action waits up to kestra.async-operations.wait-timeout (default PT30S) for the Executor. If the Executor doesn’t respond in time, the API returns 504 Gateway Timeout.
  • A bulk action, such as one sent to a by-ids or by-query endpoint, returns 202 Accepted immediately with an operation ID and the number of executions it targets.
  • Creating an execution with ?wait=true keeps the request open until the execution ends. See synchronous executions.

A few operations write directly to the repository instead of going through the Executor:

  • Deleting an execution. By default, this also deletes its logs, metrics, and internal storage files.
  • Creating, updating, and deleting flows.

Trigger actions

The Webserver doesn’t change trigger state either, because only the Scheduler writes it. When you unlock, restart, enable, disable, or delete a trigger, or create, pause, resume, or delete a backfill, the Webserver sends an event to the Scheduler:

  • An action on a single trigger waits up to kestra.async-operations.wait-timeout for the Scheduler. It returns 504 Gateway Timeout if the Scheduler doesn’t respond in time, and 409 Conflict if the action can’t be applied, for example when the Scheduler reports a failure or you unlock a trigger that isn’t locked.
  • A bulk action, such as one sent to a by-triggers or by-query endpoint, returns 202 Accepted immediately with an operation ID and the number of triggers it targets.

Live updates

The UI follows a running execution and its logs through server-sent event (SSE) streams. Each stream closes after one hour without a new update. When you open an execution right after creating it, the Webserver waits up to 10 seconds for the execution to exist before returning 404.

Each Webserver replica reads execution and log updates from the queue and forwards them to the streams opened on that replica. Any replica can serve any stream, so a load balancer in front of several Webservers needs no sticky sessions. A replica stops reading updates while no one is following an execution.

Webhooks

The Webserver receives Webhook trigger calls at /api/v1/{tenant}/executions/webhook/{namespace}/{flowId}/{key}, with GET, POST, and PUT.

  • Webhook routes don’t require authentication. The trigger’s key acts as the secret, and the Webserver compares it in constant time.
  • An unknown flow and a wrong key both return the same 404, so a caller can’t tell which one failed.
  • A disabled flow or an invalid flow returns 409.
  • The Webserver evaluates the Webhook trigger itself, then sends the new execution to the Executor. Large bodies and multipart files can be streamed to internal storage before the execution exists.

To restrict who can reach webhook endpoints, see security hardening.

Authentication

In the open-source edition, the Webserver protects the API with basic authentication. The username must be an email address, and the password must be at least 8 characters long with an uppercase letter, a lowercase letter, and a digit. Credentials are stored hashed in the repository, so every Webserver replica accepts the same credentials. If you can’t sign in, see basic auth troubleshooting.

Requests authenticated with a cookie are also protected against cross-site request forgery: a POST, PUT, PATCH, or DELETE without a valid CSRF token returns 403. API clients that send an Authorization header aren’t affected.

Maintenance mode

The Webserver keeps serving the API and UI while the instance is in maintenance mode. Its embedded Indexer and Worker Controller pause with the rest of the cluster, and execution actions are held by the paused Executor until maintenance ends.

Running the Webserver

Scaling and load balancing

The Webserver keeps no session state, so you can run as many replicas as you need behind a load balancer. See high availability for health checks and deployment patterns, and reverse proxy configuration for running behind a proxy.

Ports and endpoints

PortServes
8080API, UI, webhooks, live streams, and /ping, which returns pong without authentication
8081Management endpoints: /health, /health/liveness, /health/readiness, /metrics, /prometheus, and /version
50051gRPC for the embedded Worker Controller, unless you start the Webserver with --no-controller

See Kestra endpoints for the full list of management endpoints.

Configuration

PropertyDefaultPurpose
micronaut.server.max-request-size10GBMaximum size of a request body
micronaut.server.multipart.max-file-size10GBMaximum size of an uploaded file
micronaut.server.idle-timeout, read-idle-timeout, write-idle-timeout60mHow long an idle connection stays open
kestra.async-operations.wait-timeoutPT30SHow long an execution action waits for the Executor before returning 504
kestra.webserver.ui.enabledtrueSet to false to serve the API only. See Disabling the UI.
kestra.webserver.security-headers.*enabledSecurity headers added to every response. See Security response headers.

For the other server and UI settings, see Network and HTTP settings and UI and webserver settings.

Monitoring and troubleshooting

The Webserver publishes a counter for each execution action it forwards, such as webserver.execution.restart.total and webserver.execution.kill.total. It also publishes sse.connections.active and sse.connections.opened.total, tagged with sse_type, for live streams. See Kestra’s metrics.

Every request is logged by the io.kestra.webserver.access logger, except requests for UI assets, health checks, and metrics.

When a specific queue record blocks the Webserver’s embedded components, start it with --ignore-queue-records or --ignore-indexer-records to skip that record while you investigate. These flags are for troubleshooting only.

Was this page helpful?