feat(desktop): attach to a running local backend#8115

closed6

main

GitHub fork: fix/desktop-attach-running-backend

openedAug 24, 2026byPPedro-Revez-Silva

View on GitHubTwo-way sync enabledPR last imported 21d ago

What Changed

Packaged Desktop now discovers a live same-machine background service or t3 serve runtime and attaches to it instead of starting a second backend. The attachment uses a process-scoped grant to establish an administrative Desktop session while continuing to serve the renderer bundled with the installed app.

Desktop development remains isolated. Settings → Connections exposes an opt-out, reports the attached state, and leaves network-exposure controls with the server that owns them.

Attached backends are rediscovered after a restart or port change. Transient failures are retried silently; persistent secure-pairing failures offer Try Again, Start Separate Backend, Open in Browser, or Quit. Starting separately uses isolated state for that launch.

The background-service user documentation now covers Desktop attachment, ownership, recovery, and the escape hatch.

Why

A headless T3 Code server can be the durable environment used from web and mobile, but opening Desktop on the same machine currently creates a separate environment with different threads and settings. Desktop should be able to act as another client for the existing local environment without weakening development isolation or silently falling back when secure attachment fails.

Starting-point proposal: https://github.com/pingdotgg/t3code/discussions/8114

UI Changes

Before

Desktop manages its own backend, so Connections begins with its network controls and has no running-server attachment state.

After

Desktop is attached to the disposable local server. The page shows the attachment control and makes network exposure read-only because the external server owns it.

Service restart recovery

The attached server stops, Desktop retries and reloads its bundled renderer, and the same thread returns automatically without a decision dialog.

https://github.com/user-attachments/assets/9ffe624e-93ca-48bf-b432-3c5f8dc024fb

Verification

Focused Desktop tests: 618 passed
Focused server tests: 55 passed
Focused web tests: 16 passed
Typechecks passed for Desktop, server, web, contracts, and shared
Targeted lint, formatting, and git diff --check passed
Production Desktop build passed
Packaged Desktop manually verified against a disposable background server: secure attachment, retained thread state, restart rediscovery, silent retry, automatic recovery, and persistent-failure UX

Checklist

This PR is small and focused
I explained what changed and why
I included before/after screenshots for any UI changes
I included a video for animation/interaction changes

Implemented and reviewed with GPT-5.6 through the Codex harness in T3 Code.

Note

High Risk Changes desktop startup, OAuth pairing, and server auth grants for local attachment; mis-handling could spawn duplicate backends or fail secure reconnection in production.

Overview Packaged Desktop can attach to an already-running local T3 Code server (background service or t3 serve) instead of always spawning its own backend, so the same environment can be used from Desktop without a duplicate process.

Discovery reads server-runtime.json (and systemd/launchd T3CODE_HOME hints), validates the server via /.well-known/t3/environment, and pairs with a new per-process desktopAttachToken exchanged for a bearer session. The server seeds that token in PairingGrantStore and persists it in runtime state; Desktop uses manageProcess: false with HTTP health watching, invalidates stale attachments on loss, and can reload the bundled renderer (local protocol handler) while API traffic goes to the attached origin. Development never auto-attaches; a new attachExistingLocalBackend setting (default on) plus IPC exposes attachment state and relaunches on toggle.

Bootstrap and runtime recovery add dialogs: retry pairing, start a separate backend (isolated desktop-independent home + port scan via extracted DesktopBackendPort), open in browser, or quit. The backend pool retries pairing silently before offering “start separate” on persistent failures.

^{Reviewed by Cursor Bugbot for commit ed06cc25898e4726462b77ee80f76539c6cfaa6b. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Add Desktop app support for attaching to a running local backend

Desktop boot discovers an existing local backend (systemd/launchd) and pairs with it using a desktopAttachToken, avoiding a second server spawn
New IPC channels getExistingLocalBackendState and setAttachExistingLocalBackend let the renderer query and toggle attachment; toggling relaunches the app
DesktopBackendManager gains an attached-runner mode (manageProcess: false) with health probes every 2s and callbacks for configuration failure and unexpected shutdown
Connections settings page renders an 'Attach to running server' switch; effective auth scopes stay administrative until an attached session resolves
ElectronProtocol serves the bundled renderer locally when rendererRoot is set, with MIME types, CSP, and path-traversal protection, instead of proxying from the attached server
PairingGrantStore seeds a reusable admin grant (100-year TTL) from the configured desktopAttachToken; server runtime state is persisted with file mode 0600
Auth layer (DesktopLocalEnvironmentAuth, desktopAuth) caches bearer tokens keyed by URL + token + authSessionKey and reuses the attached token without a bootstrap exchange
Recovery dialogs on pairing failure offer retry, start separate backend, open in browser, or quit; after 4 auto-retry attempts on ExistingLocalBackendPairingError the pool prompts the user
Risk: new DesktopBackendConfiguration interface members (resolveExistingLocalBackend, invalidateExistingLocalBackendAttachment, useIndependentBackendForLaunch) require all implementations and test mocks to provide them; DesktopSettings defaults attachExistingLocalBackend to true, so existing users without the key will begin attaching on next launch

^{Macroscope summarized ed06cc2.}

Added 2 commitsAug 24, 2026

fix(desktop): attach to a running local backenda851c5c
fix(desktop): recover attached backends safelyff0be38

CcoderabbitaiBotAug 24, 2026

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: 9349159a-765e-4c5d-9284-813da4a94da7

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

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

MmacroscopeappBotreviewed · 3 inline threadsAug 24, 2026

Reviewed the new attach-to-running-backend Effect code against the service conventions. Three violations in the changed scope: a wrapped failure that loses its cause and rebuilds its message from cause.message, and two Effect.catchTag uses that should be Effect.catchTags. Dependency passing (fileSystem/path/httpClient in input objects) matches the established pattern in this package, so it is not flagged.

^{Posted via Macroscope — Effect Service Conventions}

apps/desktop/src/backend/DesktopBackendManager.tslines 495–497Outdated · ff0be38Open thread

…	…	@@ -432,9 +455,62 @@ const decodeDesktopTelemetryControlLine = Schema.decodeUnknownEffect(
	494	+	Effect.as(true),
	495	+	Effect.catchTag("BackendReadinessTimeoutError", (error) =>
	496	+	(options.onReadinessFailure?.(error) ?? Effect.void).pipe(Effect.as(false)),
	497	+	),

MmacroscopeappBoton lines 495–497Aug 24, 2026

backend/DesktopBackendManager.ts:497

Same tag is handled with Effect.catchTags a few lines above (line 473); this occurrence should use Effect.catchTags too rather than Effect.catchTag.

suggestion

1	Effect.catchTags({
2	BackendReadinessTimeoutError: (error) =>
3	(options.onReadinessFailure?.(error) ?? Effect.void).pipe(Effect.as(false)),
4	}),

No longer relevant as of 7bb191346942687efdb672729d62478bb64fe6d0

PPedro-Revez-SilvaAug 24, 2026

Fixed in 7bb191346 by using Effect.catchTags for the readiness timeout.

…	…	@@ -651,6 +742,125 @@ export const make = Effect.gen(function* () {
	819	+	Effect.map((value) => ({ _tag: "Success", value }) as const),
	820	+	Effect.catchTag("ExistingLocalBackendPairingError", (error) =>
	821	+	Effect.succeed({ _tag: "Failure", error } as const),
	822	+	),

1	Effect.catchTags({
2	ExistingLocalBackendPairingError: (error) =>
3	Effect.succeed({ _tag: "Failure", error } as const),
4	}),

…	…	@@ -0,0 +1,346 @@
	333	+	new ExistingLocalBackendPairingError({
	334	+	baseDir: input.backend.baseDir,
	335	+	origin: input.backend.origin,
	336	+	detail: cause instanceof Error ? cause.message : "The server rejected the connection.",

…	…	@@ -1,4 +1,15 @@
	8	+	const primary = window.desktopBridge
	9	+	?.getLocalEnvironmentBootstraps?.()
	10	+	.find((entry) => entry.id === PRIMARY_LOCAL_ENVIRONMENT_ID);
	11	+	return [primary?.httpBaseUrl ?? "", primary?.bootstrapToken ?? ""].join("\u0000");