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
guardrails:
  model: gpt-5-mini
extraEnv:
  - name: OPENAI_API_KEY
    valueFrom:
      secretKeyRef:
        name: mecak8s-openai
        key: OPENAI_API_KEY

guardrails.model names the checker that the default auto permission mode requires. To run every tool without a checker, remove it and set permissionMode: yolo. For the other options, see Choose a guardrails checker.

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, and the chart refuses to render auto until you choose one. 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>
```
Configure the checker in mounted settings, with a guardrails: model or the guardrail model slot, and set guardrails.fromSettings: true. The chart then passes no guardrails flag, and mecak8s uses the settings checker. It still refuses to start if the settings don't bind an enforcing 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, and fails rendering with auto. Set at most one of guardrails.model, guardrails.fromSettings, and guardrails.disabled.

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

Earlier chart versions always ran auto with no guardrails flag. Before you upgrade such a release, configure a checker or set permissionMode: yolo, or the upgrade fails to render.

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.