Quick Start

Get the workflow engine running locally in under 5 minutes.

Prerequisites

Docker and Docker Compose

1. Clone and configure

git clone https://github.com/excalibase/excalibase-workflow.git
cd excalibase-workflow

cp .env.example .env

Edit .env to add API keys if you want to use AI tasks:

OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GEMINI_API_KEY=...

These are optional. HTTP, transform, script, and flow control tasks work without any keys.

2. Start all services

docker compose up -d --build

This starts 6 services:

Service	Port	Description
postgres	5434	PostgreSQL 16 with pgvector
nats	4222	NATS JetStream message queue
dind	2375	Docker-in-Docker for script tasks
backend	8080	API server (Go)
worker	—	Task worker (scales independently)
frontend	3000	Web UI (React)

On first boot, database migrations run automatically and 3 demo workflows are seeded.

3. Open the UI

http://localhost:3000

You'll see the dashboard with the seeded workflows ready to run.

4. Run your first workflow

Via the UI

Click Run on any workflow in the dashboard.

Via the API

# List available workflows
curl -s http://localhost:8080/api/v1/flows | jq '.[].name'
# → "hello-world"
# → "data-pipeline"
# → "http-transform"

# Get a flow ID
FLOW_ID=$(curl -s http://localhost:8080/api/v1/flows | jq -r '.[0].id')

# Execute it
curl -s -X POST http://localhost:8080/api/v1/flows/$FLOW_ID/execute | jq
# → { "executionId": "...", "status": "QUEUED", "tasksTotal": 3 }

5. Check execution status

EXEC_ID="<executionId from above>"

curl -s http://localhost:8080/api/v1/executions/$EXEC_ID | jq '{
  status: .execution.status,
  duration: .execution.durationMs,
  tasks: [.tasks[] | {name: .taskName, status: .status}]
}'

{
  "status": "SUCCESS",
  "duration": 1650,
  "tasks": [
    { "name": "seed-data", "status": "SUCCESS" },
    { "name": "high-scorers", "status": "SUCCESS" },
    { "name": "ranked-users", "status": "SUCCESS" },
    { "name": "summary", "status": "SUCCESS" }
  ]
}

6. Create your own workflow

curl -X POST http://localhost:8080/api/v1/flows \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-first-workflow",
    "yamlContent": "name: my-first-workflow\ntasks:\n  - name: greet\n    type: transform.set\n    properties:\n      values:\n        message: Hello from my workflow!\n  - name: log-it\n    type: util.log\n    depends_on: [greet]\n    properties:\n      message: '\''{{ outputs[\"greet\"][\"message\"] }}'\''\n"
  }'

Or create it via the UI editor at http://localhost:3000/workflows/new.

Scale workers

# Run 3 workers for higher throughput
docker compose up -d --scale worker=3

Next steps

Task Types — explore all 83 built-in executors
AI Capabilities — connect OpenAI, Anthropic, Gemini, Ollama, MCP servers
API Reference — full REST API documentation
Deployment — Kubernetes and Helm chart guide

Introduction

Task Types