Documentation

Run Cordum locally.

Docker Compose quickstart for the control plane. The repo is public under BUSL-1.1.
View the repo on GitHub

Estimated time: 15-20 min

Prerequisites

Docker + Docker Composecurljq

Option 1: Quickstart script

bash

# From the repo root
export CORDUM_API_KEY="$(openssl rand -hex 32)"
export CORDUM_TENANT_ID=default
./tools/scripts/quickstart.sh

This is the fastest way to bring up a local control plane with sensible defaults and smoke checks.

./tools/scripts/quickstart.sh

Starts the local stack and runs smoke checks against gateway, scheduler, safety kernel, workflow engine, NATS, and Redis.

go run ./cmd/cordumctl up

Alternative one-command local bring-up via CLI if you prefer running directly from source.

Option 2: Docker Compose (Full Stack)

terminal

# From the repo root
docker compose build
docker compose up -d

This boots the API gateway, scheduler, safety kernel, workflow engine, NATS, and Redis.

2. Verify Installation

Run the smoke scripts to create workflows, trigger runs, and verify CLI output.

terminal

./tools/scripts/platform_smoke.sh
./tools/scripts/cordumctl_smoke.sh

3. Access Dashboard

URLhttp://localhost:8082

The dashboard reads /config.json for API credentials. See dashboard docs for configuration details.

Inspect Data

redis-cli

docker exec cordum-redis-1 redis-cli get res:<job_id>

Result pointers are stored in Redis under res:<job_id>.

Reset State

terminal

docker compose exec redis redis-cli FLUSHALL
docker compose down -v

The second command removes JetStream state and the Redis volume.

Optional: connect via MCP

stdio MCP server

go run ./cmd/cordum-mcp --addr http://localhost:8081 --api-key "$CORDUM_API_KEY"

See MCP server docs for stdio and gateway HTTP/SSE modes, auth headers, and client setup.

Troubleshooting

NATS connection refused

Port 4222 is already in use or the NATS container hasn't started. Check with: docker compose ps nats. If another process holds the port, stop it or change NATS_PORT in your .env file.

Redis connection failed

Port 6379 is in use by another Redis instance. Check with: docker compose ps redis. Stop conflicting Redis processes or change REDIS_PORT in your .env file.

401 Unauthorized on API calls

CORDUM_API_KEY is not set or doesn't match the running stack. Re-export it and ensure docker-compose reads the same value from .env. Restart the gateway after changes.

Dashboard shows no data

The dashboard reads /config.json for API credentials. Ensure CORDUM_API_KEY and CORDUM_TENANT_ID match the running stack. Rebuild the dashboard container after config changes.

Docker build fails

Clear the Docker build cache with: docker compose build --no-cache. If behind a corporate proxy, configure Docker's HTTP_PROXY settings. Ensure Docker has sufficient disk space.

cordumctl not found

Build from source with: go build -o ./bin/cordumctl ./cmd/cordumctl and add ./bin to your PATH, or run directly with: go run ./cmd/cordumctl <args>.

Environment Customization

Key environment variables you can customize in your .env file or shell:

.env

# Required
CORDUM_API_KEY="$(openssl rand -hex 32)"
CORDUM_TENANT_ID=default

# Port overrides (defaults shown)
GATEWAY_HTTP_PORT=8081
GATEWAY_GRPC_PORT=8080
DASHBOARD_PORT=8082
NATS_PORT=4222
REDIS_PORT=6379

# Safety policy override
CORDUM_SAFETY_POLICY_PATH=./config/safety.yaml

# Enable RBAC (enterprise)
CORDUM_REQUIRE_RBAC=false

To override the default safety policy, edit config/safety.yaml and restart the safety kernel. The default policy denies sys.* topics and allows job.* for the default tenant.

Next Steps

Try a Policy Demo

Write your first YAML policy, test it with the simulate API, and see how the Safety Kernel enforces governance before any action runs.

Architecture

Understand the NATS topic topology, Redis state pointers, and how the control plane components interact.

Worker Development

Build your first CAP worker using the runtime SDK. Subscribe to job topics and write results.

Workflow Engine

Define DAG workflows with approval gates, retries, and failure semantics for multi-step agent tasks.

CLI Reference

Explore cordumctl commands for jobs, workflows, approvals, policy management, and pack installation.