Repository navigation
HTTP API zh CN
tmag serve 通过独立版本的 tmag/http/v2 协议暴露本地实例。prefix + M-r 在 tmux window 中启动它,关闭 window 即停止。默认监听 127.0.0.1:7777。tmux 插件、hooks 和 CLI 的运行独立于 serve。
每个客户端使用自己的 bearer credential,以 owner 身份认证。所有 owner credentials 权限相同,可通过 tmag auth 分别撤销:issue 创建 credential;pair 创建有效期十分钟、仅可使用一次的 invitation;list 显示元数据;revoke 撤销一个或全部 credentials。issue 和 pair 支持 label,以及为最终 credential 设置有效期的可选 --ttl。
Token 只在签发时返回,持久化存储仅保存用于验证的 digest。在 authorization store 响应正常的情况下,撤销后已有订阅会在一秒内关闭。已接受的控制操作仍在原有 timeout 内完成,即使客户端断开或失去授权。
Credentials 持久化在 $XDG_STATE_HOME/tmag/auth/,默认 ~/.local/state/tmag/auth/,独立于 session realms。TMAG_AUTH_DIR 用于选择实例的授权目录。共享 home 的不同部署(包括 containers)应选择不同目录,除非有意共享 owner 授权。Session 清理及升级会保留 credentials;使用 --purge 完整卸载时会移除当前实例的 credentials。
获授权的客户端通过同一协议执行操作:POST /v2/act,携带 verb 和 target。send 立即投递 prompt——idle session 会启动一个 turn,working session 会在下一个步骤读到它,Codex daemon thread 则会并入当前 turn——并携带 text;interrupt 停止运行中的 turn,answer 回应未决请求。每个控制结果都通过 via 报告所用渠道。owner 调用者没有 agent 身份,因此 owner 的 prompt 不携带发送者行。GET /v2/info 列出支持的操作名。
| Serve flag | 含义 |
|---|---|
--addr ADDR |
Loopback 监听地址。 |
--host HOST |
额外允许的精确 HTTP Host 值,存在端口时需包含端口;可重复指定。 |
--origin ORIGIN |
额外允许的精确 browser origin,例如 https://client.example;可重复指定。 |
远程部署需自行提供加密 tunnel 或 reverse proxy,并用 --host 配置公开 host。每个数据请求仍需 owner credential,代理的身份 headers 不能替代它。独立 web clients 需使用明确允许的 origins。终止 TLS 的 reverse proxy 还需将公开的 HTTPS origin 加入允许列表,因为 loopback listener 本身使用 HTTP。
Tunnel 账户、部署、UI assets 和多机器聚合由外部客户端负责。tmag-client 仓库提供一个与 tmag serve 并排部署、供手机使用的网页,使用公开协议并独立发布。