mecatl

mecatl

mecatl is a cloud-native agent kit for Go. It gives you the parts around a model that turn it into an agent: a streaming loop, tools, permissions, hooks, delegation, durable state, and the service boundaries needed to run it seriously.

Use the importable engine to build your own agent runtime, or run the supplied cloud-native service on a workstation or Kubernetes. An embedding becomes as cloud native as the state and execution services you wire behind its ports. The UI is a client. The agent runtime is the server. They do not have to share a process.

What are you building?

Cloud native is how the kit is built

Putting a local agent in a container does not make it cloud native. The process has to be replaceable, state has to live somewhere else, and another replica has to be able to continue the work.

mecatl was designed around those constraints:

• One service can host many independent sessions and agent loops concurrently.
• Session snapshots, event logs, memory, schedules, skills, agent definitions, and other sources sit behind ports. In-process adapters are convenient defaults; a versioned gRPC driver protocol moves the durable stores and content sources into separate services. Learned approvals are rebuilt from the durable event log rather than stored by a separate permission service.
• Sessions survive process replacement, including a session parked on a human approval. An append-only event log retains prompts, approval decisions, and pre-compaction history.
• Optional session leases enforce one writer across replicas. The supplied mecak8s Helm chart combines Redis state, Kubernetes leases, drain handling, and disposable agent replicas—two by default—without putting mecatl state on a PVC.
• The execution environment is its own per-session capability boundary: a workspace, a command runner bound to the same namespace, and a durable environment reference. Custom deployments can reattach a non-local environment through the resolver seam. No production remote or microVM-backed environment implementation ships yet.

The loop itself does not know about Redis, Kubernetes, gRPC, OpenAI, a local filesystem, or a particular UI. It depends on small interfaces and emits one typed event model.

 clients                         agent service                    replaceable backends
 ┌───────────────┐       ┌──────────────────────────┐       ┌────────────────────────┐
 │ mecatui       │       │ many sessions / loops    │       │ model providers        │
 │ web client *  │──────▶│ tools · policy · hooks   │◀─────▶│ sessions · event log   │
 │ your client   │ gRPC  │ subagents · teams        │       │ memory · schedules     │
 └───────────────┘ HTTP  └──────────────────────────┘       │ execution environments │
                                                           └────────────────────────┘
 * in active development

Read Cloud-native kit properties for the shipped state and restart model, and the architecture guide for the boundaries and ports.

Serious deployments, explicit authority

Agents call tools with somebody's authority. Once a service runs work for more than one person, "the agent did it" is not a useful identity model.

mecatl already ships deny-dominant permissions, human approval over the wire, model-backed guardrails, bounded delegation, OIDC caller verification, durable owner and actor attribution, secret-scrubbed command environments, and an audit log. Delegated runs carry a derived capability set that can only narrow at each in-process hop, with local or Cedar-backed enforcement at the execution boundary. Caller identity still is not, by itself, a complete tenant-isolation boundary.

The next step is cryptographic proof across process and service boundaries: trace an action through the user, agent, and subagent that caused it, and let downstream services verify the narrowed authority instead of trusting the harness's log. We are working toward a mecatl-issued SPIFFE trust domain for that purpose. The signing path, attenuation model, and key custody are active design work, not a feature we claim to have finished. Follow the agent identity tracker and the working identity model.

A client for humans

The client/server split is deliberate. mecatui renders the same gRPC event stream that another client can consume. It can embed a local server for a single-binary experience or connect to a remote one. A web client is in active development on the same principle: the service remains the source of truth, and the browser is not where agent state or provider credentials live.

This gives a tinkerer a friendly local experience without turning the UI into a runtime dependency. It also lets a platform team put the service somewhere else and build the client its users need.

A kit for experimenting with agents

The operational pieces are only half the project. mecatl also includes the things we want when building a personal assistant:

• Project memory plus a cross-project user model, with versioned inspect, forget, and undo operations.
• Optional dream consolidation. Automatic schedules retire only byte-identical duplicates; manual /dream lets a human review and apply plans, including synthesized replacements.
• An operator-owned, agent-read-only soul for persistent persona and style.
• Subagents, parallel fan-out, and coordinating teams with bounded budgets and inspectable child sessions.
• Progressive skills and completed-trajectory reflection. Learning is off by default; review and auto modes stage evidence-backed proposals, and learned procedures pass through the versioned skill lifecycle before activation.

These features are conservative on purpose. The agent can propose what it learned, but durable memory and reusable instructions have provenance, review, and rollback paths. See Memory and learning and Skills and extensibility.

Try it without an API key

The offline demo runs a complete scripted session with tool calls, a permission approval, delegation, and usage accounting:

go run ./cmd/mecademo

To build every supplied runtime and client:

task build

To embed the engine:

go get github.com/stacklok/mecatl/engine@latest

The engine is a separate Go module with a guarded public API and a deliberately small dependency closure. Reference adapters let it run offline, then you can replace only the ports your application owns. See the engine compatibility contract.

Runtime shapes

See Pick your deployment shape for the trade-offs.

Security: mecated is unauthenticated by default and intended for loopback, single-user use. Configure authentication and transport protection before binding it off-loopback. The operator guide covers bearer auth, TLS/mTLS, OIDC, rate limits, and deployment posture.

Documentation

• Architecture guide
• Usage and operator guide
• Client integration guide
• Documentation index
• User documentation
• Production-readiness tracker
• Engine compatibility contract
• Contributing to mecatl

Contributing, security, and license

Contributions are welcome through pull requests. Start with CONTRIBUTING.md; coding agents should read AGENTS.md before changing the repository.

Report vulnerabilities privately through SECURITY.md.

Licensed under the Apache License 2.0. Community participation is governed by the Code of Conduct.