Orchestration

How Kestra, the host bridge, an AI provider, and Langfuse connect.

The local stack contains Kestra to run workflows, Langfuse to record traces, and a bridge supplied by this repository to connect Kestra to an AI provider. Docker Compose runs Kestra and Langfuse with their supporting PostgreSQL, ClickHouse, Redis, and MinIO services. The bridge runs separately on your machine, where it can use your local Codex CLI, project files, and authentication. It can also call the OpenAI API when configured to do so.

How the pieces connect

Orchestration Kestra Runs workflows and sends AI tasks.

Connection Bridge Accepts the request and calls the configured AI provider.

Inference Codex CLI / OpenAI API Executes the AI task and returns its response.

Tracing Langfuse Records the response and observed token usage.

Kestra makes an authenticated HTTP POST to the host bridge at /. The request carries a text task, an X-Request-Id, and the shared bearer token. The bridge starts a fresh Codex CLI execution on the host or sends the task to the OpenAI API, returns a JSON result to Kestra, and sends a trace to Langfuse. The bridge must be running for Kestra to reach either provider.

Start the architecture locally

You need Node.js 24+, npm, and Docker with Compose 2.24+. To use the local Codex CLI, install it and authenticate with codex login. From the repository root, create .env and fill its required secrets. Set INFERENCE_ENABLED=true and choose AI_PROVIDER=codex or AI_PROVIDER=openai-api; the API option also requires AI_MODEL and OPENAI_API_KEY. See the configuration guide for the secret-generation commands and other settings. If .env already exists, edit it instead of copying the example over it.

cp .env.example .env
docker compose up -d --build

Then start the bridge on the host machine, under your usual user account (the one authenticated with Codex CLI when using that provider):

npm start

Keep this process running. Kestra reaches the host bridge through BRIDGE_URL. The local service addresses are:

Kestra: http://localhost:3000
Langfuse: http://localhost:3001
Bridge health: http://localhost:8787/health