@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 238 lines 14.8 KB
Rendered Raw
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.