Repository navigation
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.
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.