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
| 1 | # Remote architecture |
| 2 | |
| 3 | Each connection joins a client to one environment over HTTP and WebSocket. The |
| 4 | environment owns providers, execution, files, and durable state. Direct access, |
| 5 | Tailscale, SSH, and T3 Connect change how the client reaches that server; they do |
| 6 | not introduce another execution model. See |
| 7 | [remote access](../user/remote-access.md) for setup. |
| 8 | |
| 9 | ## Identity is independent of the route |
| 10 | |
| 11 | An environment keeps its ID across server restarts and endpoint changes. Saved |
| 12 | connections are local to a client profile; the server's identity and state are |
| 13 | not. A repository identity can correlate clones across environments, but never |
| 14 | routes work between them. A project and its threads belong to one environment; |
| 15 | an agent reaches another environment's threads only through a peer link. |
| 16 | The canonical key follows the `upstream` remote when one exists, so pull request |
| 17 | features target the repository a fork tracks. A fork also reports its own |
| 18 | `origin`, and clients group and label by that, so a fork never collapses into a |
| 19 | checkout of its upstream. |
| 20 | |
| 21 | [Environment ID initialization](../../apps/server/src/environment/ServerEnvironment.ts) |
| 22 | must publish a complete ID atomically. Repair of an empty ID file retains a |
| 23 | recovery file so concurrent or delayed initializers choose the same winner. |
| 24 | Removing that recovery state as ordinary temporary-file cleanup can change the |
| 25 | identity underneath an already-running server. |
| 26 | |
| 27 | Advertised endpoints are reachability hints. Only the connecting device can |
| 28 | prove that a route works. In particular, a host's loopback address refers to a |
| 29 | different machine when another device opens it. Endpoint selection must not |
| 30 | silently fall back to loopback when a shareable endpoint is unavailable. |
| 31 | |
| 32 | A saved environment holds an ordered list of routes, and the |
| 33 | [driver](../../packages/client-runtime/src/connection/driver.ts) connects over |
| 34 | the first that works. Each direct route is first checked with the public |
| 35 | descriptor, so a saved LAN address that a different machine answers on another |
| 36 | network receives no credential. That check is not proof of a working route: |
| 37 | when every route stays silent, each is still tried. A route that fails to |
| 38 | connect, including a blocked one such as a signed-out T3 Connect, moves on to |
| 39 | the next; only an incompatible server stops the walk, because it is the same |
| 40 | server on every route. While connected over a later route the |
| 41 | [supervisor](../../packages/client-runtime/src/connection/supervisor.ts) |
| 42 | preflights the earlier ones and replaces the session when one would connect. |
| 43 | Preflight includes authorization so a route that answers but rejects this |
| 44 | client never costs a working session; a route that still fails afterwards is |
| 45 | held back for a cooldown so a flaky network cannot bounce the connection. |
| 46 | |
| 47 | A connected server reports the LAN and tailnet addresses it is bound to, and the |
| 48 | client saves them as learned routes. A learned route reuses the credential of |
| 49 | the route it was learned over: the T3 Connect access token, which is not bound |
| 50 | to an origin because each DPoP proof names the URL it signs, or the paired |
| 51 | bearer token. A paired token only learns a plain HTTP address off the tailnet |
| 52 | when it was itself paired over plain HTTP, so a token paired over HTTPS never |
| 53 | starts travelling unencrypted. Learned routes the server stops reporting are |
| 54 | dropped, which is how a changed LAN address replaces the old one; routes the |
| 55 | user saved are never touched. The reported addresses are hints like any advertised endpoint, so a |
| 56 | learned route still has to answer as this environment before it is used. |
| 57 | |
| 58 | A background service with no configured host is what makes this work for |
| 59 | headless machines. It listens on every IPv4 interface and closes each |
| 60 | connection unless both addresses of the direct peer are loopback, private, or |
| 61 | tailnet IPv4. That keeps a VPS's public address closed, including a cloud VM |
| 62 | whose public address is NATed to a private interface. It is not a firewall: |
| 63 | T3 Connect and Tailscale Serve reach the server over loopback by design, and a |
| 64 | proxy that rewrites the source address looks private. One listener per address would |
| 65 | miss a DHCP change, and the wildcard keeps the reported addresses current. |
| 66 | |
| 67 | Pull request routing trust covers the whole route list. Adding or changing a route |
| 68 | revokes it; reordering does not, because the same addresses remain trusted. |
| 69 | |
| 70 | ## Peer links |
| 71 | |
| 72 | A [peer link](../../apps/server/src/peer/PeerLinks.ts) lets one environment's |
| 73 | agents work in another. The linking environment signs in to the other's `/mcp` |
| 74 | as an outside MCP client, with a pairing code from it, and keeps that session's |
| 75 | token in its own secret store. The other environment needs nothing new: it |
| 76 | sees one more OAuth client, lists it in Sharing & access, and revokes it there. |
| 77 | Unlinking on the linking side only forgets the token. |
| 78 | |
| 79 | - **The Linked environments beta (`linkedEnvironmentsEnabled`) gates both |
| 80 | sides.** Off on the linking side, `PeerLinks.link`, link requests and |
| 81 | `PeerForwarding.call`/`links` refuse; `readThread`, `waitForThread` and |
| 82 | `interruptThread` do not, so a remote task already running still completes |
| 83 | and can still be cancelled. Off on the receiving side, link registrations are |
| 84 | refused and link sessions get a 403, which the linking side reports as |
| 85 | retryable so the task's follower waits rather than failing it. |
| 86 | - **A tool runs in a linked environment when its parameters take |
| 87 | `OrchestratorMcpEnvironmentTarget`** as `environmentId`. |
| 88 | [`McpToolAccess.toLayer`](../../apps/server/src/mcp/McpToolAccess.ts) sends |
| 89 | such a call there once the tool's access declaration has checked the caller, |
| 90 | so a read-only or ended caller is refused before anything is sent. The |
| 91 | thread or project the call names is checked where it lives. A tool that acts |
| 92 | as the calling thread itself cannot take a linked environment. |
| 93 | - **Every forwarded call carries the calling agent's modes** in |
| 94 | `T3-Mode-Limit`, which the receiving `/mcp` only ever narrows the client's |
| 95 | approved access with. A plan-mode agent therefore cannot start full-access |
| 96 | work through a full-access link. |
| 97 | - **A descriptor's environment id filters addresses; it does not prove |
| 98 | identity.** The token goes only to an address that reports the linked id, so |
| 99 | a LAN address that now reports another machine's never receives it. Anything can |
| 100 | report any id, though, so only addresses from the user's client count as a |
| 101 | machine's, and never a loopback one, which names whichever machine opens |
| 102 | it. An address an agent gives is recorded alone, and |
| 103 | [`linkRequestTarget`](../../packages/client-runtime/src/linkRequest.ts) names |
| 104 | a machine for it only when the client already reaches exactly one machine |
| 105 | there. An address alone never moves an unexpired link to another address. |
| 106 | - **The receiving side owns a link's expiry.** It renews the session when the |
| 107 | link is used and answers each call with `T3-Link-Expires-At`; the linking |
| 108 | side stores that and never extends a link on its own. A receiving side that |
| 109 | predates renewal sends no header, so the link keeps its original 30 days on |
| 110 | both sides. |
| 111 | - **All callers on one side share the link's single session on the other**, |
| 112 | so idempotency keys are hashed with the caller's namespace before they |
| 113 | leave. Without that, two agents reusing a key would collide on the far side. |
| 114 | - **A forwarded wait is split into calls of at most 50 s**, because the |
| 115 | receiving `/mcp` sends nothing while a wait is open and T3 Connect's edge |
| 116 | drops idle requests after about 100 s. |
| 117 | |
| 118 | **A client reads a linked thread as the thread's own stream.** A client connected |
| 119 | only to the linking environment subscribes to `peerLinks.subscribeThread`; |
| 120 | [`PeerThreadRelay`](../../apps/server/src/peer/PeerThreadRelay.ts) opens the |
| 121 | receiving environment's |
| 122 | [link thread routes](../../apps/server/src/peer/linkThreadHttp.ts) with the |
| 123 | link's token and passes on the same stream items, history pages and item detail |
| 124 | the owner's client gets. Clients reduce and draw it like any thread, read-only, |
| 125 | so there is no second transcript format to keep in step. The relay holds one |
| 126 | upstream per subscription and nothing once the client stops listening. The |
| 127 | routes accept only a peer link's session, refuse browser origins as `/mcp` does, |
| 128 | and serve any access level, since each already reads threads through `/mcp`. |
| 129 | |
| 130 | **Work a link paired below full access starts stays within that link.** The |
| 131 | receiving environment knows a session is a peer link because the linking side |
| 132 | registers its OAuth client with the `t3code-peer-link` software id, and the |
| 133 | marker is signed into the session. Threads that session launches carry it, with |
| 134 | the access it was paired with, as an immutable `linkOrigin`, and so do the |
| 135 | subagents, forks and `create_threads` they derive. The rules live in |
| 136 | [`mcp/linkOrigin.ts`](../../apps/server/src/mcp/linkOrigin.ts) and run in the |
| 137 | shared access declarations, not tool by tool: |
| 138 | |
| 139 | - linked work may change only threads with the same origin, not the user's own |
| 140 | threads and not another link's; |
| 141 | - it cannot change projects, settings or scheduled tasks, nor use the receiving |
| 142 | environment's own links; |
| 143 | - its project setup scripts are skipped |
| 144 | ([`ProjectSetupScriptRunner`](../../apps/server/src/project/ProjectSetupScriptRunner.ts) |
| 145 | checks every path that runs them). |
| 146 | |
| 147 | Reads are not fenced, and a client's own `thread.create` can never carry |
| 148 | `linkOrigin`. |
| 149 | |
| 150 | **A delegated task can run in a linked environment.** Its child is then an |
| 151 | ordinary thread there, so the parent here records the task without a child |
| 152 | thread of its own (`remoteChild` instead of `childThreadId`). A follower in |
| 153 | [`RemoteDelegation`](../../apps/server/src/peer/RemoteDelegation.ts) waits on |
| 154 | that thread and completes the task with `delegated_task.remote.complete`. That |
| 155 | internal command reuses the parent half of a local finalize, so the parent |
| 156 | wakes the same way. Open remote tasks are followed again at startup, which is |
| 157 | also what keeps restart recovery from treating them as abandoned provider work. |
| 158 | |
| 159 | The link is routing, not isolation: an agent the link starts runs as the |
| 160 | receiving environment's user. **A full-access link is therefore not fenced**: |
| 161 | its agents can already do anything that user can, so the fence would only stop |
| 162 | T3's own tools. Its work still carries `linkOrigin`, so clients show where it |
| 163 | came from. A stamp without the access, from before it was recorded, is fenced. |
| 164 | |
| 165 | ## Hosted web is a client |
| 166 | |
| 167 | The hosted web app stores its connection catalog in the browser and connects |
| 168 | directly to each environment. It does not proxy traffic or hold server-side |
| 169 | pairing state. Hosting the UI over HTTPS therefore cannot make a plain HTTP LAN |
| 170 | backend accessible from that browser context. |
| 171 | |
| 172 | A [hosted pairing URL](../../apps/web/src/hostedPairing.ts) identifies the backend |
| 173 | in its query and carries the pairing secret in its fragment. Fragments stay out |
| 174 | of requests to the hosted origin. The browser exchanges the secret with the |
| 175 | environment and strips it from its history. Moving the token into a query |
| 176 | parameter would disclose it to the wrong origin. |
| 177 | |
| 178 | ## Desktop previews tunnel loopback |
| 179 | |
| 180 | A desktop webview for another environment keeps `localhost` URLs and reaches the environment's |
| 181 | loopback through `/api/preview/tunnel`, one WebSocket per TCP connection, on the same origin as |
| 182 | every other request. That is why it works over any connection method. Four choices are easy to |
| 183 | undo by accident: |
| 184 | |
| 185 | - **Fixed proxy, not PAC.** Chromium never consults a PAC script for loopback hosts, even with |
| 186 | `<-loopback>`. The partition uses a fixed SOCKS5 proxy with the bypass list |
| 187 | `*,<-loopback>,169.254.0.0/16,fe80::/10`, in that order, since the last matching rule wins: |
| 188 | everything is direct except loopback. `<-loopback>` also takes link-local addresses, so the last |
| 189 | two rules hand them back to the direct route. A fixed proxy also has no |
| 190 | direct retry, so a failed tunnel is a connection error and never the reviewer's own localhost. |
| 191 | The rule matches hostnames, not resolved addresses, so a custom name that resolves to loopback |
| 192 | still goes direct. |
| 193 | - **Media tickets.** Desktop main opens the tunnel but holds no environment credentials. Media |
| 194 | tickets are not DPoP-bound, so the renderer can hand one over. Main asks it for a tunnel URL per |
| 195 | connection, which also makes the tunnel follow a route switch. |
| 196 | - **Owner check, not auth.** Chromium can't authenticate to a SOCKS proxy, so any local process |
| 197 | can connect to the listener and ride this user's tunnel. On Linux the listener looks the client |
| 198 | up in `/proc/net/tcp` and refuses other users. macOS and Windows have no such check yet. The |
| 199 | mobile app's device preview has the same listener while it is open: iOS suspends other apps, but |
| 200 | Android lets any app reach it, and apps cannot see another app's socket owner there. |
| 201 | - **Off stays routed.** `allowsPreviewTunnel` (setting plus policy) gates the route and, from |
| 202 | server config, the clients, which then stream. The partition keeps its tunnel proxy anyway, so a |
| 203 | desktop tab left open fails instead of loading the reviewer's own localhost. |
| 204 | - **System browser links** have no tunnel. They keep the private-network rewrite in |
| 205 | [`browserTargetResolver.ts`](../../apps/web/src/browser/browserTargetResolver.ts). |
| 206 | |
| 207 | ## Access and process ownership are different |
| 208 | |
| 209 | Tailscale supplies an endpoint for ordinary pairing, so it needs no separate |
| 210 | environment type. Authentication remains the environment's responsibility for |
| 211 | every route. See [environment authentication](./environment-auth.md) and the |
| 212 | [T3 Connect trust boundary](./t3-connect.md). |
| 213 | |
| 214 | SSH can launch a server as well as forward a port. Desktop main owns that |
| 215 | lifecycle because it can spawn SSH and handle authentication prompts. The |
| 216 | renderer uses the forwarded endpoint through the shared connection runtime. |
| 217 | [SSH cleanup](../../packages/ssh/src/tunnel.ts) stops a remote server only if the |
| 218 | launcher owns it; a server it discovered already running must survive a client |
| 219 | disconnect. Reconnection restores the forward before opening the application |
| 220 | transport. |
| 221 | |
| 222 | Remote servers can outlive several client releases. Clients must use advertised |
| 223 | capabilities and handle their absence, rather than assume their own version |
| 224 | describes the server. Process replacement belongs to the launcher's |
| 225 | [update protocol](./server-updates.md); the connection runtime handles the |
| 226 | resulting disconnect. |
| 227 | |
| 228 | ### Desktop without a local environment |
| 229 | |
| 230 | Desktop normally launches its own primary server, but the desktop setting `localEnvironmentEnabled` |
| 231 | (`apps/desktop/src/settings/DesktopAppSettings.ts`) turns that off. Changing it relaunches the app; |
| 232 | no local state is deleted. On the next start the main process skips port selection, server exposure, |
| 233 | and the primary and WSL backends, and opens the window right away. The renderer sees this through |
| 234 | `desktopBridge.getLocalEnvironmentEnabled()`: `readPrimaryEnvironmentTarget` returns null, so primary |
| 235 | auth and platform-managed discovery are skipped and only saved environments (pairing, relay, SSH) |
| 236 | connect. This is possible because the desktop renderer is not served by the backend: the `t3code://` |
| 237 | scheme serves the bundled client from disk (Vite in development) and API traffic always goes to the |
| 238 | environment's own URL. |