A rule for which settings the client owns and which the environment owns

[colonelpanic8]

TL;DR: Which side owns a setting is currently decided one PR at a time. #16816 just moved model favorites onto the environment. A written rule would settle #16899, #15668, #14818, and future cases the same way. Here's a proposed rule. Is it the one you want?

Proposed rule

• The environment owns anything that changes what happens on that machine with no client attached: providers, worktrees, source control, project overrides.
• The client owns how one device looks and behaves (windows, panels, fonts) and its connections to environments.
• Preferences that should follow the person across devices (keybindings, theme, favorites) need an explicit home. Today they end up on whichever side the implementer picked.

Where the current layout conflicts with this

• Keybindings are owned by the environment, so a desktop running without a local environment uses whatever keybindings the environment it connects to has ([Bug]: Custom keybindings are ignored when Local environment is off and the app connects to the background service #15668).
• The desktop's own files live in the server's userdata/ (Separately configurable locations for server config, server data, and client files #19591).
• favorites and providerModelPreferences are defined in both ClientSettingsSchema and ServerSettings (packages/contracts/src/settings.ts).

Questions

1. Is this the rule you want?
2. Should preferences that follow the person live in each client, on a chosen home environment, or in an account?
3. Should keybindings be owned by the client, with an environment-supplied default?

Prior art

VS Code settings each declare a scope: application, machine, machine-overridable, window, or resource. The scope decides where a setting can be set and whether Settings Sync carries it to other machines.

Related

• Separately configurable locations for server config, server data, and client files #19591: separately configurable locations for server config, server data, and client files
• Every setting should be expressible in a config file #19592: every setting should be expressible in a config file
• Keep dotfile-managed settings separate from machine-local changes #19594: keeping dotfile-managed settings separate from machine-local changes
• [Feature]: Commit to a true graphical client/headless server architecture with first-class remote environments #6811: client/headless-server architecture
• Store appearance and behavior settings on the server that serves the web app #16899: storing web client settings on the server that serves the web app
• [Bug]: Custom keybindings are ignored when Local environment is off and the app connects to the background service #15668, fix: sync model favorites and visibility across clients #16816, Environment-level hidden models per provider instance (so mobile and every client respect them) #14818

[ayushdecoded]

A concrete case for "preferences that should follow the person", from a desktop linked to several Linux VMs.

Since #16816, favorites are stored per environment in settings.json. modelPreferencesMigrationPatch copies a client's legacy favorites only while a server's favorites is null, so later changes never propagate. On my setup one linked environment held 5 favorites matching the older client list, while the main machine had 7.

To reproduce:

1. Link a second environment and let the migration run.
2. Add a favorite on the first environment.
3. Open the model picker for the second environment. The new favorite is missing.

Version: 0.1.7-nightly.20261101.4016. Arch-based Linux desktop (Omarchy) linked to Linux VMs over Tailscale.

Workaround: a script that copies favorites from the main machine's settings.json to the other environments. The server's settings watcher applies it without a restart.

Written by Claude (Opus 5.5), following the T3 triage playbook.