feat(remote): support path-prefixed direct pairing

[HamedMP]

Problem

T3's direct remote-environment flow assumed that a server lived at the root of an origin. Matrix OS safely exposes a user's loopback T3 server below an owner-scoped path, so pairing URLs, OAuth/DPoP requests, assets, discovery, and WebSocket connections lost that prefix. The previous Matrix setup also sent users through T3 Connect, which required a T3 account and Clerk.

Solution

• add --pairing-base-url to t3 serve and t3 pair so a trusted reverse proxy can advertise its public URL
• accept only HTTP(S) public bases, normalize directory semantics, persist the running server's effective base, and reject mismatched t3 pair requests
• preserve path prefixes throughout environment resolution, OAuth, HTTP RPC, assets, and WebSocket setup
• verify both token exchange and authenticated-request DPoP proofs against the configured public URL instead of trusting forwarded headers
• emit a hosted app.t3.codes/pair?host=... link for externally hosted direct environments
• keep the Matrix OS setup entry points in desktop/web and mobile, now documented as direct pairing rather than T3 Connect discovery
• refresh and save the resulting environment through T3's normal pairing/session model; no Matrix-specific auth or transport is added

User story

The user selects Set up Matrix OS, approves setup in Matrix, then scans or pastes the one-time pairing link into the normal T3 desktop, web, or mobile client. The Matrix computer appears as a standard remote environment. No T3 Connect toggle, T3 account, Clerk session, managed relay, or forked T3 client is required.

Tests

• all 15 touched test files pass: 215 tests
• targeted typechecks pass for mobile, web, client-runtime, and shared
• server typecheck reaches one unrelated existing HttpResponseCompression.ts BodyInit error; no changed-file type errors remain
• targeted lint and changed-file formatting checks pass
• Macroscope correctness and Effect service-convention checks pass

Security notes

• --pairing-base-url is operator-owned CLI configuration, not derived from request headers
• the running server's public URL is persisted and must match later pairing requests
• T3 remains the authority for one-time pairing credentials, DPoP-bound access tokens, API scopes, and WebSocket tickets
• Matrix receives no T3 account token because this route does not use a T3 account

Rollout dependency

• Matrix OS PR: feat(integrations): pair T3 Code directly through Matrix HamedMP/matrix-os#1126
• Matrix currently pins a commit-specific preview package. Replace it with the first official T3 release containing this PR before the Matrix PR leaves preview.

Test plan

1. Start T3 behind a reverse proxy with a path-prefixed --pairing-base-url.
2. Open the emitted app.t3.codes/pair?host=... link in web/desktop or scan it on mobile.
3. Verify the environment is saved with its complete path prefix.
4. Open a project and verify OAuth/DPoP, HTTP RPC, assets, and WebSocket traffic use the prefixed URL.
5. Use Set up Matrix OS and verify the same direct flow works without T3 Connect sign-in.

Implemented with Codex desktop (GPT-5).

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 3cb0590d-0be5-4ef7-a909-42abdf010231

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[macroscopeapp]

One finding: a semantically distinct failure is being expressed by stuffing prose into a structured error attribute instead of its own error class. Everything else in the touched Effect code (namespace import of ServerConfig plus yield* ServerConfig.ServerConfig in EnvironmentAuth.make, pure-config threading of pairingBaseUrl into verifyRequestDpopProof, the new Schema.TaggedErrorClass with an attribute-derived message, no new Layer.succeed/ManagedRuntime/runPromise in service code) follows the conventions.

^{Posted via Macroscope — Effect Service Conventions}