[Feature] Use the Desktop app as a UI for an existing local T3 Code server

[Pedro-Revez-Silva]

Problem

T3 Code can run as a background service without the Desktop UI, which is useful for keeping one environment available to web and mobile clients. Opening the Desktop app on that same machine currently starts another backend instead of using the server that is already running.

That creates a second local environment with separate threads and connection settings. In my use case, the background server is the durable environment I reach remotely, while Desktop should be another client for that same environment.

Proposed behavior

For packaged Desktop launches:

• Detect a live T3 Code background service or local t3 serve process on the same machine.
• Attach securely to that server by default instead of starting a second backend.
• Keep Desktop development isolated from installed or production services.
• Continue serving the renderer bundled with the Desktop app, so its UI version is independent from the server bundle.
• Show the attached state in Settings → Connections, and leave network exposure controls with the process that owns the server.
• Let users disable attachment when they intentionally want an independent Desktop environment.

If a server is detected but secure pairing fails, Desktop should not silently start another backend. It should retry transient failures first, then offer Try Again, Start Separate Backend, Open in Browser, or Quit. The separate-backend option should use isolated state for that launch.

If an attached service restarts or changes port, Desktop should rediscover it and reconnect automatically before asking the user.

Why this shape

This keeps one machine represented by one durable T3 environment across desktop, web, and mobile while preserving an explicit escape hatch. Discovery remains local, authentication uses a short-lived process-scoped grant, development stays independent, and Desktop never takes lifecycle or network-exposure ownership away from an externally launched server.

I have a working implementation and will link the pull request here as a starting point for review.

[Pedro-Revez-Silva]

Starting implementation: #8115

[fu5ha]

This is now much more important since with #16102, the desktop app now errors and hard-quits when a service owns the home (intentionally, per #20250). It's also probably easier to implement, given #9194 already exists.

[Pedro-Revez-Silva]

This feature request should actually be irrelevant now because you can start conversations from the "don't work in a project" so it defeats the purpose of starting something from home

[fu5ha]

Eh? This feature doesn't have to do with where you start your project... At least not how I read it?

[Pedro-Revez-Silva]

Ops, sorry, I had the wrong feature request in mind.

This one is already implemented, currently my t3code connects to the local server and doesn't have it's own. It's in the settings.

[rubenmeza]

Same setup here (Linux, t3code-bin + a systemd user t3code.service with T3CODE_HOME=~/.t3, reached remotely over Tailscale) and the desktop app refuses to start with "this T3 home is unavailable".

Workaround that keeps the desktop's local environment (unlike disabling it per #9194, which loses "Open in editor" / "Reveal in file explorer"):

1. Give the desktop its own home so it does not contend for the service's lock:

   T3CODE_HOME=~/.t3-desktop t3code

   To make it stick, copy /usr/share/applications/t3code.desktop to ~/.local/share/applications/ and change the Exec= line to Exec=env T3CODE_HOME=/home/<user>/.t3-desktop t3code %U.
2. Mint a pairing token on the service and add it from the desktop as a remote environment:

   t3 auth pairing create --base-dir ~/.t3 --ttl 15m --base-url http://127.0.0.1:3773

   Use the printed /pair#token=... URL (or the token) in the desktop.

Caveat: the desktop then has two environments (its own local one and the service), so threads stay split across them, which is the gap this proposal would close. Posting in case it helps others hitting the error before this lands.

[iurii-provizio]

Another Linux data point, plus one gap I think is worth closing even before full auto-attach lands.

Use case: T3 on my dev workstation is my primary agent tool, and I want to reach it from the mobile app at any time, including when the desktop app is not open. So I installed the background service (t3 service install, systemd user unit, bound to the tailnet IP), which owns ~/.t3.

Result (desktop AppImage 0.1.0 + service 0.1.0, Ubuntu): the desktop app cannot start at all. On every launch its primary backend exits with ServerAlreadyRunningError (code 78), and the "This T3 home is unavailable" dialog quits the app.

The gap: the supported setup from #20250 (turn off Local environment per #9194, then add the service as an environment) is unreachable from that state. The toggle lives in Settings → Connections, but the app quits before any window opens. The only ways in are:

• stop the service, open the app, flip the toggle, start the service again; or
• hand-edit ~/.t3/userdata/desktop-settings.json to add "localEnvironmentEnabled": false.

So installing the service and then opening the desktop app leaves you with a desktop app that will not open and no in-app way out. With the manual edit, the app starts normally (bootstrap skipping local environment (disabled in settings)) and the service keeps serving mobile.

Smallest fix that would unblock this, short of the full proposal above: when onStateDirOwned fires and the owner is the local background service (server-runtime.json already records serviceManaged: true), offer Use the running service in that dialog: set localEnvironmentEnabled to false, relaunch, and open Add environment, ideally pre-paired since the desktop can read the same T3 home. Quit then becomes the fallback instead of the only option.

The remaining rough edge in that mode is Open in / Reveal taking the remote path for a same-machine service (#18515, #21661).

[JamesOBrien2]

Note

🤖 gpt-6.1-terra responding on behalf of James

When a background service already owns the T3 home, desktop users may expect to connect to it instead of having to work out why desktop cannot start its local environment. The single-owner lock is intentional; the maintainer-described workaround is to disable desktop's local environment and connect to the existing service as an environment.

Building on the smaller startup-recovery suggestion here, would maintainers prefer an explicit recovery action over full automatic attachment? What should establish that it is the right service, how should pairing and version mismatches work, and who owns startup, shutdown, and failures? The lock should remain authoritative. Could improving the ownership error be a separate first step?

Existing discussion: #8114. Background: #20250 (comment), #22820, and closed PR #26547. The PR requested prior approval of the automatic-attachment and lifecycle scope before a fresh submission.

[kvnloo]

Linux data point, plus a design sketch for how this could work.

Setup: CachyOS, t3code-nightly-bin desktop app, and a systemd user service on 0.1.7-nightly.20261102.4093 (t3 update --channel nightly). The service owns ~/.t3, and the desktop app exits with code 78 (ServerAlreadyRunningError). The only way out is the one described above: set localEnvironmentEnabled: false in desktop-settings.json while the app is closed, then pair.

Most of what's needed already exists:

• The single-owner lock (fix(server): enforce one database owner and guard update rollback #16102) decides which process hosts a T3 home.
• localEnvironmentEnabled (feat(desktop): allow disabling the local environment #9194) lets the desktop app run without its own server.
• The process that owns the lock already writes userdata/server-runtime.json with origin, serverVersion, serviceManaged, pid and ownerId. environment-id is in the same directory.

What's missing is a model where the desktop app is a client of whichever process hosts the T3 home. Here are the principles I'd build it on.

1. Hosting and UI are separate roles. Today the desktop app does two jobs. It's the UI: the renderer plus OS integration such as Open in, Reveal, notifications and capture. It's also the host: it owns the T3 home and runs agents. The lock already decides who hosts, so the desktop app shouldn't decide it a second time. When it finds that another process holds the lock, it should attach to that process, not show a dialog and quit.

2. Find the server through the lock owner's own record, not by probing ports. At startup, read server-runtime.json. If its owner holds the lock, attach to origin. If not, the file is stale and the desktop app can host. This also handles a service that restarts or changes ports. Exit 78 becomes one branch of startup, not a dead end.

3. Authenticate the same user through the filesystem. Anyone who can read ~/.t3/userdata already has the database and secrets. So a credential that only works over loopback, minted by the lock owner into a 0600 file, grants nothing new, and the same-machine pairing step goes away. Remote clients keep pairing as they do today.

4. Whether something is local depends on the machine, not on who started the server. If a connected environment's environment-id matches the one in the desktop app's own T3 home, that environment is on this machine. Then Open in, Reveal and cookie import work against the service too (#18515). The same check covers a browser on the same machine.

5. Control of the server's lifecycle never moves without the user asking. A desktop app that attached to the service doesn't stop it when it quits. That rules out the kind of orphan described in #22983. Managing the service (status, restart, update, channel) becomes an admin-scoped server RPC, so web and mobile get it as well. An update that restarts the server runs outside the service's own process group (on Linux, a transient systemd unit), so the restart doesn't kill the request that triggered it.

6. Version skew is not a new problem. An attached desktop app runs its bundled UI against whatever server version is hosting. The mobile app and app.t3.codes already handle that. On a mismatch, show it and offer to update.

The smallest end state is one way to host. "Local environment" in the desktop app would mean "run the background service": systemd on Linux, launchd on macOS. Only Windows, which has no service support, would keep the embedded server process. Then each machine has exactly one host and every surface is a client, so startup order stops mattering. The trade-off is that some people want the server to stop when they quit the app. That fits as a service setting ("Stop when T3 Code quits") and doesn't need a second architecture.

A possible order, each step shippable alone:

1. On ServerAlreadyRunningError, offer Use the running server. It turns off the local environment and attaches over loopback. This fixes the trap in Desktop quits on home-ownership refusal instead of offering to connect to the running background service #20250 and Home-ownership dialog gives the same advice for an old and a current background service, and never mentions turning off Local environment #22820.
2. Same-machine detection by environment-id (Treat same-machine saved environments as local for Open in and Reveal in file manager #18515).
3. A service panel in Settings: status, restart, update, channel.
4. Decide whether the embedded server stays the default on Linux and macOS.

Drafted with Claude Code (Claude Opus 5.5), after reading the current main source and debugging this on my machine.

[fionn77]

Additional controlled reproduction on stable 0.1.7, Linux x64 AppImage host and a Windows desktop SSH client:

1. With Local environment enabled, the host desktop owns its normal T3 home.
2. Turn that setting off and let the desktop backend stop.
3. The other desktop reconnects through its saved SSH route. It starts a detached t3 serve using the host's same default home.
4. Turn Local environment back on. Desktop startup is refused because the SSH backend now owns the home.

We verified the SSH launcher PID record, runtime PID, command line, and live POSIX ownership lock all identified the same process. The systemd service was absent. This reproduces without a reboot, update, or stale database lock.

The ownership guard is correct. The gap is the desktop's inability to use the healthy same-machine owner while preserving the normal local desktop experience. Client-only mode works, but it changes that experience and turning Local environment on returns to the failure. Removing the SSH route is a deployment workaround, not a product resolution.

Before preparing another PR, could a maintainer approve or reject this narrower direction?

• On an ownership refusal, offer an explicit Use running server action; keep Quit as the default. No silent automatic attachment or process takeover.
• Verify the server belongs to the same T3 home/environment using runtime ownership and the server descriptor, then authenticate through the existing local auth control plane. Recheck ownership before accepting the connection. Do not invent a new credential-file mechanism.
• Keep the connection represented as the desktop's same-machine environment, preserving local integrations rather than merely saving a remote environment or creating a second home.
• The desktop remains a client of that external owner: quitting the desktop must not stop it, and desktop updates/exposure controls must not silently restart or reconfigure it. If it disappears or is incompatible, offer retry/quit rather than kill it or spawn a competing writer.

This would address the SSH-started-owner case in #21423 as well as service ownership. I have read the scope decisions on #20250, #8115 and #26547. #30333 covers access to client-only recovery, and #21661 covers local integrations for a saved service connection; neither is a claim of approval for this attachment behavior.

This is a request to agree on direction and lifecycle scope, not an implementation or a claim that a fix has shipped. Prepared with Codex from a locally verified reproduction; no personal runtime logs or credentials are included.

[gkoreli]

Building on this thread, I put together a proposal design doc (ADR), with source references after hitting the matching-0.1.7 Connect-to-Desktop failure on macOS.

The source review identifies two existing mechanisms to build on:

• T3 already documents client-only Desktop managing a background service on the same machine, including its Connect link.
• The Connect CLI already issues scoped local sessions for live-server RPC, providing an issuance capability to reuse alongside existing catalog/storage mechanisms.

The proposed Use running server action would attach to a verified, compatible owner of Desktop's selected home. One host would continue serving local Desktop and remote clients; quitting attached Desktop would preserve the external host and its update/exposure ownership.

Native integrations need capability-specific proof. Automatic attachment and hosting-default changes remain separate decisions. #30333 can provide an incremental recovery step toward this workflow.

Can we make this a first-class workflow: one existing server powering both the native Desktop app and remote clients? The linked proposal design doc (ADR) proposes the contract for making that reliable across authentication, lifecycle, compatibility, updates and recovery.

Prepared with Codex; design proposal only.

[0xLightDev]

I hit the same "This T3 home is unavailable" error on Linux (Omarchy) with 0.1.7, running a background service plus the desktop app. This fixed it for me while keeping the service as the main server:

1. Give the app its own home by editing the Exec line of t3code.desktop to env T3CODE_HOME=$HOME/.t3-app /path/to/T3-Code.AppImage %U.
2. Turn off the app's local environment (Settings → Environments → Local environment, or "localEnvironmentEnabled": false in desktop-settings.json while the app is closed). The desktop log then says it is skipping the local environment, so no second server runs.
3. Pair the app to the service: t3 auth pairing create --base-dir <service home> --ttl 15m --base-url http://127.0.0.1:<port>, then paste the URL into Add environment.

Projects, threads and remote access stay on the service, and other devices connect to it as before. This is a workaround, not an official recommendation.

[bradenbiz]

Note

🤖 Claude Opus 5.5 responding on behalf of Braden

Another Linux case on today's nightly, with one consequence I haven't seen covered here.

Setup: Omarchy 4.5 (Arch, Hyprland). The desktop app is the self-updating AppImage; Omarchy 4.5's omarchy-install-ai-t3-code migrates t3code-nightly-bin users to it on ~/.t3. The background service is t3code.service from t3 up, also on ~/.t3. Both run 0.1.8-nightly.20261107.4327. Opening the app, the backend exits 78 (ServerAlreadyRunningError) and "This T3 home is unavailable" quits it. onStateDirOwned on main (25bf84a) still only quits.

The consequence: the dialog's last suggestion, a separate T3CODE_HOME paired with the running server, keeps the desktop's own local environment. The picker then lists this machine twice. Both entries are labeled malta (the hostname) and have different environment IDs, one per home. Web and desktop can't rename them yet (#31948 and #32333 are open). Because the homes differ, the environment-id match that #21661 and #31358 use to treat a paired service as local won't apply either. So the route the dialog offers is the worst one. The setup that works, the same home with Local environment off and then pairing, can't be reached from the dialog.

+1 to the incremental order kvnloo laid out above. Step 1 is #30333 ("Disable local environment and restart", which also drops the separate-home advice). Step 2 is same-machine detection by environment id. An attach that treats the service as this machine's environment would leave one malta in the picker.