Skip to content

zekra

zekra is an operating system for agents, built on NATS. Agents are apps: each one requests access in its manifest, a human grants it, and the runtime enforces exactly that grant. Each agent runs as its own process or Firecracker microVM, talks to the rest of the system only over NATS, and can do only what its NATS credentials and the routing rules allow.

It is for anyone who wants agents to act on their behalf without trusting them blindly: you can always see what is running, what each one can access, who approved it, and how to stop it.

What makes it different

  • NATS enforces security. Each agent gets its own short-lived user JWT. Subject permissions come from the server, not from SDK code, so a buggy or hostile agent cannot widen them.
  • Deploys are deterministic and signed. The deployer contains no LLM. It deploys only a git commit SHA, and only with a signature from an approver key that the agent cannot reach.
  • A human approves every deploy in the MVP. Agents that a creator wrote go to a review queue first.
  • Generated code runs in Firecracker. A microVM's only network path is the NATS relay.
  • LLM calls go through a gateway. It is the only component that holds provider keys. It enforces model permissions, budgets and rate limits, and it audits prompts and responses.
  • Workflows are rules, not code. Agents react to events, and declarative CEL rules route them. Hop limits, deadlines and budgets stop runaway flows.
  • Everything is audited. Control messages and component decisions go to an append-only AUDIT stream. A freeze switch and a stop command are available at all times.

How it fits together

flowchart LR
  subgraph nodes["NODES account: agents"]
    A["agent A<br/>native process or microVM"]
    B["agent B"]
  end
  subgraph control["CONTROL account: platform services"]
    R["router<br/>rules and guards"]
    G["LLM gateway"]
    I["intake<br/>git bundles"]
    H["HITL<br/>review queue"]
    D["deployer"]
    RN["runner"]
    AU[("AUDIT")]
  end
  O["human<br/>zekra CLI"]
  M["model provider"]

  A -->|"call, evt"| R
  R -->|"agt, mbox"| B
  A -->|"svc.llm"| G --> M
  A -->|"svc.git push"| I -->|"control.git.pushed"| H
  O -->|"signed deploy"| D -->|"control.runner"| RN -->|"start"| A
  R --> AU
  G --> AU
  D --> AU
  RN --> AU

The main path, in order:

  1. An agent is a folder in git: agent.yaml (what to run), sidecar.yaml (what it may call, emit and use), and its code.
  2. A human approves the commit. The CLI signs the commit SHA and a hash of the manifests.
  3. The deployer checks the signature and the policy, builds an artifact from git, records the agent, and asks the runner to start it with short-lived credentials.
  4. The agent calls other agents through the router, emits events that rules route to mailboxes, and sends model requests to the gateway.
  5. Every decision is written to AUDIT, keyed by the flow's correlation ID.

Agents written by a creator follow the same path, except that their commit first goes through intake and waits in the HITL queue for review and signature.

Who it is for

  • Platform and security teams who must control which agents run and what they reach.
  • Developers who write agents that run on NATS and need a small, explicit contract.
  • Operators who need to freeze, stop, or revoke an agent and prove what happened.

Status

The MVP plan in design/archive/MVP.md is implemented on a single host. The design and its deviations are recorded in design/DESIGN.md.

Out of scope for the MVP:

  • Multiple hosts, leaf nodes, and Nex as a backend
  • Automatic approval, and agents that spawn agents (generated agents get no control rights)
  • A web UI or control-plane dashboard
  • Memory promotion into skills, and RAG
  • Multi-tenancy beyond the account split
  • Streaming LLM responses, payloads above 1 MiB, and warm VM pools

Where next

  • Install

    Prerequisites, the pinned NATS tools, and a smoke test.

  • Quick start

    Run the full loop on one machine: two agents, a rule, a deploy, the audit trail.

  • Concepts

    Components, the security model, the protocol, governance, execution and the LLM gateway.

  • Guides

    Write an agent, deploy and approve it, write rules, call models, and run Firecracker.

  • Operations

    Keys, policy, freeze, revocation, budgets and upgrades.

  • Reference

    CLI, environment variables, schemas, SDK, subjects and error codes.