Configuration Reference

Status: Available.

All msh local state lives under ~/.mezite/local/ (per-user install) or /var/lib/mezite/local/ and /etc/mezite/local/ (system install). Every file is created with 0600 permissions; directories are 0700.

Directory layout

~/.mezite/local/
├── ca.crt            # Dev CA certificate (ECDSA, generated at install)
├── ca.key            # Dev CA private key (0600)
├── ca-bundle.pem     # System roots + dev CA — used by SSL_CERT_FILE exports
├── policy.yaml       # YAML policy rules (hot-reloaded via fsnotify)
├── settings.yaml     # Daemon settings (hot-reloaded)
├── audit.jsonl       # Best-effort audit log, append-only by convention (0600)
├── observe.jsonl     # Observe-mode session log (0600)
├── daemon.sock       # Unix domain socket — CLI and desktop connect here
├── daemon.log        # Daemon log
├── install_mode      # "per_user" or "system" marker written by msh local install
└── ca_trusted        # Boolean marker: dev CA trusted in the OS keychain

There is no tokens.yaml, no per-AI-agent credential directory, and no per-AI-agent kubeconfig. msh local is a transparent MITM proxy — AI agents set HTTPS_PROXY and present no identity to the proxy. All authentication to the real upstream uses the operator's existing credentials.

policy.yaml

Defines protocol-keyed policy rules. Hot-reloaded by the daemon via fsnotify — changes take effect within a second without dropping in-flight requests. If the reload fails (invalid YAML), the daemon logs the error and enforces the last-good policy.

Top-level structure

<protocol>:
  inspect: [<hostname-glob>, <ip>, <cidr>, ...] # Hosts to MITM-decrypt
  default: escalate # Fallback action
  groups: # Named tier groups
    <group-name>:
      tiers: [<tier>, ...]
      # or:
      commands: [<command-string>, ...]
      # or:
      operations: [<operation-glob>, ...]
  namespaces: # (kubectl only) scope-sugar; first-match-wins
    - names: [<glob>, ...]
      rules:
        <action>:
          groups: [<group>, ...]
          commands: [<command>, ...]
          operations: [<operation-glob>, ...]
  projects: # (gcloud only) scope-sugar
    - names: [...]
      rules: ...
  regions: # (gcloud, aws) scope-sugar
    - names: [...]
      rules: ...
  apps: # (fly only) scope-sugar
    - names: [...]
      rules: ...
  rules: # Flat fallback — consulted after scope-sugar blocks
    <action>:
      groups: [<group>, ...]

Valid actions: allow, escalate, deny.

Valid tiers: observe, modify, sensitive, break-glass.

Selectors inside a group or an action branch: groups: (named groups), tiers: (glob over the tier name), commands: (glob over the classifier's canonical command label), and operations: (glob over the classifier's operation label — the real API verb, used to pin a specific call for protocols whose on-the-wire command is just an HTTP method, e.g. aws / gcloud). The shipped default policy usesoperations: to hard-deny a few catastrophic, irreversible operations (e.g. DeleteVpc, ScheduleKeyDeletion, cloudresourcemanager.projects.delete).

Scope-sugar blocks (namespaces:, projects:, regions:, zones:, orgs:, apps:) are first-match-wins on names: globs. The flat rules: block is consulted only when no scope-sugar entry matched.

protocol keys

KeyCovers
kubectlKubernetes API traffic (kubectl, kustomize)
gcloudGoogle Cloud API traffic (gcloud CLI)
flyFly.io API traffic (flyctl, fly)
awsAWS API traffic (aws CLI)
githubGitHub API traffic (gh CLI)
cloudflareCloudflare API traffic (wrangler, flarectl)
genericAny other host — tiered by HTTP method only

Example: kubectl with namespace scoping

kubectl:
  inspect:
    - "*.eks.amazonaws.com"
    - "*.gke.goog"
    - "*.azmk8s.io"

  default: escalate

  groups:
    read:
      tiers: [observe]
    mutate:
      tiers: [modify]
    delete:
      tiers: [sensitive]
    admin:
      tiers: [break-glass]
    exec:
      commands: [exec, attach, port-forward, cp, debug, proxy]

  namespaces:
    - names: [prod-*, production]
      rules:
        allow:
          groups: [read]
        escalate:
          groups: [mutate, delete, admin]
        deny:
          groups: [exec]

    - names: ["*"]
      rules:
        allow:
          groups: [read]
        escalate:
          groups: [mutate, delete, admin]
        deny:
          groups: [exec]

  rules:
    allow:
      groups: [read]
    escalate:
      groups: [mutate, delete, admin]
    deny:
      groups: [exec]

Example: generic block for arbitrary hosts

generic:
  inspect:
    - "api.internal.example.com"
  default: escalate
  groups:
    read:
      tiers: [observe]
    mutate:
      tiers: [modify]
    destructive:
      tiers: [sensitive]
    admin:
      tiers: [break-glass]
  rules:
    allow:
      groups: [read]
    escalate:
      groups: [mutate, destructive, admin]

settings.yaml

Daemon settings. Managed via msh local settings get|set. The file is hot-reloaded automatically on write.

SettingDescription
proxy_listenAddress and port the proxy listens on
log_levelLogging verbosity
default_modeDefault proxy mode at startup
telemetry_opt_inWhether anonymous telemetry is enabled

Environment variables (shell-init snippet)

The msh local shell-init snippet exports the following when the daemon is up:

VariableValuePurpose
HTTPS_PROXYhttp://127.0.0.1:9443Routes HTTPS traffic through the msh local proxy
HTTP_PROXYhttp://127.0.0.1:9443Routes HTTP traffic
SSL_CERT_FILE$HOME/.mezite/local/ca-bundle.pemSystem roots + dev CA for Go/C toolchains
REQUESTS_CA_BUNDLE$HOME/.mezite/local/ca-bundle.pemPython requests library
NODE_EXTRA_CA_CERTS$HOME/.mezite/local/ca-bundle.pemNode.js
AWS_CA_BUNDLE$HOME/.mezite/local/ca-bundle.pemAWS CLI
GIT_SSL_CAINFO$HOME/.mezite/local/ca-bundle.pemgit

The proxy address defaults to http://127.0.0.1:9443. Override with msh local shell-init --listen-addr <addr>.