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
| Scope | Allows |
|---|---|
use | Chat, 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 |
control | Everything 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-fingerprintorMIRMIR_REMOTE_FINGERPRINTon every run (read it withmirmir 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 statuslists clients seen in the last 15 minutes with the key name, scope, address and request count.