The best way to control Claude Code, Codex and more from any computer or phone
| 1 | # Remote access |
| 2 | |
| 3 | Connect a phone, browser, or another desktop app to T3 Code running on a different |
| 4 | machine. That machine must stay running and reachable while you work. |
| 5 | |
| 6 | ## T3 Connect |
| 7 | |
| 8 | T3 Connect makes an environment available to your other devices without setting |
| 9 | up router forwarding. In the desktop app on the host, open **Settings → |
| 10 | Sharing & access**, sign in, and enable **T3 Connect** for that environment. |
| 11 | |
| 12 | For a command-line host, run: |
| 13 | |
| 14 | ```bash |
| 15 | t3 up |
| 16 | ``` |
| 17 | |
| 18 | It asks how your other devices reach the machine: T3 Connect, the local network, |
| 19 | or both. Choose T3 Connect and follow the sign-in instructions. It then runs |
| 20 | T3 Code as a [background service](./background-service.md). |
| 21 | `t3 connect` is the same as `t3 up --connect`. Run `t3 up` again to change your |
| 22 | choice, and `t3 status` to see it. |
| 23 | |
| 24 | Instead of the background service, you can keep the desktop app running with |
| 25 | its local environment enabled. Closing the desktop app's last window stops its |
| 26 | local server. Saving your sign-in alone does not start a server or make the |
| 27 | machine reachable. |
| 28 | |
| 29 | On your other device, sign in to the same T3 Connect account and choose the |
| 30 | environment. On the app.t3.codes home page with no computer added yet, signing |
| 31 | in adds compatible computers linked to your account. Over SSH, the CLI prints a |
| 32 | browser link and a short code. Open the link on any device, confirm the code |
| 33 | matches, and approve. The CLI continues on its own, so you do not need to forward |
| 34 | an OAuth callback port. |
| 35 | |
| 36 | T3 Connect renews access credentials when needed without disconnecting a healthy |
| 37 | connection. Pull request diffs and provider settings keep working after the |
| 38 | previous credential expires. A failed renewal affects that request; it does not |
| 39 | disconnect an otherwise healthy conversation. |
| 40 | |
| 41 | ### Approve new devices |
| 42 | |
| 43 | By default, any device signed in to your T3 Connect account can open a linked |
| 44 | machine. To require approval instead, turn on **Require approval for new |
| 45 | devices** with the T3 Connect settings in **Settings → Sharing & access** on the |
| 46 | host, or when you first set up T3 Connect. Then someone who takes over your T3 |
| 47 | Connect account cannot reach the machine from a new device without your |
| 48 | approval. Review the devices that are already approved, described below. |
| 49 | |
| 50 | A new device waits and shows a code such as `K7QM-2XFD`. Approve it from a |
| 51 | device that is already connected, using the prompt or **Settings → Sharing & |
| 52 | access**. Check that the code matches the one on the waiting device. On a |
| 53 | headless host, run `t3 auth connect-device list` and then |
| 54 | `t3 auth connect-device approve K7QM-2XFD`. A request expires after 10 minutes, |
| 55 | and the device asks again when it retries. Deny keeps that device out until its |
| 56 | request expires. |
| 57 | |
| 58 | Each device is approved once. Revoke it from **T3 Connect devices** in the same |
| 59 | settings page, or with `t3 auth connect-device revoke <code>`. With approval on, |
| 60 | it has to ask again. With approval off, it can connect again on its own, so |
| 61 | revoking in the app offers to turn approval on first. Devices that connected through T3 Connect while approval was off stay |
| 62 | approved and appear in that list for you to review. A device that has not |
| 63 | connected since you updated T3 Code asks for approval like a new one. Older apps |
| 64 | cannot show the code, so update them before you turn approval on. |
| 65 | |
| 66 | ### Scripts and agents |
| 67 | |
| 68 | `t3 up` asks nothing when you name a choice: `--connect`, `--lan`, or their |
| 69 | `--no-` forms. Choices you do not name keep their settings, and `--yes` takes |
| 70 | the defaults. Without a terminal: |
| 71 | |
| 72 | - T3 Connect sign-in prints a URL and a code. Approve it on any device. |
| 73 | - A needed restart runs without asking, and stops running agent turns. |
| 74 | - With nothing set up and no choice named, `t3 up` stops and names the flags. |
| 75 | |
| 76 | `t3 status --json` prints the settings. `t3 up --help` lists every flag with |
| 77 | examples. |
| 78 | |
| 79 | ### More machines with T3 Chat |
| 80 | |
| 81 | Each T3 Connect account can link up to 3 machines. Phones and browsers do not |
| 82 | count. A paid T3 Chat plan raises the limit to 10 machines with Pro, or 100 with |
| 83 | Premier. |
| 84 | |
| 85 | To link T3 Chat, open your account menu on the web or desktop app, go to |
| 86 | **T3 Chat**, and select **Link T3 Chat**. Sign in to T3 Chat in the window that |
| 87 | opens and approve. The new limit applies the next time you add a machine. If you |
| 88 | cancel or downgrade T3 Chat, machines you already linked stay linked, but you |
| 89 | cannot add more until you are under the limit again. |
| 90 | |
| 91 | ## Pair over a LAN or private network |
| 92 | |
| 93 | Use direct pairing when the other device can reach the host's network address. |
| 94 | |
| 95 | On a desktop host, open **Settings → Sharing & access**, enable **Network access**, |
| 96 | then create a pairing link using an address the other device can reach. Changing |
| 97 | network access restarts the desktop app. You can turn it off in the same place. |
| 98 | |
| 99 | For a command-line host, choose the local network in `t3 up`, or run: |
| 100 | |
| 101 | ```bash |
| 102 | t3 up --lan |
| 103 | ``` |
| 104 | |
| 105 | For a server in a terminal, run `t3 serve --lan`. Either way, T3 Code then |
| 106 | accepts connections from your local network and tailnet, so a pairing code is |
| 107 | all that keeps other devices on them out. |
| 108 | |
| 109 | If a server is already running, generate a fresh link without restarting it: |
| 110 | |
| 111 | ```bash |
| 112 | t3 pair |
| 113 | ``` |
| 114 | |
| 115 | Scan the QR code on your phone or paste the pairing URL into **Add environment** |
| 116 | in the receiving app. Connection settings are under **Settings → Environments** |
| 117 | on web and desktop and **Settings → Environments** on mobile. A loopback address |
| 118 | such as `127.0.0.1` reaches only the device opening the link. |
| 119 | |
| 120 | On a computer with the desktop app, you can open the printed `t3code://pair` |
| 121 | app link instead. The desktop app asks you to confirm the server address, then |
| 122 | adds it. |
| 123 | |
| 124 | If your HTTPS endpoint uses a certificate from your own certificate authority, |
| 125 | install that CA on Android as a **CA certificate** in its security settings; the |
| 126 | Android app then trusts it. |
| 127 | |
| 128 | Pairing authorizes that device for future connections. Use a fresh one-time link |
| 129 | for each new device; you do not need the original token to reconnect. A device |
| 130 | stays signed in while you keep using it, until you revoke it in **Settings → |
| 131 | Sharing & access** on the host. One unused for 30 days, or paired with a host |
| 132 | older than this release, has to pair again. Links |
| 133 | created in Settings can only be copied from the client that created them while |
| 134 | its Sharing & access page stays open. If you leave or reload that page, create |
| 135 | another link to share. |
| 136 | |
| 137 | ### Reach one machine several ways |
| 138 | |
| 139 | A machine can have more than one route: LAN, Tailscale, another VPN, a public |
| 140 | URL, SSH, or T3 Connect. Tailscale shares its `100.64.0.0/10` address range with |
| 141 | other VPNs such as Cloudflare WARP, so an address in that range shows as VPN |
| 142 | unless the machine confirms it is on Tailscale. To add a route, choose **Add |
| 143 | route** in the machine's route list, or next to it in the T3 Connect list. |
| 144 | A pairing link for a saved machine is refused when it comes from an address |
| 145 | that machine does not have yet; add that address with **Add route** instead. |
| 146 | Pairing again over an address the machine already has still works. A new route |
| 147 | is placed by speed, in that order, and you can reorder routes at any time. |
| 148 | |
| 149 | While connected through T3 Connect or a paired address, T3 Code also learns the |
| 150 | machine's current LAN and Tailscale addresses and adds them as routes, so |
| 151 | pairing once through T3 Connect is enough to use the LAN at home. When the |
| 152 | machine's LAN address changes, for example after it joins another Wi-Fi network, |
| 153 | the learned route follows it. The machine must allow network access for its LAN |
| 154 | address to be learned: **Network access** in the desktop app, or the |
| 155 | [local network](./background-service.md#local-network-access) choice in `t3 up`. |
| 156 | You can reorder a learned route, but not remove it; it |
| 157 | goes away with the route it was learned through, or when the machine stops |
| 158 | reporting that address. |
| 159 | |
| 160 | T3 Code connects over the first route that answers. Away from home, a LAN |
| 161 | address that does not answer is checked briefly and skipped. It is only tried |
| 162 | again, after the other routes, if none of them connect. While connected over a |
| 163 | later route, T3 Code checks the earlier ones when your network changes, when you |
| 164 | return to the app, and every minute, and moves back as soon as one works. A |
| 165 | route whose machine refused this device's sign-in is marked **Sign-in |
| 166 | refused**; pair that address again with **Add route** to use it. |
| 167 | |
| 168 | On web and desktop, select the route count under the machine's name in |
| 169 | **Settings → Environments** to see its routes. Drag a route to change the order, |
| 170 | or remove it. On mobile, open the machine under **Settings → Environments** and |
| 171 | choose **Edit**. Signing out of T3 Connect removes only that route; a machine |
| 172 | you can still reach another way stays saved. |
| 173 | |
| 174 | Open **Permissions** next to **Routes** in web or desktop, or **Your permissions** |
| 175 | in the mobile route details, to see what your current connection can do on that |
| 176 | environment. For a remote environment, this is in its route details. Permissions |
| 177 | shown there apply only to the route marked **In use**; other routes are not |
| 178 | checked. Direct pairing and T3 Connect have separate sessions and may grant |
| 179 | different permissions. |
| 180 | |
| 181 | ### Balance new threads across machines |
| 182 | |
| 183 | Auto balance is off by default. On web and desktop, enable it in |
| 184 | **Settings → Environments → Load balancing** to automatically choose a machine for |
| 185 | new threads in projects grouped across connected environments. The section |
| 186 | appears once two or more machines are switched on. |
| 187 | Each machine starts at **Normal**. Choose **Prefer** to favor it when it has CPU and |
| 188 | memory available, **Less often** to reduce its share, or **Manual only** to exclude |
| 189 | it from automatic selection. These are preferences, not fixed traffic percentages. |
| 190 | Preferences are saved separately in each client. |
| 191 | |
| 192 | The composer checks eligible machines when choosing a draft's environment, then keeps |
| 193 | that choice stable. Choose **Auto balance** again to check current resources, or choose |
| 194 | a specific machine to override it. Choosing a branch or worktree also keeps the draft |
| 195 | on that machine. Existing threads stay where they started. If resource checks are |
| 196 | unavailable or all eligible machines are full, choose a machine manually to continue. |
| 197 | Mobile keeps its manual environment selection. |
| 198 | |
| 199 | ### Tailscale HTTPS |
| 200 | |
| 201 | Join both devices to the same tailnet. In the desktop app, enable **Tailscale |
| 202 | HTTPS** in **Settings → Sharing & access**. Turn it off there to remove that route. |
| 203 | |
| 204 | Your tailnet needs MagicDNS and HTTPS certificates enabled; see |
| 205 | [Tailscale's HTTPS setup](https://tailscale.com/docs/how-to/set-up-https-certificates). |
| 206 | On Linux, T3 Code also needs permission to manage Tailscale; see |
| 207 | [operator permission](https://tailscale.com/docs/reference/troubleshooting/linux/linux-operator-permission) |
| 208 | for non-root users. If any of these is missing, T3 Code still starts but can't |
| 209 | add the HTTPS route. |
| 210 | |
| 211 | To start a command-line server with Tailscale HTTPS: |
| 212 | |
| 213 | ```bash |
| 214 | t3 serve --tailscale-serve |
| 215 | ``` |
| 216 | |
| 217 | For an already-running server: |
| 218 | |
| 219 | ```bash |
| 220 | t3 pair --tailscale |
| 221 | ``` |
| 222 | |
| 223 | The pairing link uses an address such as `https://machine.tailnet.ts.net/`. |
| 224 | The mapping created by `pair --tailscale` persists across restarts. Remove its |
| 225 | default-port mapping with: |
| 226 | |
| 227 | ```bash |
| 228 | tailscale serve --https=443 --set-path=/ off |
| 229 | ``` |
| 230 | |
| 231 | If that port is already in use, choose another with |
| 232 | `--tailscale-serve-port`. See `t3 pair --help` for other pairing options. |
| 233 | |
| 234 | ### Hosted web app |
| 235 | |
| 236 | [app.t3.codes](https://app.t3.codes) needs an HTTPS endpoint. It connects directly |
| 237 | to your server; a hosted pairing link does not make an unreachable backend |
| 238 | reachable or convert HTTP to HTTPS. |
| 239 | |
| 240 | For a plain HTTP LAN endpoint, use the direct pairing URL in a browser that can |
| 241 | open it, or pair from the desktop app. On mobile, an IP address entered without a |
| 242 | scheme uses HTTP, so include `https://` when your server uses HTTPS. |
| 243 | |
| 244 | ## Desktop-managed SSH |
| 245 | |
| 246 | In the desktop app, open **Settings → Environments → Add environment**, choose |
| 247 | **SSH**, and enter a host or SSH alias such as `user@example.com`. T3 Code starts |
| 248 | or reuses a server there and opens the port forward for you. Projects, provider |
| 249 | credentials, and agent work stay on the remote machine. |
| 250 | |
| 251 | The remote host must be Linux or an Apple Silicon Mac with `curl` or `wget`, |
| 252 | `tar`, `sha256sum` or `shasum`, and [provider setup](./install.md#providers). |
| 253 | The first launch downloads T3 Code's server to `~/.t3/runtime` on the host, so |
| 254 | it takes longer than later ones. |
| 255 | Provider CLIs must be on the `PATH` of a non-interactive login shell there; |
| 256 | check with: |
| 257 | |
| 258 | ```bash |
| 259 | ssh user@example.com 'sh -lc "command -v claude codex"' |
| 260 | ``` |
| 261 | |
| 262 | T3 Code cannot answer a second sign-in prompt such as a Duo code. On macOS and |
| 263 | Linux it can reuse a connection you signed in to in a terminal instead: turn on |
| 264 | connection sharing for the host in `~/.ssh/config`, run `ssh <alias>`, then |
| 265 | connect. When that connection closes, sign in again in a terminal and retry. |
| 266 | |
| 267 | ```sshconfig |
| 268 | Host <alias> |
| 269 | ControlMaster auto |
| 270 | ControlPath ~/.ssh/cm-%C |
| 271 | ControlPersist 8h |
| 272 | ``` |
| 273 | |
| 274 | If SSH reconnecting fails after an app update, retry the launch once. Removing |
| 275 | the connection stops a server that T3 Code launched; a server that was already |
| 276 | running is left alone. |
| 277 | |
| 278 | Each desktop app keeps one session on the host for its SSH connection and reuses |
| 279 | it when it reconnects. Revoke sessions you no longer use in **Settings → |
| 280 | Sharing & access** on the host, or on a headless host with `t3 auth session list` and |
| 281 | `t3 auth session revoke <id>`. A desktop that can still sign in over SSH pairs |
| 282 | again on its next connect. |
| 283 | |
| 284 | For Antigravity's Google callback on a remote host, see |
| 285 | [remote sign-in](./providers-antigravity.md#sign-in-from-a-remote-device). |
| 286 | |
| 287 | ## Browser on a remote environment |
| 288 | |
| 289 | Browser tabs belong to the environment, so you and your agents see the same |
| 290 | tabs from any device. The desktop app shows its own environment's tabs |
| 291 | directly. Every other device, and the desktop app for other environments, |
| 292 | streams them from the host. Agents keep using them while no device is |
| 293 | connected, and `localhost` addresses reach servers on the host. |
| 294 | |
| 295 | A tab you open yourself in the desktop app for another environment loads on |
| 296 | your computer instead, so the element picker, screenshots, and annotations work |
| 297 | as they do locally. Its `localhost` addresses still reach servers on the host, |
| 298 | over the connection the app already has, whichever way you connected. If the |
| 299 | host cannot be reached, the tab shows a connection error; a `localhost`, |
| 300 | `127.0.0.1`, or `[::1]` address never opens a server on your own computer. |
| 301 | Other names that point at your computer, such as `/etc/hosts` entries, still |
| 302 | do. These tabs ignore your system proxy settings, so they can't reach a host |
| 303 | you connect to only through a proxy or over HTTPS with a privately issued |
| 304 | certificate. The web app keeps streaming. |
| 305 | |
| 306 | The desktop app can also forward a port on the host to your computer, so any |
| 307 | app there, such as your own browser, `curl`, or a database client, reaches it |
| 308 | at `localhost`. Use the forward button on a server in the thread's **Servers** |
| 309 | list, or **Forwarded ports** in the command palette, where you can also type |
| 310 | any port number and stop forwards. A forward keeps the host's port number |
| 311 | unless that port is taken on your computer, in which case it uses a free one |
| 312 | and shows it. Forwards end when you stop them or quit the app. ⌘-click |
| 313 | (Ctrl-click on Windows and Linux) on a remote server forwards it and opens it |
| 314 | in your browser. |
| 315 | |
| 316 | A forwarded port behaves like a server running on your computer: anything on |
| 317 | your computer can reach it, including web pages open in your browser, so a |
| 318 | forwarded service is exposed the same way a local dev server is. Forwards |
| 319 | listen only on your computer's loopback, never on your network. On Linux they |
| 320 | accept only apps running as your user; on macOS and Windows, other users signed |
| 321 | in to the same computer can reach them too. |
| 322 | |
| 323 | On iPhone, iPad, and Android, a tab showing one of the host's `localhost` pages |
| 324 | has **Open on this device** in its menu. So does a long press on a `localhost` |
| 325 | link in a chat. It opens the page in the phone's own browser view, at the same |
| 326 | `localhost` address, so it scrolls and responds to touch natively. Like the |
| 327 | desktop app, it never opens a server on the phone itself. The streamed tab |
| 328 | stays where it was, and agents keep using it. Each host keeps its own cookies |
| 329 | and site data on the phone. On iPhone and iPad the page runs under a stand-in |
| 330 | address while the address bar shows `localhost`, so browser features that need |
| 331 | a secure page, such as the clipboard or service workers, aren't available there. |
| 332 | |
| 333 | All of this rides the host's preview tunnel. Turn off **Settings → Sharing & |
| 334 | access → Preview tunnel** on the host to stop other devices from loading its |
| 335 | `localhost` pages themselves: port forwarding and **Open on this device** go |
| 336 | away, and open tunnels close. Tabs keep working by streaming from the host, so |
| 337 | anyone who can use the host's browser tabs can still view its `localhost` pages |
| 338 | there. An administrator can also turn it off with a |
| 339 | [managed policy](./managed-policy.md#other-capabilities). |
| 340 | |
| 341 | The first tab downloads a headless Chrome, about 120 MB, into the T3 home. It |
| 342 | is the same browser [HTML renders](html-renders.md) use, so a host downloads it |
| 343 | only once. Some Linux hosts need [setup](#browser-host-setup) before it can |
| 344 | start. |
| 345 | |
| 346 | Agent tabs have separate storage and share a Chromium process. Take control before |
| 347 | typing into an agent's tab, then release control when you want the agent to |
| 348 | continue. Read-only connections can watch without changing the page. |
| 349 | |
| 350 | While you have control, the tab works with your device: text the page copies or |
| 351 | cuts goes to your clipboard, a file picker on the page opens your device's |
| 352 | picker, and a finished download is offered for you to save. Popups such as |
| 353 | sign-in windows open as their own tabs. Downloads stay on the host until the |
| 354 | tab closes. Audio does not play on your device. |
| 355 | |
| 356 | On a phone, tap the floating preview's corner dot to show its controls, then |
| 357 | **Pop into separate window** to keep watching in picture-in-picture over other |
| 358 | apps. |
| 359 | |
| 360 | ### Local servers |
| 361 | |
| 362 | The browser lists ports held by processes your terminals and agents started. |
| 363 | T3 Code reads which process holds each port and never connects to it, so a |
| 364 | listed port opens as `http://localhost:<port>` and might not be a web page. For |
| 365 | an HTTPS server or a specific path, set the **Preview URL** on the project |
| 366 | script that starts it; T3 Code checks that address and opens it as written. |
| 367 | |
| 368 | To stop listing ports, set `T3CODE_PORT_DISCOVERY=0` in the environment that |
| 369 | starts the T3 Code server, such as |
| 370 | [`service.env`](./background-service.md#configure-the-service-environment) for |
| 371 | the background service, and restart it. Script preview URLs still appear. |
| 372 | |
| 373 | ### Browser host setup |
| 374 | |
| 375 | macOS, Windows, and Linux desktops run the browser as is. Some Linux hosts need |
| 376 | one-time setup: Ubuntu 23.10 and later block the sandbox the browser runs in, |
| 377 | and minimal images and containers lack libraries it loads. When that happens, |
| 378 | the server says so at startup, and browser tabs and HTML previews show the |
| 379 | command to run on the host: |
| 380 | |
| 381 | ```sh |
| 382 | sudo t3 browser setup |
| 383 | ``` |
| 384 | |
| 385 | The server shows the exact line for how you started it, and keeps your `PATH` |
| 386 | when you started it with `npx` and Node is installed only for your user. Where `t3` is not on your `PATH`, such as with only the |
| 387 | desktop app installed, it names the full path of the app's own `t3` instead. It allows Chrome's sandbox with an AppArmor profile and installs |
| 388 | any missing libraries and system fonts with apt; pages that load without text |
| 389 | can mean the host has no fonts. It is safe to run again, and each run reloads |
| 390 | the AppArmor profile: run it again if the browser reports a blocked sandbox on a |
| 391 | host restored from an image or snapshot, where the profile can be on disk |
| 392 | without being loaded. Without `sudo`, it only reports what it would change. |
| 393 | |
| 394 | The browser runs in Chrome's sandbox by default. Chrome cannot start that sandbox |
| 395 | as root. If your T3 server runs as root, run it as a nonroot user to keep |
| 396 | sandboxing enabled. `t3 browser setup` does not fix this root restriction. |
| 397 | |
| 398 | If you need to run as root, or cannot enable the sandbox on your host, set |
| 399 | `T3CODE_SERVER_BROWSER_SANDBOX=0` in the **T3 server's environment** and restart |
| 400 | the server. This disables Chrome's sandbox. For a manual launch: |
| 401 | |
| 402 | ```sh |
| 403 | T3CODE_SERVER_BROWSER_SANDBOX=0 t3 serve |
| 404 | ``` |
| 405 | |
| 406 | For a systemd service, add `Environment=T3CODE_SERVER_BROWSER_SANDBOX=0` under |
| 407 | `[Service]` in its configuration, run `sudo systemctl daemon-reload`, then restart |
| 408 | your T3 service. Setting the variable in an agent's terminal does not change the |
| 409 | environment of an already running T3 server. |
| 410 | |
| 411 | ## Connect an outside agent |
| 412 | |
| 413 | Claude Code, Codex, ChatGPT and other agents T3 Code did not start can drive |
| 414 | threads on an environment through its MCP server. See |
| 415 | [outside agents](./outside-agents.md) for setup. |
| 416 | |
| 417 | ## Link another environment |
| 418 | |
| 419 | Link two machines, such as your laptop and a VPS, and agents on one can work on |
| 420 | the other: launch, message, wait on and stop its threads, answer their |
| 421 | questions, and manage its queues, projects and scheduled tasks. |
| 422 | |
| 423 | Linked environments is a beta. Turn it on for both machines in **Settings → |
| 424 | Labs**; on mobile, **Settings → Labs** lists each connected machine. While it is |
| 425 | off on either machine, agents start nothing over a link between them. A task |
| 426 | already running on the other machine still finishes, and if that machine has it |
| 427 | off, its result arrives once it is back on. |
| 428 | |
| 429 | On the machine you will work from, open **Settings → Environments → Linked environments**, |
| 430 | choose **Link**, and pick the other machine or enter its address. The list |
| 431 | holds the machines this app knows and those on your T3 Connect account. If this |
| 432 | app has an address for that machine and is connected to it with a session that |
| 433 | manages access there, it makes the pairing code itself; otherwise paste one |
| 434 | from that machine's **Settings → Sharing & access**. An address you type always |
| 435 | needs a pasted code. From a terminal, use |
| 436 | `t3 environment link <address> --pairing-code <code> --access <mode>`. |
| 437 | |
| 438 | To link many machines at once, choose **Link several…** (it appears once this |
| 439 | app has two other machines saved). Tick the machines, pick one access level for |
| 440 | all of them, and confirm once. A machine can be ticked when this app is |
| 441 | connected to it with a session that manages access there and has an address |
| 442 | another machine can reach; the list says why when it cannot. Each machine |
| 443 | reports its own result, and the ones that failed stay ticked so you can try |
| 444 | only those again. Machines already linked are left as they are. |
| 445 | |
| 446 | For machines no app is connected to, put one `<address> <pairing-code>` per |
| 447 | line in a file (make each code with `t3 pair` on that machine) and run |
| 448 | `t3 environment link --from <file> --access <mode>`, or `--from -` to read |
| 449 | standard input. It prints a result per line, leaves machines already linked as |
| 450 | they are, and exits non-zero if any line failed, so the same file can be run |
| 451 | again with fresh codes for the failures. |
| 452 | |
| 453 | You can also ask an agent to link a machine by name, such as "delegate this to |
| 454 | my vps". It shows a card in the thread where you pick the machine the same way |
| 455 | and the access, then approve. An address the agent gives that this app does |
| 456 | not know for one of your machines also needs a pasted code. Paste one only for |
| 457 | an address you trust: the code is sent there. |
| 458 | |
| 459 | - The access you pick is the most agents from this machine may do there. An |
| 460 | agent also never gets more there than its own mode here. |
| 461 | - Threads a link starts are marked **From** and this machine's name there. |
| 462 | - A full-access link works there like that machine's own agents. Below full |
| 463 | access, the link's agents can change only threads it started, not that |
| 464 | machine's own threads, projects or settings, and they skip its project setup |
| 465 | scripts. |
| 466 | - The link shows up in that machine's **Settings → Sharing & access** like any |
| 467 | outside agent. Revoke it there to end it. **Forget** on this machine only |
| 468 | removes it here. |
| 469 | - A link stays valid while agents use it. One unused for 30 days expires, as |
| 470 | does one to a machine on an older T3 Code after 30 days; link again with a |
| 471 | new pairing code. |
| 472 | |
| 473 | On web and desktop, **Settings → Environments** opens as a map of your machines: |
| 474 | this app, each environment with one line per route (the one in use is |
| 475 | highlighted), and the machines an environment links to. Select a machine to |
| 476 | manage it, or switch to **List** for the same controls as rows. To link from |
| 477 | the map, drag the plus on an environment onto another machine, or press it and |
| 478 | pick one. If this app is connected to both machines, knows an address the first |
| 479 | can reach the other at, and its session on the other one manages access there, |
| 480 | it needs no pairing code. |
| 481 | |
| 482 | A link goes one way. To let the other machine's agents work back, tick **Also |
| 483 | link … back** when you create the link, or select a one-way link and use |
| 484 | **Link back…**. It is offered when this app is connected to both machines and |
| 485 | may manage access on each. Two machines linked to each other at the same access |
| 486 | are drawn as one line with an arrowhead at each end; they are still two links, |
| 487 | and each is forgotten on its own. |
| 488 | |
| 489 | To link one environment to several machines at once, Shift-click the machines |
| 490 | (or Shift-drag a box around them, or press Space on a focused machine), then |
| 491 | drag the environment's plus onto any of them, or use **Link several…** above |
| 492 | the map. Dropping the plus on a stack offers the stack's machines. The dialog |
| 493 | ticks the machines it can link without a pairing code and says why for the |
| 494 | rest. When this app is connected to none of them, each needs a pairing code, |
| 495 | so the map says so and offers to link one at a time instead. |
| 496 | |
| 497 | Large setups fold: machines known only through links that share the same |
| 498 | linking environments and access levels become one stack, and once this app |
| 499 | knows more than 12 environments, the ones that are not connected and have no |
| 500 | links fold by state. Select a stack to list and filter every machine in it. |
| 501 | Opening a stack on the map draws its first 24 below its card: the rest of the |
| 502 | map stays where it is and the map grows taller, so pan or press the fit button |
| 503 | to see all of it. **Find a machine** above the map searches by name, and Enter |
| 504 | goes to the first match. The **?** button above the map lists these gestures. |
| 505 | |
| 506 | The map draws the links of the machines this app is connected to; a machine it |
| 507 | is not connected to may hold links the map cannot show. A link reaches one |
| 508 | machine and does not carry on through that machine's own links. |
| 509 | |
| 510 | An agent can also hand a task to a linked machine with `delegate_task`: it runs |
| 511 | there as an ordinary thread, in the project with the same repository (or the |
| 512 | one `target.projectId` names), and this thread wakes with its result when it |
| 513 | ends, as for any delegated task. It keeps following the task across restarts. |
| 514 | If the other machine revokes the link, or the link is removed here, the task |
| 515 | fails with that reason. |
| 516 | |
| 517 | ### Read a linked machine's threads |
| 518 | |
| 519 | You can read a thread on a linked machine without connecting this app to it. Open |
| 520 | a task that was delegated there from the thread's agents, or a thread link that |
| 521 | points there, and the thread opens read-only, streamed through the machine you |
| 522 | are connected to over its link. It follows the thread live. On web and desktop |
| 523 | it opens as a tab in the right panel, beside the thread you are in, or in the |
| 524 | main view with ⌘/Ctrl-click, like |
| 525 | [subagents and side chats](thread-sidebar.md#open-a-thread-beside-the-one-you-are-in). |
| 526 | On mobile it opens in the inspector on layouts that have one, where Maximize |
| 527 | fills the screen, and as its own screen elsewhere. It shows the same timeline as |
| 528 | any other thread on web and desktop, and a shorter read-only list on mobile. |
| 529 | |
| 530 | - The view is marked **Read-only** with both machines' names. To reply, approve |
| 531 | or stop the thread, choose **Connect to interact**. When the link has full |
| 532 | access, this app pairs with that machine in one step and opens the thread |
| 533 | there; you need permission to manage access on the machine you are connected |
| 534 | to. Otherwise the add-environment form opens for that machine and asks for a |
| 535 | pairing code you create on it. |
| 536 | - This app connects to that machine directly, so it must be able to reach one of |
| 537 | the addresses the link uses. If it cannot, the view says so and stays |
| 538 | read-only. The new connection appears in that machine's **Settings → Sharing & |
| 539 | access**, named after this device and the machine it came through, and is |
| 540 | revoked there like any other. |
| 541 | - Files, images and published visuals stay on that machine and do not load |
| 542 | here. A command's output shows as of when you open its row. |
| 543 | - If this app is already connected to that machine, the thread opens there as |
| 544 | usual instead. |
| 545 | - You need permission to read threads on the machine you are connected to, and |
| 546 | Linked environments must be on there. Both machines need a version of T3 Code |
| 547 | that has this view. |
| 548 | |
| 549 | ## Manage or revoke access |
| 550 | |
| 551 | On the host, **Settings → Sharing & access** lets authorized administrators create |
| 552 | pairing links and revoke client sessions. Revoking an unused link prevents new |
| 553 | pairings; revoke a device's session to remove its existing access. Command-line |
| 554 | management is available through `t3 auth --help`. |
| 555 | |
| 556 | When the app connects to more than one environment, choose one at the top of the |
| 557 | page. A desktop app with **Local environment** off can manage a background |
| 558 | service on the same machine this way, including its T3 Connect link. |
| 559 | |
| 560 | A session with an open connection stays listed after its access credential |
| 561 | expires. |
| 562 | |
| 563 | To choose a token's permissions, pass `--scope` once for each scope you want: |
| 564 | |
| 565 | ```sh |
| 566 | t3 pair --scope orchestration:read --scope relay:read |
| 567 | ``` |
| 568 | |
| 569 | The selected scopes replace the default permissions. The same option works with |
| 570 | `t3 auth pairing create` and `t3 auth session issue`; each command's |
| 571 | `--help` lists the available scopes. Without `--scope`, pairing tokens and issued |
| 572 | bearer sessions get the standard client permissions, including managing access. |
| 573 | Setting up or replacing a T3 Connect link requires the separate `relay:configure` permission. |
| 574 | A terminal or a full-access agent on the host can reach those as well, so a |
| 575 | client that should not manage access also needs to go without `terminal:operate` |
| 576 | and `orchestration:operate`. |
| 577 | |
| 578 | To change an existing client's permissions, create a fresh pairing link with the |
| 579 | scopes it needs. In a browser opened directly on the environment, open that link |
| 580 | to replace the browser's current grant. For mobile or a saved remote environment |
| 581 | in web or desktop, use **Add Environment** with the fresh link or code; pairing |
| 582 | the same environment replaces its saved grant. Reconnecting alone does not change |
| 583 | permissions. |
| 584 | |
| 585 | Grouping checkouts does not combine their permissions. Shared project settings |
| 586 | require `orchestration:operate` on every member environment; actions on one |
| 587 | checkout use that checkout's permissions. |
| 588 | |
| 589 | `source-control:write` covers direct Git and pull request changes made from the |
| 590 | client: pushing, switching or creating branches, cloning, and removing |
| 591 | worktrees. It does not restrict what a task does. Starting a task in a new |
| 592 | worktree still creates that branch and worktree with `orchestration:operate`, |
| 593 | and the agent it runs can use Git however the environment allows. |
| 594 | |
| 595 | Settings changes, provider management, environment maintenance, access |
| 596 | management, and T3 Connect preferences can each be granted separately. Setting |
| 597 | up or replacing a T3 Connect link requires the administrative |
| 598 | `relay:configure` permission. `relay:write` covers preferences and unlinking. |
| 599 | New pairings without `--scope` include the standard client permissions. Existing clients keep the |
| 600 | permissions they paired with and can stay connected after an update, but newly |
| 601 | separated features may require pairing again with the permissions they need. |
| 602 | Older clients may show controls that the server denies. Create a fresh pairing |
| 603 | link to change a client's permissions. |
| 604 | |
| 605 | `filesystem:read` allows browsing host files, opening workspace files, and viewing |
| 606 | local changes. Add `filesystem:write` to allow editing files or saving plans to |
| 607 | the workspace. These scopes control direct file access from the client. |
| 608 | |
| 609 | Some permissions also give a client indirect access. With `terminal:operate`, |
| 610 | a client can run commands that read or change any files the server’s OS account |
| 611 | can access, even when the pairing link omits file permissions. With |
| 612 | `relay:configure`, a client can replace the trusted issuer of pairing |
| 613 | credentials. Grant these permissions only to clients you trust with those |
| 614 | capabilities. |
| 615 | |
| 616 | To remove an environment from T3 Connect, open your account menu's **T3 Connect** |
| 617 | page, or **Settings → T3 Connect** on mobile, and choose **Deregister**. This |
| 618 | revokes its cloud access and frees its host space even when the environment is |
| 619 | offline or has been wiped. When T3 Connect rejects a host's link, the host |
| 620 | shows that it was removed from T3 Connect. To link it again, turn on |
| 621 | **T3 Connect** in **Settings → Sharing & access** on web or desktop, or turn on |
| 622 | **Live Activity Updates** in **Settings → Notifications** on mobile; if it is |
| 623 | already on, turn it off and on again. Either needs a client paired with |
| 624 | `relay:read`, `relay:write`, and `relay:configure`. The desktop app's own session |
| 625 | and the startup pairing link include all three; a pairing link created in |
| 626 | **Settings → Sharing & access** needs `relay:configure` selected. You can also |
| 627 | run `t3 connect link` on the host and then restart T3 Code there. A |
| 628 | command-line host that released its tunnel when it last stopped may link itself |
| 629 | again on its next start; run `t3 connect unlink` on that host to keep it off. |
| 630 | Removing an environment from a device's connection settings only forgets it on |
| 631 | that device and doesn't change your T3 Connect account. A device keeps a saved |
| 632 | environment after it's deregistered until you remove it from that device. |
| 633 | |
| 634 | When idle tunnel cleanup is enabled, T3 Connect removes a linked environment's |
| 635 | tunnel after it stays offline for several minutes. The environment stays linked |
| 636 | and keeps the same address. When the host starts again or wakes, T3 Connect |
| 637 | creates a replacement tunnel on its own. You do not need to pair again. Cleanup |
| 638 | usually runs five to ten minutes after the tunnel goes down. |
| 639 | |
| 640 | T3 Connect also removes the tunnel of an environment running an older version of |
| 641 | T3 Code once it has been offline for seven days. That environment shows a message |
| 642 | asking you to update. Start T3 Code on that computer and update it to the latest |
| 643 | version; it reconnects at the same address without pairing again. |
| 644 | |
| 645 | On a command-line host, `t3 connect unlink` disables exposure while retaining |
| 646 | your login; `t3 connect logout` also clears that login. Background-service |
| 647 | [removal](./background-service.md#manage-the-service) is separate. |
| 648 | |
| 649 | Treat pairing URLs and authorization codes as passwords. Do not include them in |
| 650 | screenshots, logs, or bug reports. |
| 651 | |
| 652 | ## T3 Connect troubleshooting |
| 653 | |
| 654 | When a T3 Connect connection fails, see |
| 655 | [T3 Connect troubleshooting](./t3-connect-troubleshooting.md). It explains each |
| 656 | error, where the problem is, and how to fix it. |
| 657 | |
| 658 | ## Using the Desktop App as a Remote Only |
| 659 | |
| 660 | If a computer should only drive work running elsewhere, turn off its local environment. In the |
| 661 | desktop app, open **Settings → Environments** and switch off **Local |
| 662 | environment**. T3 Code restarts without a local server: no local agents or terminals run, WSL |
| 663 | backends stay off, and other devices can no longer connect to this computer. Your projects, |
| 664 | history, and saved connections are kept, and you keep working through pairing, T3 Connect, or SSH. |
| 665 | If a [background service](./background-service.md) on this computer uses the same T3 home, the |
| 666 | app still treats it as this computer: **Open in** and file reveal for its projects run here, |
| 667 | whichever connection you reach it through. |
| 668 | |
| 669 | Switch **Local environment** back on in the same place to restart with your previous local |
| 670 | settings. |