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 keychainThere 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 setHTTPS_PROXYand 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
| Key | Covers |
|---|---|
kubectl | Kubernetes API traffic (kubectl, kustomize) |
gcloud | Google Cloud API traffic (gcloud CLI) |
fly | Fly.io API traffic (flyctl, fly) |
aws | AWS API traffic (aws CLI) |
github | GitHub API traffic (gh CLI) |
cloudflare | Cloudflare API traffic (wrangler, flarectl) |
generic | Any 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.
| Setting | Description |
|---|---|
proxy_listen | Address and port the proxy listens on |
log_level | Logging verbosity |
default_mode | Default proxy mode at startup |
telemetry_opt_in | Whether anonymous telemetry is enabled |
Environment variables (shell-init snippet)
The msh local shell-init snippet exports the following when the daemon is up:
| Variable | Value | Purpose |
|---|---|---|
HTTPS_PROXY | http://127.0.0.1:9443 | Routes HTTPS traffic through the msh local proxy |
HTTP_PROXY | http://127.0.0.1:9443 | Routes HTTP traffic |
SSL_CERT_FILE | $HOME/.mezite/local/ca-bundle.pem | System roots + dev CA for Go/C toolchains |
REQUESTS_CA_BUNDLE | $HOME/.mezite/local/ca-bundle.pem | Python requests library |
NODE_EXTRA_CA_CERTS | $HOME/.mezite/local/ca-bundle.pem | Node.js |
AWS_CA_BUNDLE | $HOME/.mezite/local/ca-bundle.pem | AWS CLI |
GIT_SSL_CAINFO | $HOME/.mezite/local/ca-bundle.pem | git |
The proxy address defaults to http://127.0.0.1:9443. Override with msh local shell-init --listen-addr <addr>.