Environment themes for a desktop paired to its own background service, and published themes from every connected environment

[AkiVonAkira]

Follow-up to #19842, which asked for this as an Ideas discussion that explains how conflicts between environments are resolved.

Problem

Since #16102, one server owns a T3 home. A desktop that runs on the same machine as t3 service has to turn Local environment off and pair with the service through Add environment. The background-service docs lead users to this setup, so that closing the window doesn't stop threads.

That desktop then has no primary environment, so it never sees that home's environment themes. t3 theme set on the service changes nothing, and the published themes aren't listed in Settings → Appearance. The workaround in #19842, keeping Local environment on, is no longer possible because the service owns the lock. Today the only way is to import the JSON by hand on every client, and then the theme no longer follows server updates.

Seen on 0.0.46-nightly.20261015.3145, desktop and service on the same machine.

Cause (by design)

• apps/web/src/state/primaryEnvironment.ts#L5-L12: the primary environment is the catalog entry whose target is PrimaryConnectionTarget. A paired environment is a BearerConnectionTarget (packages/client-runtime/src/connection/model.ts#L9-L54).
• apps/web/src/hooks/useEnvironmentTheme.ts#L107-L108 and apps/web/src/state/server.ts#L125-L128: published themes come only from the primary server's config.
• apps/web/src/hooks/useDefaultTheme.ts#L73-L84: default-theme adoption keys on primaryEnvironmentIdAtom and returns early when it is null.

Two separate questions

"Which themes can I pick?" and "whose t3 theme set switches me?" are separate questions. Only the second can conflict.

Proposal 1: treat a same-home paired environment as the theme source

When the desktop has no primary environment, use a paired environment whose environmentId matches the desktop's own T3 home (userdata/environment-id) as the source for environment themes and default adoption.

• No new conflict. It is the same home and the same server the desktop would have started itself, so there is still exactly one source, as there is today.
• Narrow. It only touches theme sync and useDefaultThemeAdoption. Every other "primary" behaviour stays as it is. A broader version would make that connection fully primary, but that is a larger decision.
• Applied-generation key unchanged. The key is already t3code:default-theme-applied:v2:<environmentId> and the environment ID doesn't change, so a client that switches from Local environment to the paired service doesn't apply the same t3 theme set twice.
• Needs one value from the desktop. The desktop already reads that home for desktop-settings.json. It would pass the home's environment ID to the renderer, next to the existing desktop bootstrap data.

Proposal 2: published themes from every connected environment, defaults from one

Extend Settings → Appearance to list the published themes of every connected environment:

• Grouped by environment name, with IDs namespaced by environment (for example <environmentId>:<themeId>), so two machines can each publish a nightfall without colliding.
• Live palette. Picking one follows its palette as that environment updates it, as published themes already do for the primary.
• Offline is not unpublished. If that environment goes offline, keep the last palette it sent. Fall back to the standard theme only when it stops publishing the theme.
• Defaults do not merge. Only the theme source (the primary, or the Proposal 1 environment) can switch clients with t3 theme set. A t3 theme set on any other environment only publishes. Most-recent-wins across machines is not used, because their clocks can differ and the result would surprise people.

That is the conflict rule: one environment sets the default, and every environment can publish themes a client can pick.

A later option, not part of this ask: a Follow defaults from setting per client, for clients that have neither a primary nor a same-home environment.

Use case

A seated Linux desktop paired with its own t3 service, as background-service.md describes, with a theme published once on the service (t3 theme set nightfall). Today each client has to import that file by hand, and it stops following updates. With Proposal 1 the desktop behaves as it did with Local environment on. With Proposal 2, other machines can also pick the theme from the environment that publishes it.

Proposal 1 is a small change. If maintainers approve the direction, I can send a PR for it.

[clayton-glober]

This limitation is still present with T3 Code v0.1.2 (desktop AppImage and background-service CLI), on Omarchy/Hyprland Linux.

My desktop has Local environment disabled and is paired with the persistent background server on the same machine. Omarchy publishes its generated palette to ~/.t3/userdata/themes/omarchy.json. The service uses that same T3 home, t3 theme show reports omarchy as the selected environment theme, and the published JSON matches the current Omarchy palette. Republishing the file and re-running t3 theme set omarchy --base-dir ~/.t3 through both the desktop-bundled CLI and the background runtime CLI succeeds, but the desktop appearance does not change.

This affects Omarchy's automatic theme integration, not just one-time selection. Omarchy PRs #15907 (self-updating AppImage) and #14178 (theme setup without opening the app) are already present in the installed Omarchy revision, 967bbdd7346e6e2ff1a6af33c5d762ea784832cc; neither changes T3's primary-only theme-source behavior.

Source review at T3 main eb1510d2493cbf28600432d5193cc22a1af8f3d8 still shows useEnvironmentThemeSync consuming only primaryServerEnvironmentThemesAtom, and useDefaultThemeAdoption consuming only the primary environment's ID/settings. With Local environment off, platform connection registrations are empty, so the paired service never becomes that primary theme source. The installed desktop bundle also contains this primary-gated adoption logic.

Proposal 1 would address this use case while preserving the background server: follow the paired environment matching the desktop's own T3 home, without giving unrelated connections control of the client theme. Manual import provides a snapshot workaround, but loses automatic updates when Omarchy changes themes. Enabling the desktop's Local environment is not a suitable workaround while the service owns the same home.

Adding this as current-version evidence for the existing proposal, rather than opening a duplicate of #19842. No patched client build or visual UI automation was used to validate a fix.