Cloud-native k8s with mecak8s

mecak8s runs Mecatl with Kubernetes-native defaults. The chart uses two replicas by default for availability; you can use one replica to reduce resource usage and simplify session routing. Agent pods hold no durable state: session snapshots and the event log live in Redis, while Kubernetes Leases enforce a single writer for each session.

If a pod stops, a surviving pod can acquire its leases and resume interrupted sessions from Redis. The pod is disposable; the session is not.

Try mecak8s locally

The repository includes a disposable local Kind environment with Redis and two mecak8s replicas. Follow Try Mecatl on Kubernetes to create the cluster and connect with mecatui.

Before you deploy

You need:

A Kubernetes cluster, Helm, and kubectl. The cluster must be able to pull public images from ghcr.io.
A Redis endpoint reachable from the agent pods. Production deployments use verified TLS and can read ACL credentials from a Kubernetes Secret.
An OIDC issuer and audience for caller authentication.
A TLS certificate and key for the mecak8s Service, unless an operator-controlled gateway terminates TLS.
Credentials for an LLM provider.

The chart creates the ServiceAccount and namespace-scoped permissions for Kubernetes Leases. It does not create production Redis, TLS Secrets, provider Secrets, gateways, or general NetworkPolicies. A deployment that selects models.router.backend: jev must project TYPESAFE_API_KEY from a Kubernetes Secret and allow HTTPS egress to api.typesafe.ai; eligible delegated task text leaves the cluster for classification.

Quick start

The following example stores credentials in Kubernetes Secrets and installs the published chart with two replicas. Choose a version from GitHub releases, then substitute its number without the leading v for <VERSION>. Replace the example endpoints and filenames with values for your environment.

Create the namespace and Secrets. Set OPENAI_API_KEY in your current shell first. Redis and TLS values are read from files instead of being placed in Helm values:

: "${OPENAI_API_KEY:?set OPENAI_API_KEY first}"
kubectl create namespace mecatl
kubectl create secret generic mecak8s-openai --namespace mecatl \
  --from-literal=OPENAI_API_KEY="$OPENAI_API_KEY"
kubectl create secret generic mecak8s-redis --namespace mecatl \
  --from-file=password=./redis-password \
  --from-file=ca.pem=./redis-ca.pem
kubectl create secret tls mecak8s-tls --namespace mecatl \
  --cert=./server.crt --key=./server.key

Save the deployment values as mecak8s-values.yaml:

redis:
  endpoint: redis.example.internal:6379
  credentialsSecret: mecak8s-redis
  passwordKey: password
  caKey: ca.pem

tls:
  enabled: true
  secretName: mecak8s-tls

oidc:
  enabled: true
  issuer: https://idp.example.com
  audience: mecatl

defaultProvider: openai
model: gpt-5
extraEnv:
  - name: OPENAI_API_KEY
    valueFrom:
      secretKeyRef:
        name: mecak8s-openai
        key: OPENAI_API_KEY

Install the chart and wait for both replicas:

helm upgrade --install mecak8s \
  oci://ghcr.io/stacklok/mecatl/charts/mecak8s \
  --version <VERSION> \
  --namespace mecatl \
  --values mecak8s-values.yaml
kubectl rollout status deployment/mecak8s-mecak8s --namespace mecatl

The default Deployment name is <RELEASE>-mecak8s. Set fullnameOverride in the values file if you need a fixed name.

Deployment defaults

mecak8s starts with unattended, Kubernetes-oriented defaults:

Setting	Default
Replicas	Two
Permission mode	Headless `auto`, which needs an enforcing guardrails checker
Session state	Redis
Session ownership	Kubernetes Leases
Filesystem	No filesystem access
Network binds	Pod network on `0.0.0.0`
Metrics and OpenTelemetry	Opt-in

Project-provided instructions, skills, agents, and read-only child Shell access still require explicit project trust. mecak8s does not include ACP, local JSONL storage, or the mecated operator subcommands.

Choose a guardrails checker

auto allows every tool without asking, so mecak8s refuses to start it without an enforcing guardrails checker. The chart renders --permission-mode=<permissionMode>, which defaults to auto. Configure the checker in one of two ways:

Set guardrails.model, which renders --guardrails-model=<MODEL>:
```
guardrails:
  model: <MODEL>
```
Leave guardrails.model empty and configure the checker in mounted settings, with a guardrails: model or the guardrail model slot. The chart then passes no guardrails flag, and mecak8s uses the settings checker.

To run every tool with no checker, set permissionMode: yolo. guardrails.disabled: true renders the --guardrails=off kill-switch, which also disables a checker in mounted settings. Setting both guardrails.model and guardrails.disabled fails rendering.

The chart owns the permission mode. Rendering fails if extraArgs contains --posture, --permission-mode, or --yolo; move that choice to permissionMode. --posture=strict becomes permissionMode: default.

Earlier chart versions always ran auto with --guardrails=off. Before you upgrade such a release, configure a checker or set permissionMode: yolo, or the new pods refuse to start.

Because mecak8s is headless, the subagent ask reviewer is on by default. It uses the ask-reviewer model slot or the session model to decide subagent permission requests, and each decision spends tokens. Add --subagent-ask-reviewer=off to extraArgs to keep it off. See Subagents under auto.

Production Helm chart

The production chart is published at oci://ghcr.io/stacklok/mecatl/charts/mecak8s; its source is in deploy/helm/mecak8s/. It requires an external Redis endpoint and creates no Redis StatefulSet. Reference a Kubernetes Secret for Redis credentials. The chart's default image tag matches its application and chart versions, so it pulls the corresponding signed ghcr.io/stacklok/mecatl/mecak8s release. Set image.digest to pin an immutable image. It accepts a canonical lowercase SHA-256 digest: sha256: followed by 64 lowercase hexadecimal characters. Set only one of image.tag and image.digest, or clear the tag to use v<chart-version>.

A real-provider deployment (mockProvider: false) must choose one of these security postures:

Posture	Configuration
TLS in the pod	Enable `tls` and OIDC.
TLS at an operator-owned edge	Set `security.tlsTerminatedUpstream=true`, enable OIDC, and optionally keep in-pod TLS for re-encryption.
Unsafe bypass	Select the explicit bypass, which annotates the pod as unsafe.

The chart reserves its security-posture annotations; podAnnotations cannot override them.

Differences from mecated

Unlike mecated, mecak8s requires Redis, enables Kubernetes session leases by default, and exposes --redis-url. It does not include the config, skills promote, perf-mcp, or ACP operator commands.

mecak8s does not support the local ChatGPT Codex subscription entry at providers.openai-codex.oauth. API-key entries in auth.yaml remain supported. Use an API-key provider instead of mounting a local Codex OAuth credential.