Mecatl is an open source, cloud-native agent harness. It provides the loop, tools, permissions, hooks, delegation, and service boundaries for running AI agents as production workloads on infrastructure you operate.
Mecatl keeps the agent loop independent of the client and execution environment, so the same runtime can start locally, run remotely with durable external state and a recorded event history, then scale across Kubernetes replicas without replacing the loop. It combines composable tools and skills with permissions, attribution, and audit records while keeping model providers and deployment infrastructure replaceable.
Run one of the supplied services or connect Mecatl to an existing application with the model provider, state store, filesystem, and UI that fit your workflow. These concerns connect through explicit interfaces, so changing one does not require replacing the agent loop.
Read the Mecatl documentation to get started.
- A streaming agent loop with tool dispatch, permissions, compaction, hooks, subagents, and teams.
- Provider-agnostic model integration, with reference adapters and opt-in provider modules.
- Durable sessions and append-only event logs through pluggable stores, so a deployment can recover persisted work after process replacement.
- Client integration via gRPC and HTTP/SSE, the TypeScript SDK, and mecatui, a terminal client that can host a local server or connect to a remote one.
- A Kubernetes-native reference runtime that combines Redis-backed state, Kubernetes session leases, drain handling, and disposable replicas.
| Goal | Start with |
|---|---|
| Run an agent service | mecated and the deployment guide |
| Run agents on Kubernetes | mecak8s and the Kubernetes deployment guide |
| Use an agent locally | Install, then use mecatui — or run the offline demo from a checkout |
| Connect an application | The TypeScript SDK guides or the gRPC and HTTP/SSE integration guide |
| Build unattended automation | mecatequi for one prompt, a patch, and a machine-readable result |
| Embed the runtime | engine and the embedding guide |
Homebrew installs the two executables most people run — mecatui, the terminal
client, and mecated, the server:
brew install stacklok/tap/mecatlEvery release also attaches macOS and Linux archives (amd64 and arm64) with
checksums, cosign signature bundles, SBOMs, and build provenance. See
Install Mecatl for archive verification, the
container images, and the from-source path. mecademo, mecatequi, and
mecak8s are not in the formula — build them from a checkout with task build.
An agent runtime needs more than a model call to operate as a workload. A replaceable process needs durable state outside the process, a record of work that survives a restart, and a way to coordinate access when replicas share a session. Mecatl supplies the seams and reference implementations for those concerns without making them part of the agent loop.
The supplied mecak8s runtime demonstrates this deployment model. It uses
Redis for session state and event logs, Kubernetes leases to ensure one writer
per session, and a drain path for replacing pods. You can also embed the engine
and provide the backing services and execution environment yourself. See
Cloud-native kit properties
for the runtime guarantees and boundaries.
Mecatl keeps the agent loop independent of the provider and infrastructure behind it. Reference adapters support offline development, while integrations use the interfaces that match the parts of the system they connect. This lets you use the same harness with the model providers, state services, tools, and clients your system requires.
Mecatl provides the agent runtime and its contracts. Your application decides which capabilities a session receives, where code runs, and how it connects to its identity, policy, and data services.
Agents can act with a user's or service's authority, so Mecatl keeps the agent loop separate from the execution environment. It treats permissions and the event record as first-class runtime concerns. It includes deny-dominant permissions, approval flows, secret-scrubbed command environments, durable attribution, and an audit trail. Delegated runs receive derived capabilities that can only narrow at each in-process hop.
Caller identity and audit records are useful building blocks, not a complete tenant-isolation boundary. Cross-process cryptographic proof and authority attenuation remain active design work. See the agent identity tracker and the working identity model.
The offline demo runs a scripted session with tool calls, a permission approval,
delegation, and usage accounting. It does not require an API key. It runs from a
checkout of this repository; the Homebrew formula does not ship mecademo.
go run ./cmd/mecademoTo build every supplied runtime and client:
task buildFor an embedded deployment, see the engine compatibility contract and the embedding guide.
Security:
mecatedis unauthenticated by default and intended for loopback, single-user use. Configure authentication and transport protection before binding it off-loopback. The deployment guide covers bearer auth, TLS/mTLS, OIDC, rate limits, and deployment posture.
- Mecatl documentation for user guides and deployment information.
- Client integration guide for gRPC and HTTP/SSE clients.
- TypeScript SDK guides for Node.js, Bun, and browser applications.
- Repository documentation index
- Architecture guide
- User documentation
- Production-readiness tracker
- Engine compatibility contract
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.