Skip to content

HTTP API

ChrAlpha edited this page Nov 9, 2026 · 5 revisions
🇬🇧English | 🇨🇳中文

HTTP API

tmag serve exposes this local instance through the independently versioned tmag/http/v1 contract. prefix + M-r starts it in a tmux window; closing that window stops it. Its default listener is 127.0.0.1:7777. The tmux plugin, hooks and CLI work independently of serve.

A client authenticates as the owner with its own bearer credential. All owner credentials have the same authority. Each can be revoked independently through tmag auth; issue creates a credential, pair opens a ten-minute, single-use invitation, list shows metadata, and revoke withdraws one credential or all of them. issue and pair accept a label and optional --ttl for the resulting credential. Tokens are returned only on issuance; only verification digests are stored. Existing subscriptions close within one second of revocation under a responsive authorization store. Accepted control operations finish within their existing timeout even if the client disconnects or loses authorization.

Credentials persist in $XDG_STATE_HOME/tmag/auth/ (default ~/.local/state/tmag/auth/), independently of session realms. TMAG_AUTH_DIR selects an instance's authorization directory. Separate deployments sharing a home, including containers, must select separate directories unless they intentionally share owner authorization. Session cleanup and upgrades keep credentials; full uninstall with --purge removes this instance's credentials.

Serve flag Meaning
--addr ADDR loopback listen address
--host HOST additional exact HTTP Host value, including a port when present; repeatable
--origin ORIGIN additional exact browser origin, such as https://client.example; repeatable

Remote deployment supplies an encrypted tunnel or reverse proxy and configures its public host with --host. Every data request still needs the owner's credential. Proxy identity headers do not replace that credential. Independent web clients use explicitly allowed origins. A TLS-terminating reverse proxy also lists its public HTTPS origin, since the loopback listener itself uses HTTP. Tunnel accounts, deployment, UI assets and multi-machine aggregation belong to external clients. The extracted tmag-client repository owns the existing web client and command gateway; it consumes public contracts and releases separately.

Clone this wiki locally