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_valuereads 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-dockedtoolpane 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.