mecatl

module

v0.0.26 Latest Latest Go to latest Published: Sep 8, 2026 License: Apache-2.0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/stacklok/mecatl

Links

Open Source Insights

README ¶

Mecatl

Mecatito, the Mecatl mascot

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 starts locally and scales to fleets of agents on infrastructure you control. It combines composable tools and skills with durable state, 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.

What it provides

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.
gRPC and HTTP/SSE interfaces for client applications, plus 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.

Get started

Goal	Start with
Run an agent service	`mecated` and the operator guide
Run agents on Kubernetes	`mecak8s` and the Kubernetes deployment guide
Use an agent locally	Run the offline demo, then use `mecatui`
Connect an application	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

Run agents as production workloads

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.

Open and modular by design

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.

Control and execution

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.

Try it locally

The offline demo runs a scripted session with tool calls, a permission approval, delegation, and usage accounting. It does not require an API key.

go run ./cmd/mecademo

To build every supplied runtime and client:

task build

For an embedded deployment, see the engine compatibility contract and the embedding guide.

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.

User documentation

Mecatl documentation for user guides and deployment information.
Client integration guide for gRPC and HTTP/SSE clients.

Architecture and engineering documentation

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.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
mecademo command Package main (mecademo) is the mecatl end-to-end demo driver.	Package main (mecademo) is the mecatl end-to-end demo driver.
mecak8s command Command mecak8s is the storage-free, Kubernetes-native mecatl agent binary (ADR 0048): a THIN peer of cmd/mecated that composes the SAME app.Build assembly with k8s-native defaults — Redis session store + durable event log, coordination.k8s.io Lease session leasing, a dynamic /readyz (drain-gated + Redis-pinged), and a bounded GracefulStop that cancels in-flight runs on SIGTERM so a rolling update completes within terminationGracePeriodSeconds.	Command mecak8s is the storage-free, Kubernetes-native mecatl agent binary (ADR 0048): a THIN peer of cmd/mecated that composes the SAME app.Build assembly with k8s-native defaults — Redis session store + durable event log, coordination.k8s.io Lease session leasing, a dynamic /readyz (drain-gated + Redis-pinged), and a bounded GracefulStop that cancels in-flight runs on SIGTERM so a rolling update completes within terminationGracePeriodSeconds.
mecated command Command mecated is the standalone mecatl server binary and a composition root: it parses the CLI/env configuration, builds the telemetry sink, delegates the engine + service assembly to internal/app (the SHARED composition layer also used by the embedded server in cmd/mecatui), and serves the resulting HarnessService over gRPC and HTTP/SSE concurrently, with graceful shutdown on SIGINT/SIGTERM.	Command mecated is the standalone mecatl server binary and a composition root: it parses the CLI/env configuration, builds the telemetry sink, delegates the engine + service assembly to internal/app (the SHARED composition layer also used by the embedded server in cmd/mecatui), and serves the resulting HarnessService over gRPC and HTTP/SSE concurrently, with graceful shutdown on SIGINT/SIGTERM.
mecatequi command Command mecatequi is a single-shot, headless mecatl runner for CI / batch use: it runs ONE prompt against an in-process engine assembled by internal/app, drives the run to a terminal state, and emits three artifacts — a working-tree git diff, a machine-readable run-summary JSON, and an optional durable JSONL event log — then maps the terminal stop reason to a process exit code.	Command mecatequi is a single-shot, headless mecatl runner for CI / batch use: it runs ONE prompt against an in-process engine assembled by internal/app, drives the run to a terminal state, and emits three artifacts — a working-tree git diff, a machine-readable run-summary JSON, and an optional durable JSONL event log — then maps the terminal stop reason to a process exit code.
mecatui command login.go implements the separate ToolHive LLM and remote OIDC login routes.	login.go implements the separate ToolHive LLM and remote OIDC login routes.
mecatui/client Package client is the gRPC-facing layer of mecatui: it dials mecated, creates sessions, opens the bidi Converse stream, and translates proto Events into the plain Go tea.Msg structs the ui consumes.	Package client is the gRPC-facing layer of mecatui: it dials mecated, creates sessions, opens the bidi Converse stream, and translates proto Events into the plain Go tea.Msg structs the ui consumes.
mecatui/embed Package embed lets mecatui host its OWN mecated server in-process when no external one is running, so a single `mecatui` binary "just works" with no separately-spawned daemon and no TCP port.	Package embed lets mecatui host its OWN mecated server in-process when no external one is running, so a single `mecatui` binary "just works" with no separately-spawned daemon and no TCP port.
mecatui/keymap Package keymap validates rebindable-key overrides for mecatui.	Package keymap validates rebindable-key overrides for mecatui.
mecatui/schedparse Package schedparse is a small client-side natural-language → trigger compiler for the mecatui /schedule overlay's Create form.	Package schedparse is a small client-side natural-language → trigger compiler for the mecatui /schedule overlay's Create form.
mecatui/statusline Package statusline defines the display-only, dependency-leaf protocol shared by mecatui composition and UI status-line renderers.	Package statusline defines the display-only, dependency-leaf protocol shared by mecatui composition and UI status-line renderers.
mecatui/theme Package theme is the pure styling layer for mecatui.	Package theme is the pure styling layer for mecatui.
mecatui/ui Package ui is the Bubble Tea (Elm) layer of mecatui: the root Model state machine, its Update reducer, the View assembly, and the conversation/block renderers.	Package ui is the Bubble Tea (Elm) layer of mecatui: the root Model state machine, its Update reducer, the View assembly, and the conversation/block renderers.
mecatui/ui/platform Package platform reports host-platform facts the TUI adapts its presentation to.	Package platform reports host-platform facts the TUI adapts its presentation to.
mecatui/ui/prompttextarea Package prompttextarea owns the upstream textarea behind Mecatl's prompt-editor policy.	Package prompttextarea owns the upstream textarea behind Mecatl's prompt-editor policy.
mecatui/ui/welcome Package welcome renders the first-run splash for the mecatui zero-state: a faithful mascot (half-block on any truecolor terminal, a zero-dependency kitty Unicode-placeholder high-res path on capable terminals), a gradient "mecatl" wordmark, and an info block.	Package welcome renders the first-run splash for the mecatui zero-state: a faithful mascot (half-block on any truecolor terminal, a zero-dependency kitty Unicode-placeholder high-res path on capable terminals), a gradient "mecatl" wordmark, and an info block.
contracts
gen/go/mecatl/driver/v1
gen/go/mecatl/v1
sessionaffinity Package sessionaffinity defines the root transport contract for mecatl's optional session routing hint.	Package sessionaffinity defines the root transport contract for mecatl's optional session routing hint.
docs
lint Package lint holds the design-doc anti-drift checks.	Package lint holds the design-doc anti-drift checks.
engine module
examples
first-agent command Package main demonstrates the minimal offline mecatl agent.	Package main demonstrates the minimal offline mecatl agent.
first-agent-approval command Package main demonstrates resolving a mecatl permission request.	Package main demonstrates resolving a mecatl permission request.
first-agent-openrouter command Package main demonstrates using the mecatl engine with OpenRouter.	Package main demonstrates using the mecatl engine with OpenRouter.
first-agent-tool command Package main demonstrates registering a custom mecatl tool.	Package main demonstrates registering a custom mecatl tool.
internal
adapter/acp Package acp is the Agent Client Protocol (ACP) adapter: it lets an ACP editor (Zed, and others that speak ACP) drive the mecatl harness as a subprocess over stdio.	Package acp is the Agent Client Protocol (ACP) adapter: it lets an ACP editor (Zed, and others that speak ACP) drive the mecatl harness as a subprocess over stdio.
adapter/agentimport Package agentimport converts local Codex and Claude Code artifacts into provider-neutral Mecatl data.	Package agentimport converts local Codex and Claude Code artifacts into provider-neutral Mecatl data.
adapter/agents Package agents is the in-repo alias shim for the agent-definition discovery adapter that graduated into the importable engine module (engine/adapter/agentfs, issue #328).	Package agents is the in-repo alias shim for the agent-definition discovery adapter that graduated into the importable engine module (engine/adapter/agentfs, issue #328).
adapter/attemptstore Package attemptstore persists bounded learning attempts in a crash-safe, owner-partitioned document.	Package attemptstore persists bounded learning attempts in a crash-safe, owner-partitioned document.
adapter/authfile Package authfile is the adapter-layer leaf for mecatl's credentials file: a settings.yaml-sibling YAML file (conventionally $XDG_CONFIG_HOME/mecatl/auth.yaml) holding per-provider secrets: an api_key for the existing keyed providers or a manually supplied OAuth access-token snapshot for openai-codex.	Package authfile is the adapter-layer leaf for mecatl's credentials file: a settings.yaml-sibling YAML file (conventionally $XDG_CONFIG_HOME/mecatl/auth.yaml) holding per-provider secrets: an api_key for the existing keyed providers or a manually supplied OAuth access-token snapshot for openai-codex.
adapter/automaticstore Package automaticstore persists automatic-admission accounting in one flock-serialized, crash-safe document shared by cooperating processes.	Package automaticstore persists automatic-admission accounting in one flock-serialized, crash-safe document shared by cooperating processes.
adapter/cedarauthority Package cedarauthority provides the optional Cedar-backed authority evaluator.	Package cedarauthority provides the optional Cedar-backed authority evaluator.
adapter/clientauth Package clientauth provides durable, target-bound public-client OIDC credentials.	Package clientauth provides durable, target-bound public-client OIDC credentials.
adapter/credentialstore Package credentialstore defines a host-internal, credential-format-agnostic port for opaque binary records and provides namespace-bound backend handles.	Package credentialstore defines a host-internal, credential-format-agnostic port for opaque binary records and provides namespace-bound backend handles.
adapter/credentialstore/conformance Package conformance provides the reusable contract tests for mutable credential stores.	Package conformance provides the reusable contract tests for mutable credential stores.
adapter/daemonconfig Package daemonconfig is a strict, versioned, operator-selected daemon configuration file loaded ONLY when `mecated serve --config PATH` is explicitly supplied.	Package daemonconfig is a strict, versioned, operator-selected daemon configuration file loaded ONLY when `mecated serve --config PATH` is explicitly supplied.