Skip to content

HTTP API

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

HTTP API

tmag serve exposes this local instance through the independently versioned tmag/http/v2 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.

Control

An authorized client acts through the same contract: POST /v2/act with a verb and a target. send delivers a prompt now — an idle session starts a turn, a working one reads it at its next step, and a Codex daemon thread joins its active turn — and carries text; interrupt stops a running turn, and answer decides an open request. Every control result reports via, the channel that carried it. Owner callers have no agent identity, so an owner's prompt carries no sender line. GET /v2/info lists the supported operation names.

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 tmag-client repository holds a web page for a phone, served beside tmag serve; it consumes public contracts and releases separately.

Clone this wiki locally