Cordum.io

Cordum

Sepa lo que tus Agentes de IA están Haciendo. Antes de que lo Hagan.
El Plano de Control de Agentes de Código Disponible para Gobernanza, Seguridad y Confianza.
Incluye Cordum Edge — un Firewall de Cumplimiento para Claude Code y otras acciones locales de agentes de IA.

Discord · Discusiones · Documentación

Inicio Rápido

¿Primera Vez?

Opción A: Instalar desde el código fuente

Un comando levanta la pila completa — puerta de enlace API, programador, núcleo de seguridad, motor de flujo de trabajo, motor de contexto, panel de control, NATS y Redis protegido con TLS — con secretos generados automáticamente, certificados aprovisionados automáticamente y una prueba de humo posterior al despliegue que ejecuta un flujo de trabajo de aprobación real:

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

Requisitos previos: Docker Desktop v4+ (o Engine v20.10+ con Compose v2, ≥ 4 GB de RAM asignada), Go 1.26.3+ (para la generación de certificados en el primer arranque) y curl. En Windows usa MSYS2 / Git Bash / WSL.

Lo que obtienes al final:

• Panel de control en http://localhost:8082 — inicia sesión como admin / ChangeMe123! (la contraseña de desarrollo predeterminada, también guardada en .env como CORDUM_ADMIN_PASSWORD; cámbiala antes de exponer la pila).
• Puerta de enlace en http://localhost:8081 con un CORDUM_API_KEY generado en .env.
• Pares de claves TLS de CA, servidor y cliente en ./certs/.
• Un flujo de trabajo de puerta de aprobación funcional demostrado por la ejecución integrada de platform_smoke.sh.

Guía completa, notas de plataforma y solución de problemas: docs/quickstart.md.

Opción B: Ejecutar las imágenes publicadas

Requisitos previos: Docker Desktop v4+ o Docker Engine v20.10+ con el plugin Compose v2 (≥ 4 GB de RAM asignada), jq (recomendado, para analizar respuestas de API) y Go 1.26.3+ (para la generación local de certificados de una sola vez — docker compose monta ./certs pero no lo crea).

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

Panel de control: http://localhost:8082 Inicio de sesión: esta ruta deja la autenticación de usuario desactivada por defecto — inicia sesión en el panel de control con tu CORDUM_API_KEY. Para habilitar el inicio de sesión con contraseña admin en su lugar, establece CORDUM_USER_AUTH_ENABLED=true y una CORDUM_ADMIN_PASSWORD que cumpla con la política (≥ 12 caracteres, con una letra mayúscula, un dígito y un carácter especial) en .env, luego docker compose up -d. (El script de inicio rápido en la Opción A hace esto por ti.)

Fija una versión específica exportando CORDUM_VERSION=1.2.3 antes de docker compose pull. El valor predeterminado es :latest, que solo avanza en etiquetas de versión estables (los sufijos de prelanzamiento como -rc.1 nunca promueven :latest).

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.*'

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

Imágenes de contenedor (multi-arquitectura: linux/amd64 + linux/arm64):

Catálogo completo, política de etiquetas, receta de verificación con cosign y notas multi-arquitectura: docs/deployment/images.md.

Puertos

¿Conflictos de puertos? Si algún puerto ya está en uso, detén el servicio en conflicto o sobrescribe los puertos en tu archivo .env antes de iniciar la pila.

Después de la Configuración

# 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

Solución de Problemas

Para solución de problemas detallada, consulta docs/troubleshooting.md.

Ver una demostración de 3 veredictos

Una vez que la pila esté activa, instala el paquete demo-quickstart y ejecuta la demostración de gobernanza:

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

Un único flujo de trabajo de hello, operator! se ramifica en tres temas y ejercita cada clase de decisión del núcleo de seguridad en menos de 30 segundos:

  +--------------------+--------------------------+--------------------+---------
  | 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…
  +--------------------+--------------------------+--------------------+---------

Guía completa, explicación regla por regla y receta de extensión: demo/quickstart/README.md.

Inicio Rápido de Edge (Firewall de Cumplimiento para Claude Code)

Cordum Edge gobierna las llamadas de herramientas de Claude Code en la terminal del desarrollador — el hook deniega acciones arriesgadas antes de que se ejecuten, requiere aprobación para ediciones y exporta un paquete de evidencia redactado para cada sesión. Una vez que la pila de la plataforma esté activa (arriba), apunta Claude Code a 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

El envoltorio renderiza un settings.json temporal, genera cordum-agentd en un nonce de bucle local y inicia Claude Code con el hook de comando instalado. La lectura de .env está denegada; Editar/Escribir requiere aprobación; las lecturas seguras pasan sin cambios. El panel de control muestra la línea de tiempo de la sesión en vivo en /edge/sessions.

Para acciones destructivas aprobadas, Edge no confía solo en el almacén de aprobaciones: el ProvenanceGate también requiere un evento de auditoría de aprobación resuelto para el mismo inquilino, approval_ref y action_hash. Un evento de solicitud de aprobación por sí solo no satisface la procedencia, y los prompts sin procesar, transcripciones y cargas útiles de herramientas se mantienen fuera de la evidencia de auditoría.

Guía completa de 30 minutos: docs/quickstart-edge.md. Referencia: docs/edge/README.md.

El Problema: La Brecha de Riesgo de los Agentes

Las empresas se están apresurando a desplegar Agentes de IA Autónomos, pero se están topando con un muro de riesgo. Según Gartner, el 74% de las empresas ven a los agentes de IA como un nuevo vector de ataque, y más del 40% de los proyectos de IA agéntica serán cancelados debido a controles de riesgo inadecuados.

El panorama actual deja a los equipos con una elección:

1. Restringir agentes a tareas simples de solo lectura y bajo valor.
2. Aceptar el riesgo de agentes autónomos que toman acciones destructivas y no supervisadas.

Sin una capa de gobernanza dedicada, estás volando a ciegas:

• Sin visibilidad: No sabes lo que tus agentes están haciendo hasta después de que lo hacen.
• Sin rieles de seguridad: No hay forma de interceptar operaciones peligrosas antes de que se ejecuten.
• Sin humano en el circuito: Las acciones sensibles ocurren sin supervisión manual.
• Sin rastro de auditoría: Cuando algo sale mal, no puedes reconstruir la cadena de pensamiento.

La Solución: Plano de Control de Agentes de Cordum

Cordum es un Plano de Control de Agentes que proporciona una capa de gobernanza determinista para mentes de IA probabilísticas. Te permite definir, hacer cumplir y auditar el comportamiento de tus Agentes de IA Autónomos en cualquier marco o modelo.

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

Gobernanza a lo Largo del Ciclo de Vida

El marco Antes/Durante/A través de Cordum proporciona un control exhaustivo sobre las operaciones de tus agentes:

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

• ANTES (Gobernanza): Define políticas declarativas que evalúan solicitudes de trabajo antes de que un agente ejecute. Activa verificaciones del núcleo de seguridad, limita acciones arriesgadas o marca operaciones para aprobación humana.
• DURANTE (Seguridad): Visibilidad en tiempo real de ejecuciones de agentes activos. Monitorea el progreso, maneja aprobaciones a nivel de paso y aplica tiempos de espera o interruptores de circuito sobre la marcha.
• A TRAVÉS (Observabilidad): Gestiona toda tu flota desde un solo plano de control. Agrega rastros de auditoría, rastrea el enrutamiento basado en capacidades y observa la salud del grupo de agentes en tiempo real.

Cordum Edge: Firewall de Cumplimiento para agentes de IA

Cordum Edge extiende el plano de control a acciones locales de agentes de IA. Para Claude Code, cordumctl edge claude lanza la ruta P0 real — hook de comando, cordum-agentd local, APIs de Edge de la puerta de enlace, política/evaluación del núcleo de seguridad, aprobaciones, punteros de artefactos y evidencia del panel de control.

Cordum permanece en silencio hasta que la gobernanza importa. Los desarrolladores ven a Cordum exactamente cuando los protege a ellos, a su equipo y a la producción: antes de que se ejecuten herramientas arriesgadas, cuando una acción necesita aprobación y cuando se debe exportar evidencia. El envoltorio es la ruta de desarrollador/demostración; el cumplimiento empresarial requiere configuraciones de Claude administradas y controles de punto final.

La procedencia de aprobación es solo resuelta: los reintentos destructivos deben tener un registro de aprobación aprobado coincidente y un evento de auditoría de aprobación resuelto canónico para el mismo inquilino/ref/hash. Las filas de auditoría solo solicitadas son contexto del ciclo de vida, no prueba de que la acción fue aprobada.

Comienza aquí: Descripción general de Edge, Guía de Claude Code, demostración manual y API de Edge.

Desarrollo

La ruta de imágenes publicadas anteriormente extrae los binarios de Cordum de ghcr.io. Los contribuyentes que necesiten reconstruir desde el código fuente usan el archivo de anulación de desarrollo:

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-fija cada servicio de Cordum a una etiqueta cordum/<name>:dev local y fuerza el contexto build:, de modo que los cambios en el código fuente se reflejan en el siguiente --build. Las imágenes ascendentes (NATS, Redis) no se modifican. Consulta Makefile y docker-compose.dev.yml para obtener todos los detalles.

Otros comandos útiles para colaboradores:

Características Clave

Arquitectura

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

Documentación

Protocolo: CAP — El Estándar Abierto para la Gobernanza de Agentes

Cordum implementa CAP (Protocolo de Agente de Cordum), un protocolo abierto diseñado específicamente para la gobernanza distribuida de agentes de IA. CAP proporciona una interfaz unificada para definir capacidades de agentes, enviar trabajos y aplicar políticas de seguridad en grupos de agentes heterogéneos.

CAP vs. MCP: Por Qué Necesitas Ambos

Aunque ambos son esenciales, resuelven diferentes partes de la pila de agentes:

• MCP es para dentro del agente — define cómo un modelo llama a herramientas locales.
• CAP es para por encima del agente — define el plano de control de gobernanza para toda la flota de agentes.

Usa CAP para orquestación de alto nivel y control de seguridad, y MCP dentro de tus agentes para integración fina de herramientas.

Lee el análisis completo: MCP vs CAP: Por Qué Tus Agentes de IA Necesitan Ambos Protocolos

Servidor MCP

Cordum incluye un marco de servidor MCP con:

• Modo stdio independiente mediante cmd/cordum-mcp (para integración local con Claude Desktop/Code)
• Modo Gateway HTTP/SSE mediante /mcp/message y /mcp/sse (cuando mcp.enabled=true)

Consulta docs/mcp-server.md para la configuración, cabeceras de autenticación y ejemplos de configuración de clientes.

SDK

El SDK de Go facilita la creación de trabajadores compatibles con CAP:

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 (estable, este repositorio) | Python (pip install cap-sdk-python) | Node (npm install cap-sdk-node)

Los runtimes estables de CAP Go, Python y Node implementan el mismo contrato de confianza de trabajador autenticado basado en protobuf. Un handshake o heartbeat de capacidad heredado es telemetría, no prueba de identidad, a menos que esté vinculado a una sesión aceptada. Los despliegues permanecen en el valor predeterminado de compatibilidad explícito CORDUM_SDK_HANDSHAKE=off + CORDUM_HEARTBEAT_MODE=authority hasta que se aprovisionen claves de prueba de trabajador y autoridades de firma del plano de control. Sigue la guía de confianza de trabajador autenticado antes de habilitar warn o enforce.

Paquetes de Integración

Extiende Cordum con más de 30 paquetes de integración para Slack, GitHub, AWS, Jira, Terraform, Datadog, PagerDuty y más. Cada paquete es un trabajador nativo de CAP con flujos de trabajo controlados por políticas.

Explora todas las integraciones →

Comunidad

• Discord: Únete a la conversación
• Discusiones de GitHub: Haz preguntas
• Twitter/X: @Cordum_io
• Correo electrónico: Consulta SECURITY.md para detalles de contacto

Empresa

Características de Cordum Enterprise (incluidas en el núcleo, desbloqueadas por licencia):

• Integración SSO/SAML/OIDC + aprovisionamiento SCIM
• RBAC avanzado con jerarquía de roles
• Exportación SIEM (webhook, syslog, Datadog, CloudWatch)
• Retención legal + reglas de velocidad + identidad de agente
• Soporte prioritario

Consulta docs/enterprise.md para la matriz completa de derechos. El repositorio anteriormente separado cordum-enterprise se retiró el 2026-04-23.

Gobernanza

Cordum sigue un modelo de gobernanza transparente con un compromiso de estabilidad del protocolo, estructura de mantenedores y un proceso claro de toma de decisiones. Consulta GOVERNANCE.md para más detalles, incluyendo:

• Estabilidad del Protocolo: Formato de cable CAP v2 congelado hasta febrero de 2027
• Seguridad: SECURITY.md para reportar vulnerabilidades
• Versionado: Versionado semántico con política de obsolescencia

Hoja de Ruta

Consulta ROADMAP.md para la hoja de ruta completa de funciones, hitos completados y trabajo planificado.

Registro de Cambios

Consulta CHANGELOG.md para un registro detallado de todos los cambios por versión.

Comparación

Contribuciones

¡Damos la bienvenida a las contribuciones! Consulta CONTRIBUTING.md para las pautas. Revisa nuestros primeros problemas buenos para comenzar.

Licencia

Licenciado bajo Licencia de Código Fuente Comercial 1.1 (BUSL-1.1).

• Autoalojar y usar internamente: Permitido
• Modificar y contribuir de vuelta: Permitido
• Ofrecer como servicio alojado competidor: No permitido
• Fecha de Cambio: 1 de enero de 2029 — se convierte automáticamente a Licencia Apache 2.0

Consulta LICENSE para los términos completos.

Historial de Estrellas

¿Listo para gobernar tus agentes de IA?
Protocolo CAP · Integraciones · Discord

Si Cordum te ayuda a desplegar agentes de forma segura, dale una ⭐