Quickstart
Status: Available.
Get msh local running in under five minutes. This guide covers installation, daemon setup, policy configuration, and your first proxied command.
1. Install
One install gets everything: the desktop app, daemon, and CLI — bundled together.
macOS (Homebrew)
brew install --cask leonardaustin/tap/mezite-desktopOr grab the latest .dmg from GitHub Releases.
The desktop app manages the daemon for you. Once it is open and the daemon is running, skip to Step 3 to route your shell through the proxy.
Linux
Download an .AppImage from GitHub Releases.
2. Install and start the daemon
msh local install registers msh local daemon as an OS service (launchd on macOS, systemd on Linux) and seeds the default policy.
msh local installVerify the daemon is running:
msh local status
# daemon up
# pid 12345
# uptime 4s
# build_version v0.2.26
# schema_version 2
# proxy_mode enforce
# policy loaded
# proxy_listen 127.0.0.1:9443
msh local installis idempotent — re-running it on an already-installed host re-renders the service unit and is a no-op otherwise.
3. Route your shell through the proxy
Print and source a shell snippet that sets HTTPS_PROXY and the matching CA-bundle env vars:
# bash / zsh — add to ~/.bashrc or ~/.zshrc
eval "$(msh local shell-init)"
# fish — add to ~/.config/fish/config.fish
msh local shell-init fish | sourceThe snippet is gated on msh local status --quiet, so a stopped daemon never leaves your CLIs pointing at a closed listener.
The proxy intercepts HTTPS traffic via a local MITM CA it generates at install time. On macOS,
msh local installtrusts this CA in the system keychain automatically. On Linux you may need to add~/.mezite/local/ca.crtto your system trust store. Runmsh local ca infoto check trust state.
4. Review the policy
The default policy ships with rules for managed Kubernetes clusters (EKS, GKE, AKS), Google Cloud, and Fly.io. Open it to understand what is configured:
msh local policy showEdit it interactively:
msh local policy editOr edit the file directly — changes hot-reload within a second:
$EDITOR ~/.mezite/local/policy.yamlA minimal policy that allows read operations and escalates writes for a local cluster:
kubectl:
inspect:
- "127.0.0.1:*" # local cluster endpoint
- "192.168.*.1:*"
default: escalate
groups:
read:
tiers: [observe]
mutate:
tiers: [modify]
delete:
tiers: [sensitive]
admin:
tiers: [break-glass]
rules:
allow:
groups: [read]
escalate:
groups: [mutate, delete, admin]See Config Reference for the full policy schema.
For the local cluster, set an explicit proxy in its existing kubeconfig cluster entry. Environment-selected proxies skip loopback destinations even when NO_PROXY is empty. Remove any existing certificate-authority-data field and use the actual absolute CA bundle path; kubeconfig does not expand~. Keep your existing context and user credentials.
clusters:
- name: local-cluster
cluster:
server: https://127.0.0.1:6443
proxy-url: http://127.0.0.1:9443
certificate-authority: /Users/you/.mezite/local/ca-bundle.pem5. Run a proxied command
With the shell snippet sourced, run any supported CLI tool normally. Read operations pass through without any prompt. Write and delete operations block until you approve them.
# Read — passes through instantly (observe tier)
kubectl get pods -n payments
# Write — blocks for approval (modify tier)
kubectl apply -f deployment.yamlWhen a request is held for approval, you will see it listed in the desktop app or via the CLI:
msh local approval list
# ID TIER HOST METHOD PATH
# a1b2c3d4 modify my-cluster.example.com POST /apis/apps/v1/deploymentsApprove or deny:
msh local approval allow a1b2c3d4
msh local approval deny a1b2c3d4 --reason "not during business hours"6. Check the audit log
Inspected requests in enforce mode are recorded in ~/.mezite/local/audit.jsonl. View recent entries:
msh local audit showFollow new entries in real time:
msh local audit tailSomething wrong? See Troubleshooting.