Skip to main content
Glama
README.md
<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 policy checks, approvals, and audit of the agent actions it mediates.<br/>
  <em>Includes <strong>Cordum Edge</strong> — hook-based policy evaluation for Claude Code tool calls through <code>cordumctl edge claude</code>, the developer/demo path.</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> · <a href="#safety-you-can-verify">Safety Demo</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](#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:

```bash
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 https://localhost:8081 (its certificate is signed by the
  development CA in `./certs/ca/ca.crt`) with a generated `CORDUM_API_KEY`
  in `.env`.
- TLS CA, server, and client keypairs under `./certs/`.
- An approval-gate workflow exercised, unless you pass `--skip-smoke`, by the built-in
  `platform_smoke.sh` run.

Full walkthrough, platform notes, and troubleshooting:
[docs/quickstart.md](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).

```bash
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`; the
[image workflow](.github/workflows/docker.yml) adds that tag only when the tag name
lacks `-rc`, `-beta`, and `-alpha`.

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

The `docker.yml` tag workflow signs the images it builds 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:

```bash
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](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/
</details>

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

```bash
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>

```bash
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/](cordum-helm/) for the full Helm chart reference. The
chart is also available on [Artifact Hub](https://artifacthub.io/packages/helm/cordum/cordum).
</details>

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

| Image | GHCR | Docker Hub |
|-------|------|------------|
| `api-gateway` | [`ghcr.io/cordum-io/cordum/api-gateway`](https://github.com/cordum-io/cordum/pkgs/container/cordum%2Fapi-gateway) | [`cordum/api-gateway`](https://hub.docker.com/r/cordum/api-gateway) |
| `scheduler` | `ghcr.io/cordum-io/cordum/scheduler` | [`cordum/scheduler`](https://hub.docker.com/r/cordum/scheduler) |
| `safety-kernel` | `ghcr.io/cordum-io/cordum/safety-kernel` | [`cordum/safety-kernel`](https://hub.docker.com/r/cordum/safety-kernel) |
| `workflow-engine` | `ghcr.io/cordum-io/cordum/workflow-engine` | [`cordum/workflow-engine`](https://hub.docker.com/r/cordum/workflow-engine) |
| `context-engine` | `ghcr.io/cordum-io/cordum/context-engine` | [`cordum/context-engine`](https://hub.docker.com/r/cordum/context-engine) |
| `mcp` | `ghcr.io/cordum-io/cordum/mcp` | `cordum/mcp` |
| `dashboard` | `ghcr.io/cordum-io/cordum/dashboard` | [`cordum/dashboard`](https://hub.docker.com/r/cordum/dashboard) |

![latest release](https://img.shields.io/github/v/release/cordum-io/cordum?sort=semver&label=release)
![api-gateway image size](https://img.shields.io/docker/image-size/cordum/api-gateway/latest?label=api-gateway%20image)
![dashboard image size](https://img.shields.io/docker/image-size/cordum/dashboard/latest?label=dashboard%20image)

Full catalogue, tag policy, cosign verification recipe, and multi-arch
notes: [docs/deployment/images.md](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

```bash
# 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 | `docker compose exec redis redis-cli --tls --cacert /etc/cordum/tls/ca/ca.crt -a "$REDIS_PASSWORD" DEL cfg:system:default` then restart |

For detailed troubleshooting, see [docs/troubleshooting.md](docs/troubleshooting.md).

### See a 3-verdict demo

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

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

A single `hello, operator!` workflow fans out to three topics and
exercises three decision classes (ALLOW, DENY and REQUIRE_APPROVAL):

```
  +--------------------+--------------------------+--------------------+---------
  | 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](demo/quickstart/README.md).

### Edge Quickstart (Claude Code hook policy checks)

Cordum Edge evaluates Claude Code tool calls through the `cordumctl edge claude`
hook, the developer/demo path. Its metadata-only session export leaves raw prompts,
transcripts, and tool payloads out of the exported evidence. Once the platform stack
is up (above), point Claude Code at Cordum:

```bash
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.
With the demo Edge policy, reading .env is denied; Edit/Write requires approval; safe reads pass through
untouched. The dashboard shows the live session timeline at
[/edge/sessions](http://localhost:8082/edge/sessions).

On the Edge approval-retry path, the configured ProvenanceGate requires a
resolved approval audit event for the same tenant, `approval_ref`, and
`action_hash`; a requested-only event is not approval proof.
The metadata-only session export excludes raw prompts, transcripts, and tool payloads;
redaction protection is not yet qualified end to end.

Full 30-minute walkthrough: [docs/quickstart-edge.md](docs/quickstart-edge.md).
Reference: [docs/edge/README.md](docs/edge/README.md).

---

## Why Pre-Dispatch Action Governance?

Agents act with real authority: cloud credentials, database connections,
authenticated MCP sessions. Common controls each sit at a different boundary,
and none of them is the point where a specific action is dispatched:

- **Runtime sandboxes isolate the host, not the authority.** A container or
  microVM limits what a process can do to the machine it runs on. It does not
  limit what an agent can do with credentials or sessions it legitimately holds.
- **Observability records an action after it runs.** Logs and traces explain an
  incident; they do not hold the call that caused it.
- **Model and prompt guardrails sit at the LLM boundary.** They check what goes
  into and comes out of a model. Executing the resulting tool call or job
  happens in the code that dispatches it.

Cordum puts a policy decision at that dispatch boundary:

- **Normalized, hashed actions.** Approval-gated CAP jobs, action descriptors,
  MCP tool calls (tenant, server, tool, target path) and Cordum Edge evaluate
  requests are each reduced to a canonical form and hashed with SHA-256.
- **Explicit verdicts.** Policy evaluation yields `ALLOW`, `DENY`,
  `REQUIRE_APPROVAL`, `THROTTLE` or `ALLOW_WITH_CONSTRAINTS`. The gateway,
  scheduler and Edge evaluate routes convert an unknown verdict to `DENY` at their decision-conversion points.
- **Hash-bound approvals.** For Cordum approval-gated actions, lookup uses tenant and
  `approval_ref`; an approval whose SHA-256 `action_hash` differs is rejected as
  `approval_mismatch`. On those paths, self-approved,
  expired and already-consumed approvals also receive a rejection.
- **Declarative YAML policies.** Rules in [`config/safety.yaml`](config/safety.yaml)
  match on tenant, topic, capability, risk tags, actor and labels; the shipped
  file sets `default_decision: deny`, so the Safety Kernel denies unmatched requests when it loads that file.
- **Risk tags and agent risk tiers.** Rules can match `risk_tags` on any plan.
  Agent identities, which carry the risk tier that `agent_risk_tiers` rules
  match, require an Enterprise license.
- **Cordum Edge.** A local hook evaluates coding-agent tool calls (Claude Code
  today) against the gateway before they run. See
  [Edge Quickstart](#edge-quickstart-claude-code-hook-policy-checks).

The [claim register](docs/contract/claims.yaml) records these mechanisms as
supported: the mechanism exists; its protection is not yet qualified.

### Safety you can verify

Cordum lets routine agent work proceed while holding sensitive actions for
review. An authorized operator approves the specific action, not a blanket
permission to use the tool.

- **Try it:** The [three-verdict quickstart](demo/quickstart/README.md) shows a safe action proceeding, a simulated delete being blocked, and an admin action waiting for approval.
- **Inspect the evidence:** In the [governed CAP/MCP integration run](https://github.com/cordum-io/cordum/actions/runs/43539529144/job/132276555436), a denied job created neither an approval nor a workflow. The requester could not approve its own call. A separate operator's approval resulted in exactly one workflow. See the [test and reproduction steps](demo/cap-mcp-governed/README.md#governed-end-to-end-test).

**Coverage and limits:** Cordum enforces policy only on actions routed through
an integrated enforcement path. Deployment teams still need to restrict direct
tool access and configure policies for their environment. The CI run uses a
scripted worker and an internal workflow creation, not a live model or an
irreversible external action. It tests tool-level approval, not the separate
MCP policy-gate resume path.

## The Solution: Cordum Agent Control Plane

Cordum is an **Agent Control Plane** for policy checks, approvals, and audit of actions submitted through its integrated submission, dispatch, and hook paths, whatever framework or model the agent uses.

```mermaid
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
```

![Cordum dashboard showing a risky agent action intercepted for approval](https://github.com/user-attachments/assets/6d8d4781-dff4-4d62-8e26-7ff0366b2a5d)

### Governance Across the Lifecycle

Cordum's **Before/During/Across** framework gives operators control and visibility across connected agent workflows:

```mermaid
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)**: Monitor Cordum jobs and workflow runs, handle step-level approvals, and apply timeouts or circuit breakers.
- **ACROSS (Observability)**: Observe connected workers from a single control plane. Aggregate audit trails, track capability-based routing, and observe agent pool health.


### Cordum Edge: Claude Code hook policy checks

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.

Through `cordumctl edge claude`, the hook evaluates Claude Code tool calls.
With the demo Edge policy, reading .env is denied and Edit/Write needs approval;
session evidence can be exported. The wrapper is the
developer/demo path; enterprise enforcement requires managed Claude settings and
endpoint controls.

On the Edge approval-retry path, the configured ProvenanceGate requires a matching
approved approval record and a 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](docs/edge.md), [Claude Code guide](docs/edge-claude-code.md),
[manual demo](docs/demo-edge-claude.md), and [Edge API](docs/edge/api.md).

## Development

The published-images path above pulls Cordum binaries from `ghcr.io`.
Contributors who need to rebuild from source use the development override
file:

```bash
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/<name>: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:

| Command | Purpose |
|---|---|
| `make build` | Build every service binary into `bin/` (wraps `make proto` first). |
| `make build SERVICE=cordumctl` | Build a single service. |
| `make test` | Run the full Go test suite. |
| `make smoke` | Quick post-deploy smoke against a running stack. |

## Key Features

![Cordum workflow visualization](https://github.com/user-attachments/assets/ee44853d-1e89-463b-bf3c-0ba0481eee68)

| Governance Feature | Why It Matters for Enterprise |
|--------------------|--------------------------------|
| **Safety Gating** | Checks actions routed through Cordum's configured policy entry points before dispatch and stops those the policy denies. |
| **Output Quarantine** | Quarantines results the configured output policy flags, such as PII or secrets. |
| **Human-in-the-Loop** | Requests human oversight in policy-selected Cordum approval flows. |
| **Pool Segmentation** | Routes jobs according to pool placement configuration; this establishes neither endpoint trust nor data confinement. |
| **Deterministic Audit** | Records a decision's verdict, rule id, policy version, and reason in a verifiable audit chain, not model reasoning. |
| **Governance Policies** | Declarative YAML-based rules that map enterprise risk to agent behavior. |
| **Policy Simulator** | Test your governance rules against historical data before rolling them out to production. |
| **Cordum Edge** | Claude Code tool-call evaluation through `cordumctl edge claude` (developer/demo path): hook → local agentd → Gateway evaluate → configured resolved approval provenance → metadata-only session export. See [docs/edge/README.md](docs/edge/README.md). |

## 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

| Doc | Description |
|-----|-------------|
| [System Overview](docs/system_overview.md) | Architecture and data flow |
| [Core Reference](docs/CORE.md) | Deep technical details |
| [Docker Guide](docs/DOCKER.md) | Running with Compose |
| [Agent Protocol](docs/AGENT_PROTOCOL.md) | CAP bus + pointer semantics |
| [Authenticated Worker Trust](docs/sdk/handshake.md) | Worker enrollment, challenge/proof sessions, rollout, and rotation |
| [MCP Server](docs/mcp-server.md) | MCP stdio + HTTP/SSE integration |
| [Pack Format](docs/pack.md) | How to package agent capabilities |
| [Local E2E](docs/LOCAL_E2E.md) | Full local walkthrough |
| [Edge Quickstart](docs/quickstart-edge.md) | New-engineer 30-min path: clone → live stack → governed Claude session |
| [Edge Reference](docs/edge/README.md) | Cordum Edge product, API, CLI, demo, runbook |
| [Production Guide](docs/production.md) | TLS, HA, backups, incident runbooks |

## Protocol: CAP — The Open Standard for Agent Governance

Cordum implements [CAP (Cordum Agent Protocol)](https://github.com/cordum-io/cap), an open protocol for connected agents to declare capabilities and submit jobs that Cordum checks and routes to configured pools.

### CAP vs. MCP: Why You Need Both

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

| Protocol | Focus | Level | Responsibility |
|----------|-------|-------|----------------|
| **MCP** (Model Context Protocol) | **Tool Calling** | Local | How a model interacts with a tool. |
| **CAP** (Cordum Agent Protocol) | **Governance** | Network | How connected agents submit jobs for Cordum policy checks and routing. |

- **MCP** is for *within* the agent — it defines how a model calls local tools.
- **CAP** is for *above* the agent — it defines how connected agents submit jobs to Cordum's control plane for policy checks and routing.

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](https://dev.to/yaron_torgeman_104570d968/-mcp-vs-cap-why-your-ai-agents-need-both-protocols-3g4l)

## 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](docs/mcp-server.md) for setup, auth headers, and client configuration examples.

## SDK

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

```go
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**](https://pypi.org/project/cap-sdk-python/) (`pip install cap-sdk-python`) | [**Node**](https://www.npmjs.com/package/cap-sdk-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](docs/sdk/handshake.md) before enabling
`warn` or `enforce`.

## Integration Packs

Extend Cordum with [integration packs](https://github.com/cordum-io/cordum-packs) for Slack, GitHub, AWS, Jira, Terraform, Datadog, PagerDuty, and more. Each pack is an installable overlay of workflows, schemas and config/policy fragments ([docs/pack.md](docs/pack.md)); Core does not deploy pack workers, which run as separate deployments.

| Pack | Category | Description |
|------|----------|-------------|
| Slack | Communication | Approval notifications and agent alerts |
| GitHub | DevOps | Policy checks for repository actions the pack runs through Cordum |
| AWS | Cloud | Policy-gated cloud operations |
| Kubernetes | DevOps | Policy checks for remediation actions the pack runs through Cordum |
| Terraform | DevOps | Pre-apply policy checks for IaC actions the pack runs through Cordum |
| Datadog | Monitoring | Alert-triggered workflows for actions the pack runs through Cordum |
| LangChain | AI Framework | Policy checks for tool calls the pack runs through Cordum |
| MCP Bridge | AI Framework | Gateway policy checks for tool calls the pack runs through Cordum |

[Browse all integrations →](https://github.com/cordum-io/cordum-packs)

## Community

- **Discord:** [Join the conversation](https://discord.gg/nvHzPCcWWt)
- **GitHub Discussions:** [Ask questions](https://github.com/cordum-io/cordum/discussions)
- **Twitter/X:** [@Cordum_io](https://x.com/Cordum_io)
- **Email:** See [SECURITY.md](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`](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](GOVERNANCE.md) for details including:

- **Protocol Stability**: CAP v2 wire format frozen until February 2027
- **Security**: [SECURITY.md](SECURITY.md) for vulnerability reporting
- **Versioning**: Semantic versioning with deprecation policy

## Roadmap

See [ROADMAP.md](ROADMAP.md) for the full feature roadmap, completed milestones, and planned work.

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for a detailed log of all changes by version.

## Where Cordum Fits in the Agent Stack

Each layer below applies its checks at a different boundary, and they can be combined.
Cordum is the action control plane layer; it is meant to run alongside the
others, not to replace them. Descriptions of other projects paraphrase their
own documentation.

| Layer | Enforcement boundary | Examples |
|-------|----------------------|----------|
| Model and prompt guardrails | Inputs to and outputs from an LLM | [Guardrails AI](https://github.com/guardrails-ai/guardrails) runs Input/Output Guards in your application. [NeMo Guardrails](https://github.com/NVIDIA-NeMo/Guardrails) adds programmable guardrails to LLM-based conversational applications. [Llama Guard](https://github.com/meta-llama/PurpleLlama) is a family of input and output moderation models. |
| Traffic and MCP gateways | The network path between clients, models, tools and APIs | [IBM ContextForge](https://github.com/IBM/mcp-context-forge) is a registry and proxy that federates MCP, A2A and REST/gRPC APIs. [LiteLLM](https://github.com/BerriAI/litellm) is an AI gateway with a single interface to many LLM providers. |
| In-process hooks | Checks inside the agent's own process, such as framework callbacks or function wrappers | — |
| Action control plane (Cordum) | The point where an action is submitted or dispatched | Gateway submit-time policy checks, scheduler pre-dispatch safety checks, the [MCP server](#mcp-server) policy pipeline, and the [Cordum Edge](#cordum-edge-claude-code-hook-policy-checks) hook. |
| Runtime sandboxes | The process, OS or VM the action runs in | [Docker](https://docs.docker.com/get-started/docker-overview/) runs applications in a loosely isolated environment called a container. [gVisor](https://github.com/google/gvisor) is an application kernel that isolates applications from the host OS. [Firecracker](https://github.com/firecracker-microvm/firecracker) runs workloads in lightweight virtual machines called microVMs. [E2B](https://github.com/e2b-dev/E2B) runs AI-generated code in isolated cloud sandboxes. |

## Contributing

We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. Check out our [good first issues](https://github.com/cordum-io/cordum/labels/good%20first%20issue) to get started.

## License

Cordum ships from three repositories under two licenses. The table follows each
repository's LICENSE file and package metadata; the LICENSE files are the
authoritative terms.

| Component | Repository | License |
|-----------|------------|---------|
| Control plane services, dashboard, Cordum Edge, and Cordum's own SDKs (the Go `sdk/` module, `cordum-sdk` on PyPI, and the TypeScript `@cordum/sdk` package in `sdk/typescript/`) | [cordum-io/cordum](LICENSE) | BUSL-1.1 |
| Integration packs | [cordum-io/cordum-packs](https://github.com/cordum-io/cordum-packs) | BUSL-1.1, with the same Additional Use Grant. A pack directory with its own LICENSE is governed by that file; for example, `packs/incident-enricher` is Apache-2.0. |
| CAP protocol and its published SDKs (Go module `github.com/cordum-io/cap/v2`, `cap-sdk-python` and `cordum-guard` on PyPI, `cap-sdk-node` on npm) | [cordum-io/cap](https://github.com/cordum-io/cap) | Apache-2.0 |

The BUSL-1.1 parameters in [LICENSE](LICENSE):

> **Additional Use Grant:** You may make use of the Licensed Work for any purpose,
> including production use and self-hosted deployments, provided that you do not
> use the Licensed Work to provide a Competitive Offering.

- **Change Date:** 2029-01-01, or the fourth anniversary of a version's first
  public distribution under the license, whichever comes first.
- **Change License:** Apache License, Version 2.0 (Apache-2.0). On the earlier
  of those two dates, rights under Apache-2.0 replace the BUSL-1.1 grant for
  that version.
- **Other use:** "If your use of the Licensed Work does not comply with the
  requirements currently in effect as described in this License, you must
  purchase a commercial license from the Licensor, its affiliated entities, or
  authorized resellers, or you must refrain from using the Licensed Work."

See [LICENSE](LICENSE) for the full terms.

**Runtime entitlements are separate from the license.** The control plane
applies plan limits in code; the listed limits are not yet qualified end to end. Without a valid Cordum license it runs on the
Community defaults in [`core/licensing/tiers.go`](core/licensing/tiers.go):
3 workers, 3 concurrent jobs, 500 requests per second, 7-day audit retention,
single approval mode and no custom policy bundles. Entitlement resolution also falls back to these
defaults when a license cannot be loaded or fails verification
([`core/licensing/resolver.go`](core/licensing/resolver.go)). These are product
limits, not BUSL-1.1 terms; see [Enterprise](#enterprise).

### Versioning

Cordum core and CAP release independently, each with its own tags
([VERSIONING.md](VERSIONING.md)):

- **Cordum core (`v<major>.<minor>.<patch>` tags, currently 1.x).** A `v*` tag builds and signs the container
  images for api-gateway, scheduler, safety-kernel, workflow-engine,
  context-engine, mcp, dashboard and the demo quickstart worker, and publishes
  the Helm chart ([docker.yml](.github/workflows/docker.yml)). The separate
  [desktop binary workflow](.github/workflows/release.yml) builds
  `cordum-hook`, `cordum-agentd` and `cordum-claude`; publication requires its
  canonical `docker.yml` publish-binaries gate to find `SHA256SUMS.asc`; no signed release set is qualified. `cordumctl` is built from
  source (`make build`). The default `docker compose` stack runs api-gateway,
  scheduler, safety-kernel, workflow-engine, context-engine and dashboard with
  NATS and Redis. Cordum's own Python and TypeScript SDKs use separate
  `sdk-python-v*` and `sdk-ts-v*` tags.
- **CAP (`v2.x` tags).** The protocol and its SDKs release from
  [cordum-io/cap](https://github.com/cordum-io/cap). Cordum consumes a pinned
  CAP release through `go.mod` (`github.com/cordum-io/cap/v2 v2.17.0` at the
  time of writing), so a CAP SDK release does not require a core release, and a
  core release does not require a CAP release.

---

## Star History

<a href="https://star-history.com/#cordum-io/cordum&Date">
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=cordum-io/cordum&type=Date&theme=dark" />
   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=cordum-io/cordum&type=Date" />
   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=cordum-io/cordum&type=Date" />
 </picture>
</a>

---

<p align="center">
  <strong>Ready to govern your AI agents?</strong><br/>
  <a href="https://github.com/cordum-io/cap">CAP Protocol</a> · <a href="https://github.com/cordum-io/cordum-packs">Integrations</a> · <a href="https://discord.gg/nvHzPCcWWt">Discord</a>
</p>

<p align="center">
  If Cordum helps you deploy agents safely, <a href="https://github.com/cordum-io/cordum/stargazers">give it a ⭐</a>
</p>