# OrgKernel: Cryptographic Trust Layer for AI Agents

> OrgKernel is an Apache-licensed Python library that gives enterprise AI agents verifiable cryptographic identity, scoped execution tokens, and tamper-evident SHA-256 hash-chained audit trails. It solves the governance gap left by orchestration frameworks like LangGraph, CrewAI, and AutoGen, which provide no answer to who an agent is, what it is permitted to do, or what it actually did.

**MetapriseAI/OrgKernel** — Open-source trust layer for AI agents — cryptographic agent identity (Ed25519), instance-scoped execution tokens, SHA-256 hash-chained audit logging, and enterprise SSO/SCIM federation. The security foundation powering every agent in the Metaprise AURA platform.

- Repository: https://github.com/MetapriseAI/OrgKernel
- Stars: 2,694 · Forks: 249
- Language: Python
- License: Apache-2.0
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/metapriseai-orgkernel

## The Governance Gap in Agent Orchestration

Frameworks like LangGraph, CrewAI, and AutoGen give engineers the tools to build and coordinate agents. They do not answer the questions organizations actually need answered before deploying agents with real authority: which agent made this request, whether it was authorized to make it, and whether the record of what it did can be trusted. OrgKernel is built to answer all three. It positions itself in the execution path rather than alongside it, so the identity check and scope check run before every tool call and cannot be bypassed by application code.

The README frames this with a concrete example: an agent attempting to authorize a $10,000 purchase. Without OrgKernel, the denial depends on application-layer logic that could be missing or could be edited. With OrgKernel, the denial happens at the token scope check, and the full context of the request, including which agent, which mission, what was requested, and why it was denied, is already in the audit chain before a human asks what happened.

## The DualToken Identity Model

OrgKernel builds on two distinct credentials that must both validate before a tool call proceeds. The first is an AgentIdentity: an Ed25519 keypair where the public certificate is signed by the organization's own Certificate Authority. The identity record persists in the database; the private key is returned exactly once at issuance and never stored server-side. The second is an ExecutionToken: a per-mission, time-bounded token that carries a tool allowlist and immutable parameter bounds, signed with Ed25519 to prevent grafting tokens from one context to another.

The architecture diagram in the README describes the certificate signing request flow:

```
Agent Platform
    |
    |-- CSR submitted --> AgentIdentityService.submit_csr()
    |                      |-- validates duplicate
    |                      v
    |-- CSR issued -----> AgentIdentityService.issue_from_csr()
    |                      |-- generates Ed25519 keypair (server-side)
    |                      |-- signs certificate with Org CA
    |                      |-- returns certificate + private_key_pem ONCE
    |                      |-- persists identity record (NO private key)
    |                      v
    |                  AgentCertificate + AgentIdentity
```

The result is a least-privilege model by construction. An execution token carries only the tools a single mission needs, and it expires. An agent that holds a valid identity credential but whose token has no allowlist for a given tool call is blocked regardless of identity.

## Installing OrgKernel and Picking a Database Backend

OrgKernel is a Python package requiring Python 3.10 or newer. The pyproject.toml file defines the package as `orgkernel` with core dependencies on Pydantic 2.0+, SQLAlchemy 2.0+, the cryptography library 41.0+, and FastAPI 0.109+. The README was truncated before install instructions appeared, so the full setup steps are in the repository documentation; the pyproject.toml is the definitive reference.

The pyproject.toml lists optional database extras. The PostgreSQL extra, for example, pulls in the async driver and migration tooling:

```toml
postgres = [
    "asyncpg>=0.29",
    "alembic>=1.13",
]
```

The MySQL extra follows the same pattern:

```toml
mysql = [
    "aiomysql>=0.2",
    "alembic>=1.13",
]
```

SQLite needs only the async adapter:

```toml
sqlite = [
    "aiosqlite>=0.20",
]
```

All three can be installed together using the `all-db` extra. The three core modules cover identity (AgentIdentity, AgentCertificate, certificate lifecycle), execution (ExecutionToken, tool allowlists, parameter bounds), and audit (AuditChain, hash verification). The 27 REST endpoints built on FastAPI provide a surface for integrating with LangGraph, CrewAI, or AutoGen pipelines. The README does not document which specific endpoints are exposed by the base install versus an optional extra, so reviewing the src/ directory after installation is the next step before wiring it into an existing framework.

## Authorization as a Four-Layer Hierarchy

OrgKernel models organizational authority as a graph rather than a flat permission flag. The README describes four layers: organization, department, role, and instance. Any one layer's denial blocks execution. This design reflects how authorization works in practice inside enterprises: a role may be permitted to operate in an area, but the department may have a tighter budget cap, and the specific instance may be running in a context where the organization's policy adds a further constraint.

This contrasts with the API-key-per-agent pattern that most current deployments use. API keys are permanent, unscoped, unauditable, and shareable. Revoking one means rotating a secret and redeploying. Revoking an OrgKernel agent identity follows the certificate lifecycle: suspend, revoke, or reactivate through the identity service, with each lifecycle event recorded in the audit chain.

The README notes that upcoming capabilities, tracked in the repository roadmap, include a mission lifecycle manager, a tool gateway, a policy engine, an authority graph, a data classifier, SSO/SAML, and SCIM federation. As of the last push on 2026-07-06, these are listed as coming soon. Engineers who need them should check the CHANGELOG.md before adopting OrgKernel for production use.

## The Hash-Chained Audit Trail and What Tamper-Evident Actually Means

The AuditChain records every agent action across three layers: IDENTITY events (certificate issuance, suspension, revocation), EXECUTION events (tool calls, scope checks, token validation), and COMPLIANCE events. Each entry is appended to a SHA-256 hash chain: the hash of the new entry includes the hash of the previous entry, so deleting, modifying, or reordering any record breaks the chain.

This is a meaningful distinction from application-level logging. A log written to a file or a database table can be edited or deleted; nothing in that log proves its own integrity. OrgKernel's audit chain exposes an integrity verification API that detects any tampering. The README states the chain supports full replay of any agent's history and independent third-party verification, which the project explicitly targets at the evidentiary requirements of financial, healthcare, and legal deployments.

The three-layer audit is persisted to PostgreSQL, MySQL, or SQLite through SQLAlchemy 2.0, so it integrates with existing database infrastructure without requiring a separate logging service. The tradeoff is that the audit chain lives in the same database as the application state. Teams with strict separation requirements between operational data and compliance records will need to configure separate database instances.

## Where OrgKernel Falls Short Today

The project carries a Development Status of Beta (4 in PyPI classifier terms). Several capabilities described in the README as part of the full governance picture are not yet available: the mission lifecycle manager, the tool gateway, the policy engine, the authority graph, the data classifier, SSO/SAML federation, and SCIM provisioning. The README marks all of these as upcoming. An engineer who needs a policy engine to express fine-grained rules about what agents can do in what circumstances cannot yet rely on OrgKernel to supply it.

The repository also had no GitHub releases as of 2026-07-06, meaning there is no versioned changelog tied to release tags. The CHANGELOG.md is the record to watch, but there is no published release cadence to plan upgrades around.

The private-key-returned-once design is correct cryptographically but places the entire key management burden on the calling application. If the application fails to persist the private key at issuance time, it cannot be recovered. The README does not document a key recovery path, which means the agent identity would need to be reissued.

## OrgKernel versus Coarse API Key Access Control

The natural alternative for teams that want some form of agent authorization is to issue one API key per agent and restrict it at the API gateway or service level. This is fast to set up and requires no new library. The README directly addresses this comparison: API keys are permanent (revocation requires a rotate-and-redeploy cycle), unscoped (the key grants everything the service allows, not just what this specific mission needs), unauditable (the key appears in logs as an opaque token with no trace of which human or process authorized it), and shareable (a key copied to a second process becomes a second actor with no distinguishable identity).

OrgKernel trades setup complexity for enforced scope, time-bounded authority, and an audit record that cannot be quietly edited. It does not replace a network-level API gateway; it works alongside one. An organization that already uses a gateway for rate limiting and transport security would add OrgKernel to gain the cryptographic identity layer and the hash-chained audit chain that the gateway does not provide.

## Conclusion

OrgKernel is the right choice for teams deploying AI agents in regulated environments where a tamper-evident record and verifiable identity are not optional: financial services, healthcare, insurance, or legal operations. The DualToken model and four-layer authorization graph answer questions that no existing orchestration framework addresses. Teams with simple internal automation that is never audited or subject to compliance review will find the overhead of certificate issuance and token scoping heavier than their situation warrants. Before adopting it, verify that the roadmap capabilities you need, such as the policy engine, the tool gateway, and SSO/SAML federation, are available; the pyproject.toml and CHANGELOG.md are the right places to check, since the repository had no GitHub releases as of the last push on 2026-07-06.

## FAQ

### What is OrgKernel and what problem does it solve?

OrgKernel is an Apache-licensed Python library that provides cryptographic agent identity, scoped execution tokens, and a SHA-256 hash-chained audit trail for AI agents. It solves the governance gap in frameworks like LangGraph and CrewAI, which provide no verifiable answer to who an agent is, what it is permitted to do, or whether the audit record of its actions is intact.

### Does OrgKernel require the Metaprise AURA platform to run?

No. The README states that OrgKernel is a standalone Apache 2.0 Python library that runs entirely on your own infrastructure with no API key, no external calls, and no vendor lock-in. It is the open-source trust foundation of the AURA platform but is usable independently.

### Which databases does OrgKernel support for persisting audit and identity records?

The pyproject.toml lists PostgreSQL (via asyncpg and Alembic), MySQL (via aiomysql and Alembic), and SQLite (via aiosqlite) as supported backends. Each is available as an optional extra when installing with pip.

## Sources

- [Issues](https://github.com/MetapriseAI/OrgKernel/issues)
- [License: Apache-2.0](https://github.com/MetapriseAI/OrgKernel/blob/main/LICENSE)
- [MetapriseAI/OrgKernel on GitHub](https://github.com/MetapriseAI/OrgKernel)
- [README](https://github.com/MetapriseAI/OrgKernel/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/metapriseai-orgkernel