Your Mac at the office is running a pile of agents, and you are at home in front of a
different computer. The phone can watch and reply, but sometimes you want a real terminal:
the session as it is, to keep working in. That is what gtmux attach is for.
Open a door on your Mac
gtmux serve # the other computer is on the same local network
gtmux tunnel # a public HTTPS address, for any other network that allows itOn the same network serve is enough. Across networks, tunnel gives the Mac an
https://… address over an outbound tunnel, with no port forwarding and no VPN; the
network you attach from still has to allow that address.
Remote access reference covers the
tunnel types.
Install gtmux on the other computer
On another Mac, use the install script or Homebrew. On Linux, build the CLI from source with Go 1.26 or newer:
go install github.com/chenchaoyi/gtmux/cmd/gtmux@latestUse an interactive terminal: Ghostty, iTerm2, Terminal, or whatever your Linux desktop has.
Pair that terminal once
On the Mac, run gtmux pair. Among its three forms of the code is a one-line
gtmux attach '…/#c=<code>' command: copy it into the other computer’s terminal and run it.
The code works once and expires in five minutes, so use a fresh one each time you pair.
The terminal then remembers its credential, and from then on this is enough:
gtmux attach <host> %7%7 is the pane ID. Leave it out and gtmux picks from the panes on your radar (agents in
tmux, plus any plain pane you watch): with exactly one, it attaches; with more, it shows a
numbered list with one row per pane, so two agents in one session are two rows. Outside an
interactive terminal it prints the list and exits instead. To supply a credential yourself instead of pairing, give it explicitly
and replace every placeholder:
gtmux attach <host> --token <token> %7What you get
Your local terminal becomes the Mac’s tmux session: the Mac’s tmux and its config, full-screen programs, colour, all of it. It attaches a tmux client to the whole session that pane belongs to, which is full owner access, so only you and your paired devices can use it.
A share link is for a browser or the phone, never for gtmux attach: gtmux refuses a share
link, or a share code given with --code, before redeeming it, and the Mac’s gtmux serve
refuses terminal access to guests. A share link grants panes, not a session; to give
someone one pane, see
Open one pane to a collaborator.
Two options worth knowing: --read-only to watch without sending input, and --predict
(experimental) to show your own typing immediately on a slow link.
Leave cleanly
Detach with tmux’s prefix d (by default Ctrl-b d) or with Ctrl-]. The session keeps
running on the Mac, untouched. Do not type exit in the pane: that closes the shell
in it.
Next: just want to watch and reply? The phone is smoother; see
Manage from your phone and the web · Every flag:
gtmux attach
Source: docs/guides/attach-from-anywhere.md at v1.0.114 · Edit on GitHub
你在公司的 Mac 上跑着一堆 agent，人却在家里另一台电脑前。手机能看能回，但有时你要的是一个真正的终端：原样进到那个会话里接着干。gtmux attach 就是干这个的。
在 Mac 上开个口子
gtmux serve # 另一台电脑和 Mac 在同一个局域网
gtmux tunnel # 公网 HTTPS 地址，给其他允许访问它的网络用同一个网络里 serve 就够。跨网络用 tunnel，它经出站隧道给 Mac 一个 https://… 地址，不用开路由端口，也不用 VPN；不过你所在的网络仍得允许访问这个地址。隧道有哪几种，见远程访问参考。
在另一台电脑上装 gtmux
另一台是 Mac，就用安装脚本或 Homebrew。Linux 上用 Go 1.26 或更新版本从源码装 CLI：
go install github.com/chenchaoyi/gtmux/cmd/gtmux@latest要在交互式终端里用：Ghostty、iTerm2、Terminal，或者你 Linux 桌面上的终端都行。
给那个终端配一次对
在 Mac 上跑 gtmux pair。它印出的三种形式里有一行 gtmux attach '…/#c=<code>' 命令，复制到另一台电脑的终端里运行即可。配对码只能用一次，5 分钟过期，所以每次配对都要新的。
之后这个终端会记住凭据，再连只要：
gtmux attach <host> %7%7 是 pane ID。不写的话，gtmux 从雷达上的 pane 里挑（tmux 里的 agent，加上你主动 watch 的普通 pane）：只有一个就直接接；不止一个就给你一个带编号的列表，一个 pane 一行，所以同一会话里的两个 agent 是两行。不在交互式终端里时，它只打印列表然后退出。不想配对、想自己提供凭据，就明确写出来，并替换掉所有占位符：
gtmux attach <host> --token <token> %7连上之后
你眼前的终端就成了 Mac 上的那个 tmux 会话：Mac 的 tmux 和它的配置、全屏程序、颜色，全部照旧。它是把一个 tmux 客户端接到那个 pane 所在的整个会话上，等于 owner 的完整权限，所以只有你和你配对过的设备能用。
分享链接是给浏览器和手机用的，不能用于 gtmux attach：分享链接，或用 --code 给的分享码，gtmux 在兑换之前就会拒绝；Mac 上的 gtmux serve 也不给访客终端权限。分享链接给的是 pane，不是会话；只想把一个 pane 给别人，见把一个 pane 开给协作者。
两个值得知道的选项：--read-only 只看不输入；--predict（实验性）在慢网络上让你打的字立刻显示出来。
干完就走
按 tmux 的 前缀键 d（默认是 Ctrl-b d）或 Ctrl-] 断开。会话在 Mac 上照常跑，一点不受影响。别在 pane 里敲 exit，那会关掉里面的 shell。
接下来：只想看看、回一句？手机更顺手，见用手机和网页远程管理 · 全部参数：gtmux attach
来源：docs/guides/attach-from-anywhere.zh.md（v1.0.114）· 在 GitHub 上编辑