cordum

<p align="center"> <img src="dashboard/public/logo.png" alt="Cordum" width="200"/> </p> <h1 align="center">Cordum</h1> <p align="center"> <a href="https://artifacthub.io/packages/helm/cordum/cordum"><img src="https://img.shields.io/endpoint?url=https://artifacthub.io/badge/repository/cordum" alt="Artifact Hub" /></a> </p> <p align="center"> <strong>Know What Your AI Agents Are Doing. Before They Do It.</strong><br/> The Source-Available <strong>Agent Control Plane</strong> for Governance, Safety, and Trust.<br/> <em>Includes <strong>Cordum Edge</strong> — a Compliance Firewall for Claude Code and other local AI-agent actions.</em> </p> <p align="center"> <a href="https://github.com/cordum-io/cordum/stargazers"><img src="https://img.shields.io/github/stars/cordum-io/cordum?style=social" alt="Stars"/></a> <a href="https://github.com/cordum-io/cordum/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-BUSL--1.1-blue" alt="License"/></a> <a href="https://github.com/cordum-io/cordum/releases"><img src="https://img.shields.io/github/v/release/cordum-io/cordum?sort=semver" alt="Release"/></a> <a href="https://github.com/cordum-io/cordum/actions/workflows/ci.yml"><img src="https://github.com/cordum-io/cordum/actions/workflows/ci.yml/badge.svg" alt="CI"/></a> <a href="https://goreportcard.com/report/github.com/cordum-io/cordum"><img src="https://goreportcard.com/badge/github.com/cordum-io/cordum" alt="Go Report Card"/></a> <a href="https://discord.gg/nvHzPCcWWt"><img src="https://img.shields.io/badge/discord-join-5865F2?logo=discord&logoColor=white" alt="Discord"/></a> <a href="https://github.com/cordum-io/cap"><img src="https://img.shields.io/badge/protocol-CAP%20v2-green" alt="CAP Protocol"/></a> </p> <p align="center"> <a href="https://discord.gg/nvHzPCcWWt">Discord</a> · <a href="https://github.com/cordum-io/cordum/discussions">Discussions</a> · <a href="docs/">Docs</a> </p>

---

Quickstart

First Time?

| Goal | Path | |------|------| | Just want to try it? | ./tools/scripts/quickstart.sh — one-command install from source (Option A below) | | Run the full stack from pre-built images? | docker compose pull && docker compose up -d (Option B below) | | Developing Cordum? | See Development |

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).

<details> <summary>Verifying image signatures</summary>

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.

</details> <details> <summary>Manual setup (without docker compose)</summary>

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

</details> <details> <summary>Deploy to Kubernetes</summary>

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.

</details>

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

| Image | GHCR | Docker Hub | |-------|------|------------| | api-gateway | ghcr.io/cordum-io/cordum/api-gateway | cordum/api-gateway | | scheduler | ghcr.io/cordum-io/cordum/scheduler | cordum/scheduler | | safety-kernel | ghcr.io/cordum-io/cordum/safety-kernel | cordum/safety-kernel | | workflow-engine | ghcr.io/cordum-io/cordum/workflow-engine | cordum/workflow-engine | | context-engine | ghcr.io/cordum-io/cordum/context-engine | cordum/context-engine | | mcp | ghcr.io/cordum-io/cordum/mcp | cordum/mcp | | dashboard | ghcr.io/cordum-io/cordum/dashboard | cordum/dashboard |

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

Ports

| Port | Service | |------|---------| | 8082 | Dashboard | | 8081 | API Gateway (HTTPS) | | 9080 | gRPC Gateway | | 4222 | NATS | | 6379 | Redis | | 9092 | Gateway Metrics | | 9093 | Workflow Engine Health | | 50051 | Safety Kernel (gRPC) | | 50400 | Context Engine (gRPC) |

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

| Issue | Fix | |-------|-----| | Port already in use | docker compose down then retry, or check lsof -i :8082 | | Docker out of memory | Allocate at least 4 GB RAM to Docker Desktop | | Can't login to dashboard | Default is admin / ChangeMe123! (in .env as CORDUM_ADMIN_PASSWORD); ensure CORDUM_USER_AUTH_ENABLED=true. Custom passwords must be ≥12 chars + uppercase + digit + special | | TLS/SSL cert errors | Remove ./certs/ and re-run — certs auto-regenerate | | openssl not found | Not needed — quickstart.sh auto-generates keys without it | | Go build fails | Requires Go 1.26.3+ — check with go version | | Stale config after changes | redis-cli DEL cfg:system:default then restart |

For detailed troubleshooting, see docs/troubleshooting.md.

See a 3-verdict demo

Once the stack is up, install the demo-quickstart pack and run the governance demo:

cordumctl pack install ./demo/quickstart/pack
cordumctl demo run quickstart

A single hello, operator! workflow fans out to three topics and exercises every safety-kernel decision class in under 30 seconds:

  +--------------------+--------------------------+--------------------+---------
  | Step               | Topic                    | Verdict            | Reason
  +--------------------+--------------------------+--------------------+---------
  | greet              | job.demo-quickstart.greet           | ALLOW              | Safe…
  | attempt_delete     | job.demo-quickstart.delete-all      | DENY               | Block…
  | escalate_admin     | job.demo-quickstart.admin           | REQUIRE_APPROVAL   | Sign…
  +--------------------+--------------------------+--------------------+---------

Full walkthrough, rule-by-rule explanation, and extension recipe: demo/quickstart/README.md.

Edge Quickstart (Compliance Firewall for Claude Code)

Cordum Edge governs Claude Code tool calls in the developer's terminal — the hook denies risky actions before they run, requires approval on edits, and exports a redacted evidence bundle for every session. Once the platform stack is up (above), point Claude Code at Cordum:

export CORDUM_GATEWAY=https://localhost:8081
export CORDUM_API_KEY=$(grep CORDUM_API_KEY .env | cut -d= -f2)
export CORDUM_TENANT_ID=default
./bin/cordumctl edge claude

The wrapper renders a temporary settings.json, spawns cordum-agentd on a local loopback nonce, and starts Claude Code with the command hook installed. Read .env is denied; Edit/Write requi