cordum

Quickstart

First Time?

Option A: Install from source

One command stands up the full stack — API gateway, scheduler, safety kernel, workflow engine, context engine, dashboard, NATS, and TLS-secured Redis — with auto-generated secrets, auto-provisioned certificates, and a post-deploy smoke test that exercises a real approval workflow:

git clone https://github.com/cordum-io/cordum.git
cd cordum
./tools/scripts/quickstart.sh

Prerequisites: Docker Desktop v4+ (or Engine v20.10+ with Compose v2, ≥ 4 GB RAM allocated), Go 1.26.3+ (for first-run cert generation), and curl. On Windows use MSYS2 / Git Bash / WSL.

What you get at the end:

• Dashboard at http://localhost:8082 — log in as admin / ChangeMe123! (the default dev password, also saved to .env as CORDUM_ADMIN_PASSWORD; change it before exposing the stack).
• Gateway at http://localhost:8081 with a generated CORDUM_API_KEY in .env.
• TLS CA, server, and client keypairs under ./certs/.
• A working approval-gate workflow proven by the built-in platform_smoke.sh run.

Full walkthrough, platform notes, and troubleshooting: docs/quickstart.md.

Option B: Run the published images

Prerequisites: Docker Desktop v4+ or Docker Engine v20.10+ with the Compose v2 plugin (≥ 4 GB RAM allocated), jq (recommended, for parsing API responses), and Go 1.26.3+ (for one-time local cert generation — docker compose mounts ./certs but does not create it).

git clone https://github.com/cordum-io/cordum.git
cd cordum
go run ./cmd/cordumctl generate-certs   # writes ./certs/{ca,server,client}
export CORDUM_API_KEY=$(openssl rand -hex 32)
export REDIS_PASSWORD=$(openssl rand -hex 16)
docker compose pull         # pulls every Cordum service from ghcr.io
docker compose up -d        # starts the stack — no image build needed

Dashboard: http://localhost:8082 Login: this path leaves user auth off by default — sign in on the dashboard with your CORDUM_API_KEY. To enable admin password login instead, set CORDUM_USER_AUTH_ENABLED=true and a policy-compliant CORDUM_ADMIN_PASSWORD (≥ 12 chars, with an uppercase letter, a digit, and a special character) in .env, then docker compose up -d. (The quickstart script in Option A does this for you.)

Pin a specific release by exporting CORDUM_VERSION=1.2.3 before docker compose pull. Defaults to :latest, which only moves on stable release tags (pre-release suffixes such as -rc.1 never promote :latest).

Every release-tag image is signed with cosign keyless OIDC. The example below verifies api-gateway; repeat the same command (swapping the image name) for each of the seven Cordum images before deploying to production — verifying one image does not attest the rest:

cosign verify ghcr.io/cordum-io/cordum/api-gateway:1.2.3 \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --certificate-identity-regexp 'https://github\.com/cordum-io/cordum/\.github/workflows/docker\.yml@refs/tags/v.*'

See docs/deployment/images.md for the full image catalogue, a verify-all-images snippet, multi-arch pull instructions, and tag policy.

cp .env.example .env
# Edit .env: set CORDUM_API_KEY (or generate: openssl rand -hex 32)
export CORDUM_API_KEY="your-key-here"
go run ./cmd/cordumctl up
open http://localhost:8082

helm install cordum oci://ghcr.io/cordum-io/cordum/charts/cordum \
  --namespace cordum --create-namespace \
  --set secrets.apiKey=$(openssl rand -hex 32) \
  --set redis.auth.password=$(openssl rand -hex 32) \
  --set ingress.enabled=true \
  --set ingress.className=nginx \
  --set ingress.api.host=api.cordum.example.com \
  --set ingress.dashboard.host=cordum.example.com

--set values land in the Helm release's stored values (and your shell history) — fine for a quick eval, but for production prefer redis.auth.existingSecret (see cordum-helm/values.yaml) over redis.auth.password, and patch secrets.apiKey into the rendered Secret out-of-band rather than passing it on the command line; that chart doesn't yet have an existingSecret equivalent for the API key.

See cordum-helm/ for the full Helm chart reference. The chart is also available on Artifact Hub.

Container images (multi-arch: linux/amd64 + linux/arm64):

Full catalogue, tag policy, cosign verification recipe, and multi-arch notes: docs/deployment/images.md.

Ports

Port conflicts? If any port is already in use, either stop the conflicting service or override ports in your .env file before starting the stack.

After Setup

# Load the generated API key into this shell (skip if already exported)
export CORDUM_API_KEY=$(grep CORDUM_API_KEY .env | cut -d= -f2)

# Submit a test job
curl -sS --cacert ./certs/ca/ca.crt \
  -X POST https://localhost:8081/api/v1/jobs \
  -H "X-API-Key: $CORDUM_API_KEY" -H "X-Tenant-ID: default" \
  -H "Content-Type: application/json" \
  -d '{"topic":"job.default","prompt":"hello"}'

# Stop the stack
docker compose down

# View logs
docker compose logs -f api-gateway

Troubleshooting