@devries-cameron20 / t3code Mirror · read-only
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 03:37 UTC

main
md 670 lines 35 KB
Rendered Raw
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.