Skip to main content

Module: settings

The user-facing configuration surface — one page where every built-in module or installed plugin exposes its own settings, VS Code contributes. configuration style. Each contributor declares its settings; the page auto-renders a form and persists overrides.

Status: implemented — frontend in packages/core/src/modules/settings/ (panel) and packages/core/src/settings.ts (the reactive service), backend in backend/modules/settings/.

The settings contract​

A setting is a registry contribution declared alongside a module's commands/panels/widgets (and identically in a plugin's PluginContributions):

{ key: 'observability.recentCount', title: '…', description: '…',
type: 'number', default: 5 } // types: string | number | boolean | enum

Keys are namespaced like every other contributed id — <module>.<name>, and <pluginId>.<name> for plugins (the loader's assertNamespaced enforces this on setting keys too). The SettingDecl/SettingType types live in @horribledashboard/sdk so built-in modules and plugins share one shape.

The advanced fold​

A declaration may mark itself advanced: true:

{ key: 'network.turnCredential', title: 'TURN credential', description: '…',
type: 'string', default: '', advanced: true }

Each owner's settings are partitioned and the advanced ones render inside a collapsed <details> fold below the basic ones. The count is in the summary, so nothing is hidden — it is folded, not removed.

The line is not "obscure": it is would a working install legitimately change this? The network module is the case that forced it — fourteen knobs at equal weight, of which eight are NAT-traversal plumbing copied verbatim from whoever runs your infrastructure. Presenting those beside "what is this machine called" taught people to skim past the six that matter.

advanced is on SettingDecl in @horribledashboard/sdk, so plugins get the fold for free through the same re-export every other setting field rides.

Schema on the frontend, values on the backend​

The schema and defaults live in the frontend declarations; the backend is a dumb key→value bag (settings.json) that stores only the values the user has overridden. The effective value of a key is its override, or the declared default when unset — resolved in settings.ts. This mirrors how the dashboard backend stores layout without knowing widget shapes, and keeps the backend schema-agnostic.

settings.ts is a reactive store (the telemetry.ts pattern): loadSettings() seeds overrides at boot; getSetting/setSetting/resetSetting read and mutate; useSetting(key) is the hook built-in components use for a live read. Setting a value is optimistic (local update + PUT), so widgets bound via useSetting re-render immediately.

useSetting(key) re-renders only when its own key changes. The store itself has no per-key channel — settingsStore.subscribe fires on a write to any key — and some keys are written often (frame.windowPlacement changes on every window maximize, snap and drag). A raw settingsStore.subscribe consumer must compare the value it cares about before doing work; rebuilding on every emit turned a window maximize into a whole-app re-render.

Never put a secret in a setting​

GET /api/settings returns the bag to the browser, and every value in it is readable by any code running in the page — including third-party plugins, all of which load unsandboxed at boot.

So: an OAuth client id is fine (it's public by design), but a client secret, an API key, or a token must never be a setting. Those belong in the environment or the encrypted secrets store — see connectors.

There are no exceptions. games.google.clientSecret used to be one — it predated the rule — and has been removed: the game server now reads GAMES_GITHUB_CLIENT_SECRET / GAMES_GOOGLE_CLIENT_SECRET from its environment only (see game-server hosting). That case is also why the rule bites harder than it looks: a bundled game server shares $HORRIBLE_DATA_DIR/settings.json with its node, so the secret was reachable from the browser even though nothing in the UI displayed it.

The backstop: secret-shaped keys are never served​

Some user-supplied credentials predate connectors and still live here — training.kaggle.key, training.hf.token, training.google.clientSecret. Rather than leave them in the response until each is migrated, the route blanks any value whose key is secret-shaped (SECRET_KEY_SUFFIXES in backend/modules/settings/models.py: .key, .token, .secret, .password, .apikey, …) and returns a separate secretKeys list naming the ones that are set.

Three deliberate choices:

  • Matched on the key shape, not on a declaration. Declarations live on the frontend, so a backend that trusted them would be asking the untrusted side which of its own values are sensitive.
  • Blanked, not omitted. A key vanishing from the response is indistinguishable from never having been set, and a settings page that cannot tell those apart will overwrite a saved token with an empty string the first time someone saves an unrelated field.
  • Redaction is on the way out only. get_value reads the file, so every backend consumer still sees the real value.

Such a setting is consequently write-only from the UI: it renders as a password field showing saved — type to replace or not set, never the value. A client id is public and keeps working as an ordinary setting.

This is a backstop, not a substitute for the rule. A client secret in a setting is still a bug; the correct home is a connector.

What is deliberately not a setting​

Keybindings. A SettingValue is string | number | boolean, so a list of bindings has no home in the bag, and the whole-bag GET above is the second reason: the keymap is its own document at $HORRIBLE_DATA_DIR/keymap.json behind /api/keymap. It follows the same frontend-owns-the-schema split this store uses — see keymap. keymap.escapeHoldMs is a setting, because it is a single number.

The one setting this module declares itself​

settings.theme — the app's appearance. Appearance is global rather than any one feature's concern, and the shell module would be the natural home, but it registers from inside AppShell's mount effect — long after initTheme() reads the theme at boot, so its declared default would not exist yet at the one moment the theme is first resolved. This module is registered synchronously in main.tsx before loadSettings(), so its default is always readable. Its enumValues are derived from THEMES in packages/core/src/theme.ts, so a theme cannot be shipped and then be unreachable from this page; the palette also gets one Theme: <name> command per entry from the same array. See ../architecture/theming.mdx.

Custom sections​

Some configuration is too rich for the declarative SettingDecl controls (string/number/boolean/enum). A module may also contribute a settingsSections entry — { id, title, component } on its ModuleManifest — and the page renders the component as its own group.

A section whose title matches its module's group is merged into that group rather than added beside it. A module that both declares settings and contributes a section — hardware and updates both do — otherwise produced two nav entries with byte-identical labels ("Hardware" above "Hardware"), with nothing to say which one held the control you wanted. They are one subject, so they render as one group.

Within a merged group the section comes first and the declared settings below it, because the section is the reading and the settings are the overrides. The hardware group is the case that names the rule: its section reports what the probe found — including "could not ask", which is not the same as "nothing" — and the accelerator override sits underneath it. Asking someone to override a measurement printed below the control is how that picker came to offer six options without saying which one was actually detected. The first consumer is the agent's Agent permissions section (PermissionsSettings): a default-mode picker plus editable allow/ask/deny rule lists that read/write agent.permissions.* through /api/settings directly (rule lists are arrays, outside the scalar useSetting store). See ../architecture/agent-tools.md. This seam is built-in only — not part of the public plugin contract yet.

The other consumers are readings rather than controls, which is the same reason they cannot be SettingDecls: Hardware (what the probe found and every default it decided, each with its reason — see hardware.mdx), Updates, and Storage (where this node keeps its files, and by which rule — see ../architecture/data-directories.mdx). Storage's own overrides are environment variables, not settings, because they must resolve before anything is read and settings.json lives in the directory they locate.

Desktop is the fourth, and the one that is a control the store cannot hold: it switches the desktop you are on between the tiled frame and free windows. Mode is a property of each workspace's own layout, so a SettingDecl — one global scalar — could only ever disagree with whichever desktop was in front of you. The setting beside it, desktop.defaultMode, is declarative, because "which kind should a new desktop be" really is one preference. See ../architecture/desktop-shell.mdx.

The page​

Modelled on VS Code's Settings editor: a search box over a category list and a scrolling body. Search matches a setting's title, description, key and owning group — the key included, because that is what docs, plugin manifests and dash call it by, and it is shown beside the title on hover for the same reason. A setting you have overridden gets an accent bar in the gutter (VS Code's "modified" marker) as well as its Reset link: at ~120 settings the link alone is easy to miss when scanning.

Each group renders as one card with hairline-separated rows, rather than every row carrying its own frame — at ~30 groups that reads as a wall of boxes.

Booleans render as a switch, not a checkbox, because a setting here takes effect the moment it is clicked and there is nothing to submit. It is a <button role="switch" aria-checked>; aria-checked both carries the state to assistive tech and drives the styling, so the two cannot drift apart. See ../architecture/theming.mdx for the control vocabulary, which is themed and shared app-wide.

Below ~40rem of pane width the page drops to one column: the category list hides and rows stack. That is a container query, not a media query — a document pane is routinely half of a split, so the window's width says nothing about this page's. Search still reaches every setting, so nothing becomes unreachable when the list goes.

Deep link. openPanel('settings.home', { params: { group: 'Keyboard' } }) scrolls to that group (matched by title, or by group id). It exists for the Keyboard Shortcuts editor, which moved here from a pane of its own; it jumps when the param changes, not on every search keystroke.

Contributions to the layout shell​

  • Panels: settings.home (singleton, document) — the settings page, grouped by the module/plugin that declared each setting, the way VS Code opens its Settings editor. It was a right-docked tool pane once, which gave a two-column page ~20rem and wrapped every row.
  • Commands: settings.open.
  • Keybindings: mod+, → settings.open (VS Code parity).

Built-in settings shipped as the first consumers: observability.recentCount (how many calls the Data flow widget lists), observability.maxBodyChars (how many characters of each captured I/O body to keep — read on the backend, see below) and, from the reference plugin, hello-widget.greetingText.

Most settings are read on the frontend via useSetting, but a value can also be consumed by the backend: backend.modules.settings.get_value(key, default) returns the user override or the caller's fallback (defaults stay frontend-owned, so backend consumers supply their own). observability.maxBodyChars works this way — the telemetry instrumentation truncates bodies at capture time.

Plugins​

Plugins declare settings in their contributions and read values through host.settings (get/set/subscribe), namespace-guarded to their own keys. This is distinct from host.storage: settings are user-configurable on this page; storage is the plugin's own runtime bookkeeping. See ../architecture/plugin-sdk.md.

Backend surface​

backend/modules/settings/ — GET /api/settings (overridden values, secret-shaped ones blanked, plus secretKeys), PUT /api/settings/{key} (set one, body {value}), DELETE /api/settings/{key} (clear an override → revert to the frontend default). Persists to $HORRIBLE_DATA_DIR/settings.json.

Every write is a read-modify-write of the whole bag, so all three routes take a process-wide lock and the file is replaced atomically (temp file + rename) rather than truncated in place — both via backend/jsonstore.py, which every other whole-file JSON store now goes through as well (see ../architecture/data-directories.mdx). Both halves are load-bearing and fail silently without it: the routes are sync def, so FastAPI runs them on the threadpool, and two PUTs that overlap each read the pre-change bag — the second writes it back without the first one's key, and both answer 200. That is not a theoretical race; first-run setup writes the name, the theme and desktop.oobeComplete from a single click, which is how a completed setup wizard came back on the next launch. The atomic rename covers the other direction: a reader (or a crash) catching a truncated file parses nothing, and _read falls back to {} — i.e. every setting the user ever chose, gone.

Browser vs desktop​

Identical. Settings are stored by the backend wherever it runs (local or remote); no platform branching in the page or the service.

Not yet​

Object/array setting types, backend-side validation, search/filter in the page, import/export, and cross-device sync. Schema stays frontend-owned.