Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Remote access

A MiRMiR server can offer its runtime to other computers: Mirmir for Mac, the CLI and the TUI connect over TLS with an API key. The local Unix socket is unchanged and needs no key. This is separate from the OpenAI-compatible HTTP API, which has its own key.

Turn it on

On the server:

mirmir remote enable                 # listens on 0.0.0.0:7443
mirmir remote enable --bind 10.0.0.4:7443

For a system service, add --system and run as a member of the service’s group. enable starts the listener at once and keeps it enabled across restarts. Only mirmir serve (and the system service) opens the listener; a server that the TUI or a command starts for itself never does. The listener address is changed only with mirmir remote enable --bind and mirmir remote disable, not with mirmir config set. When no key exists yet, it creates a control key and prints it once, together with the certificate fingerprint. Open the port in the firewall only for networks that should reach it.

mirmir remote status                 # listener, fingerprint, keys, recent clients
mirmir remote disable                # stop listening; keys are kept

Keys and scopes

mirmir remote key create --name studio-mac --scope use
mirmir remote key create --name ops-laptop --scope control
mirmir remote key list
mirmir remote key revoke 3f9c0d6e1a2b4c5d
ScopeAllows
useChat, embeddings, reranking, model lists and inspection, catalog search, telemetry, activity and the redacted configuration. A chat, embedding or rerank request may load a model the server offers, and unload another to make room
controlEverything in use, plus explicitly loading, unloading, downloading and removing models, model and runtime settings, and cancelling operations

No key, whatever its scope, can change server.* settings (listener, TLS certificate, HTTP binding, CORS) or the stored HTTP API key and Hugging Face token; those change only on the server itself. A remote key names only models the server offers (configured keys, loaded models and the paths it lists itself); any other name or path is refused as an unknown model. The configuration a remote key reads omits the raw TOML and file paths.

Keys and the listener are managed only on the server itself, over its local socket: no remote key can create or revoke keys. A key reads mmk_<id>_<secret>; the server stores only a digest of the secret. A revoked key is refused on its next request; a stream it already opened, such as a running generation or an activity watch, continues until it ends.

Certificates

By default the server generates a self-signed certificate once and keeps it. Clients trust it by its SHA-256 fingerprint; compare the value they show with mirmir remote status on the server.

  • Mirmir for Mac shows the fingerprint when you add the server, pins it once you trust it and refuses a later change.
  • The CLI and TUI pin nothing on their own: pass the fingerprint with --remote-fingerprint or MIRMIR_REMOTE_FINGERPRINT on every run (read it with mirmir remote fingerprint HOST[:PORT]). Without it they verify the certificate against the system’s CA roots, which refuses the default self-signed certificate.

To use a certificate issued by a CA, which clients verify without pinning:

mirmir config set server.remote_tls_cert /etc/mirmir/remote/fullchain.pem
mirmir config set server.remote_tls_key /etc/mirmir/remote/privkey.pem
mirmir remote enable

Each command saves one key; the listener needs both. While only one is set, mirmir config show reports the other as missing and mirmir remote enable names it; a server that starts with half a pair keeps the listener off and shows why in mirmir remote status. mirmir remote enable restarts a running listener with the new certificate. To return to the self-signed certificate:

mirmir config set server.remote_tls_cert auto
mirmir config set server.remote_tls_key auto
mirmir remote enable

Connect

From Mirmir for Mac: Instances → Add Server, enter host:7443 (a pasted grpcs://host:7443 works too) and the key, check the fingerprint, then Test Connection and Add Server. The key is stored in the Keychain. Edit Server… changes the address, key or trusted certificate and keeps the server’s chats; a removed server’s chats come back when a server at the same address is added again.

From the CLI or TUI on another computer:

mirmir remote fingerprint gpu-server.local    # what the server presents
export MIRMIR_REMOTE_KEY=mmk_…
mirmir --remote gpu-server.local --remote-fingerprint 'AB:CD:…' status
mirmir --remote gpu-server.local --remote-fingerprint 'AB:CD:…' model list
mirmir --remote gpu-server.local --remote-fingerprint 'AB:CD:…'   # TUI

--remote also accepts the grpcs://host:port form that mirmir remote status shows.

The port defaults to 7443. Like --system, a remote client only attaches: it never starts or configures a local runtime.

What is enforced

  • TLS 1.2 or 1.3; a pinned client accepts only the server holding that certificate’s private key.
  • No key or an unknown key: UNAUTHENTICATED. A key whose scope is too narrow, or a local-only method: PERMISSION_DENIED.
  • More than 20 failed attempts within a minute from one IPv4 address or IPv6 /64 network refuse further failed attempts from it for the rest of the minute; a valid key from that network keeps working. A connection without a peer address is refused.
  • Rejections are logged with the address and method, never the key.
  • mirmir remote status lists clients seen in the last 15 minutes with the key name, scope, address and request count.