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-desktop

Or 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 install

Verify 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 install is 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 | source

The 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 install trusts this CA in the system keychain automatically. On Linux you may need to add ~/.mezite/local/ca.crt to your system trust store. Run msh local ca info to 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 show

Edit it interactively:

msh local policy edit

Or edit the file directly — changes hot-reload within a second:

$EDITOR ~/.mezite/local/policy.yaml

A 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.pem

5. 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.yaml

When 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/deployments

Approve 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 show

Follow new entries in real time:

msh local audit tail

Something wrong? See Troubleshooting.