cordum

Cordum

Know What Your AI Agents Are Doing. Before They Do It.

The Source-Available Agent Control Plane for Governance, Safety, and Trust.

Includes Cordum Edge — a Compliance Firewall for Claude Code and other local AI-agent actions.

· ·

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

Verifying image signatures

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.

[cosign]: https://docs.sigstore.dev/cosign/overview/

Manual setup (without docker compose)

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

Deploy to Kubernetes

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

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 requires approval; safe reads pass through

untouched. The dashboard shows the live session timeline at

/edge/sessions.

For approved destructive actions, Edge does not trust the approval store alone:

the ProvenanceGate also requires a resolved approval audit event for the same

tenant, `approval_ref`, and `action_hash`. An approval-requested event by itself

does not satisfy provenance, and raw prompts, transcripts, and tool payloads are

kept out of audit evidence.

Full 30-minute walkthrough: docs/quickstart-edge.md.

Reference: docs/edge/README.md.

The Problem: The Agent Risk Gap

Enterprises are rushing to deploy Autonomous AI Agents, but they're hitting a wall of risk. According to Gartner, 74% of enterprises see AI agents as a new attack vector, and over 40% of agentic AI projects will be canceled due to inadequate risk controls.

The current landscape leaves teams with a choice:

1. Restrict agents to simple, low-value read-only tasks.

2. Accept the risk of autonomous agents taking destructive, unmonitored actions.

Without a dedicated governance layer, you're flying blind:

• No visibility: You don't know what your agents are doing until *after* they do it.
• No safety rails: There's no way to intercept dangerous operations before they execute.
• No human-in-the-loop: Sensitive actions happen without manual oversight.
• No audit trail: When things go wrong, you can't reconstruct the chain of thought.

The Solution: Cordum Agent Control Plane

Cordum is an Agent Control Plane that provides a deterministic governance layer for probabilistic AI minds. It allows you to define, enforce, and audit the behavior of your Autonomous AI Agents across any framework or model.

graph TB
    subgraph CP [AGENT CONTROL PLANE]
        direction LR
        G[API Gateway] --- S[Scheduler] --- SK[Safety Kernel]
        S --- WE[Workflow Engine]
    end
    
    subgraph AGENTS [AUTONOMOUS AGENT POOLS]
        direction LR
        A1[Financial Ops]
        A2[Data Science]
        A3[Customer Service]
    end
    
    CP -->|Governed Jobs| AGENTS
    AGENTS -->|Audit Trail| CP

Governance Across the Lifecycle

Cordum's Before/During/Across framework provides exhaustive control over your agent operations:

graph LR
    subgraph BEFORE [1. BEFORE - Governance]
        P[Policy Evaluation] --> S[Safety Gating]
        S --> H[Human Approval]
    end
    subgraph DURING [2. DURING - Safety]
        M[Real-time Monitoring] --> C[Circuit Breakers]
        C --> A[Live Approvals]
    end
    subgraph ACROSS [3. ACROSS - Observability]
        F[Fleet Health] --> T[Audit Trail]
        T --> O[Optimization]
    end
    BEFORE --> DURING
    DURING --> ACROSS

• BEFORE (Governance): Define declarative policies that evaluate job requests *before* an agent executes. Trigger safety kernel checks, throttle risky actions, or flag operations for human approval.
• DURING (Safety): Real-time visibility into active agent runs. Monitor progress, handle step-level approvals, and enforce timeouts or circuit breakers on the fly.
• ACROSS (Observability): Manage your entire fleet from a single control plane. Aggregate audit trails, track capability-based routing, and observe agent pool health in real-time.

Cordum Edge: Compliance Firewall for AI agents

Cordum Edge extends the control plane to local AI-agent actions. For Claude Code,

`cordumctl edge claude` launches the real P0 path — command hook, local

`cordum-agentd`, Gateway Edge APIs, Safety Kernel policy/evaluate, approvals,

artifact pointers, and dashboard evidence.

Cordum stays quiet until governance matters. Developers see Cordum exactly when

it protects them, their team, and production: before risky tools run, when an

action needs approval, and when evidence must be exported. The wrapper is the

developer/demo path; enterprise enforcement requires managed Claude settings and

endpoint controls.

Approval provenance is resolved-only: destructive retries must have a matching

approved approval record and a canonical resolved approval audit event for the

same tenant/ref/hash. Requested-only audit rows are lifecycle context, not proof

that the action was approved.

Start here: Edge overview, Claude Code guide,

manual demo, and Edge API.

Development

The published-images path above pulls Cordum binaries from `ghcr.io`.

Contributors who need to rebuild from source use the development override

file:

make dev-up      # docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d --build
make dev-logs    # tail compose logs
make dev-down    # docker compose down

`docker-compose.dev.yml` re-pins every Cordum service to a local

`cordum/:dev` tag and forces the `build:` context, so source

changes are reflected on the next `--build`. Upstream images (NATS,

Redis) are untouched. See `Makefile` and `docker-compose.dev.yml` for

full details.

Other useful contributor commands:

Key Features

Architecture

cordum/
├── cmd/                          # Service entrypoints + CLI
│   ├── cordum-api-gateway/       # API gateway (HTTP/WS + gRPC)
│   ├── cordum-scheduler/         # Scheduler + safety gating
│   ├── cordum-safety-kernel/     # Policy evaluation
│   ├── cordum-workflow-engine/   # Workflow orchestration
│   ├── cordum-context-engine/    # Optional context/memory service
│   └── cordumctl/                # CLI
├── core/                         # Core libraries
│   ├── controlplane/             # Gateway, scheduler, safety kernel
│   ├── context/                  # Context engine implementation
│   ├── infra/                    # Config, storage, bus, metrics
│   ├── protocol/                 # API protos + CAP aliases
│   └── workflow/                 # Workflow engine
├── dashboard/                    # React UI
├── sdk/                          # SDK + worker runtime
├── cordum-helm/                  # Helm chart
├── deploy/k8s/                   # Kubernetes manifests
└── docs/                         # Documentation

Documentation

Protocol: CAP — The Open Standard for Agent Governance

Cordum implements CAP (Cordum Agent Protocol), an open protocol specifically designed for distributed AI agent governance. CAP provides a unified interface for defining agent capabilities, submitting jobs, and enforcing safety policies across heterogeneous agent pools.

CAP vs. MCP: Why You Need Both

While both are essential, they solve different parts of the agent stack:

• MCP is for *within* the agent — it defines how a model calls local tools.
• CAP is for *above* the agent — it defines the governance control plane for the entire agent fleet.

Use CAP for high-level orchestration and safety gating, and MCP inside your agents for fine-grained tool integration.

Read the full deep dive: MCP vs CAP: Why Your AI Agents Need Both Protocols

MCP Server

Cordum includes an MCP server framework with:

• Standalone stdio mode via `cmd/cordum-mcp` (for Claude Desktop/Code local integration)
• Gateway HTTP/SSE mode via `/mcp/message` and `/mcp/sse` (when `mcp.enabled=true`)

See docs/mcp-server.md for setup, auth headers, and client configuration examples.

SDK

The Go SDK makes it easy to build CAP-compatible workers:

import (
    "log"

    "github.com/cordum/cordum/sdk/runtime"
)

type Input struct {
    Prompt string `json:"prompt"`
}

type Output struct {
    Summary string `json:"summary"`
}

func main() {
    // AllowUnsigned is required when the worker holds no signing keys;
    // CAP fails closed at startup otherwise. Provision worker trust keys
    // for anything beyond local development -- see docs/sdk/handshake.md.
    agent := &runtime.Agent{Retries: 2, AllowUnsigned: true}

    runtime.Register(agent, "job.summarize", func(ctx runtime.Context, input Input) (Output, error) {
        // Your agent logic here
        return Output{Summary: input.Prompt}, nil
    })

    if err := agent.Start(); err != nil {
        log.Fatal(err)
    }
    select {}
}

SDKs: Go (stable, this repo) | **Python** (`pip install cap-sdk-python`) | **Node** (`npm install cap-sdk-node`)

Stable CAP Go, Python, and Node runtimes implement the same authenticated

protobuf worker-trust contract. A legacy capability handshake or heartbeat is

telemetry, not identity proof, unless it is bound into an accepted session.

Deployments remain at the explicit compatibility default

`CORDUM_SDK_HANDSHAKE=off` + `CORDUM_HEARTBEAT_MODE=authority` until worker

proof keys and control-plane signing authorities are provisioned. Follow the

authenticated worker trust guide before enabling

`warn` or `enforce`.

Integration Packs

Extend Cordum with 30+ integration packs for Slack, GitHub, AWS, Jira, Terraform, Datadog, PagerDuty, and more. Each pack is a CAP-native worker with policy-gated workflows.

Browse all integrations →

Community

• Discord: Join the conversation
• GitHub Discussions: Ask questions
• Twitter/X: @Cordum_io
• Email: See SECURITY.md for contact details

Enterprise

Cordum Enterprise features (shipped in core, unlocked by license entitlement):

• SSO/SAML/OIDC integration + SCIM provisioning
• Advanced RBAC with role hierarchy
• SIEM export (webhook, syslog, Datadog, CloudWatch)
• Legal hold + velocity rules + agent identity
• Priority support

See `docs/enterprise.md` for the full entitlement matrix.

The formerly separate `cordum-enterprise` repo was retired 2026-04-23.

Governance

Cordum follows a transparent governance model with a protocol stability pledge, maintainer structure, and clear decision-making process. See GOVERNANCE.md for details including:

• Protocol Stability: CAP v2 wire format frozen until February 2027
• Security: SECURITY.md for vulnerability reporting
• Versioning: Semantic versioning with deprecation policy

Roadmap

See ROADMAP.md for the full feature roadmap, completed milestones, and planned work.

Changelog

See CHANGELOG.md for a detailed log of all changes by version.

Compared To

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines. Check out our good first issues to get started.

License

Licensed under Business Source License 1.1 (BUSL-1.1).

• Self-host and use internally: Permitted
• Modify and contribute back: Permitted
• Offer as a competing hosted service: Not permitted
• Change Date: January 1, 2029 — automatically converts to Apache License 2.0

See LICENSE for full terms.

Star History

Ready to govern your AI agents?

· ·

If Cordum helps you deploy agents safely,