Configuration
Termia's global settings live in one JSON file, settings.json. It is a flat file — instead of
nested objects, keys use : as a namespace separator (term:fontsize, window:transparent, and
so on). This page documents where that file lives, how to edit it, how it interacts with
per-connection and per-block overrides, and every key it declares.
Where settings.json lives
Termia keeps its editable configuration in a .config-style directory, the same on every
platform, separate from the larger data directory (SQLite database, logs, cached tab state):
| Default location | |
|---|---|
Config directory (settings.json, presets.json, widgets.json, termthemes.json, connections.json) | ~/.config/termia/ on macOS, Linux, and Windows |
| Data directory (database, logs, vault sync state) | macOS: ~/Library/Application Support/termia/; Linux: ~/.local/share/termia/ (or $XDG_DATA_HOME/termia); Windows: %LOCALAPPDATA%\termia\Data |
The config directory is intentionally not the platform-conventional Application Support /
%APPDATA% location — Termia treats its config directory as a dotfile home you're expected to
edit and version, the same way on every OS. It resolves in this order:
- If
~/.termiaexists and contains awave.lockfile (a pre-v0.9 combined install), the config directory is~/.termia/configinstead. - Otherwise, the
TERMIA_CONFIG_HOMEenvironment variable, if set. - Otherwise,
XDG_CONFIG_HOME/termia, ifXDG_CONFIG_HOMEis set. - Otherwise,
~/.config/termia.
settings.json sits directly inside that directory: ~/.config/termia/settings.json by default.
If the file or directory doesn't exist yet, Termia creates it on first write.
Editing settings

In the app
Open Settings from the tab-bar avatar, gear or application menu. The current sidebar groups pages into Basics (General, Appearance, Terminal, Window), Capabilities (Web, AI, Sync) and System (Security, Privacy, Updates, Advanced, About). Account and Vaults sync controls are on Sync; language is on General, and keyboard settings are on Terminal. AI → Manage providers & models… opens TT Agent provider/BYOK management. Security → Host password security reports the local master key and migration status.
Common preferences have UI controls; advanced options can be edited in JSON. Read each control's effect notice: some changes apply immediately, others affect newly created terminals or require a restart. See the feature guide, shortcuts and credentials/sync.
By hand
Run this from any terminal block to open settings.json in Termia's built-in editor:
wsh editconfig
Pass a different filename (presets.json, widgets.json, termthemes.json, connections.json)
to edit one of the other config files the same way. You can also open the file in any external
text editor — it's plain JSON.
To set a key without opening an editor:
wsh setconfig term:fontsize=14
wsh setconfig validates the key against the schema below and rejects unknown keys or values of
the wrong type.
Keeping secrets out of the file
Any string value in any config file can reference an environment variable instead of a literal,
using $ENV:VARIABLE_NAME or $ENV:VARIABLE_NAME:fallback:
{
"web:defaulturl": "$ENV:TERMIA_HOMEPAGE:https://github.com/open-fusion/termia"
}
If the environment variable isn't set, the fallback (if given) is used; otherwise the value resolves to an empty string.
Override order
Many term:* and a few other keys can be set at more than one level. When a block reads one of
these keys, Termia resolves it in this order and stops at the first level that has a value:
- Block metadata — set on a single block with
wsh setmeta, e.g.wsh setmeta this term:theme=default-light. Takes effect only for that one block. - Connection config — set per-connection in
connections.json(see Connections). Only a handful of keys are also declared there today:term:fontsize,term:fontfamily,term:theme,conn:wshenabled,conn:askbeforewshinstall. Every other key skips this level entirely. - Global settings.json — the table below. Applies everywhere nothing more specific is set.
A separate mechanism resets a whole namespace at once: setting a <prefix>:* key (app:*,
ai:*, term:*, web:*, blockheader:*, autoupdate:*, widget:*, window:*,
telemetry:*, conn:*, vaultmemory:*) to true in an update clears every existing key under
that prefix before the rest of the update is applied. This is how applying a
preset guarantees a clean slate instead of merging on top of stale keys; you
won't normally write these by hand.
Settings reference
The tables below list every key declared in the settings schema, grouped by prefix in the order they appear in the underlying Go struct. "Default" is blank where Termia ships no default and the feature simply falls back to a hardcoded value described in the Description column.
A handful of keys in this same schema (native:startpage, native:autoreconnect,
native:keymap, native:newtablayout, termia:termtheme, termia:singlepaneheader,
term:macosoptionasalt) are read only by the separate macOS native client, not by this app —
see macOS Settings instead. They're left out of the tables below.
termia:* — product identity
| Key | Type | Default | Description |
|---|---|---|---|
termia:sku | string | saas | Product SKU (saas or enterprise) that decides which login/billing flow and setup wizard run. Seeded once from the build's TERMIA_SKU on first launch; editing it by hand does not re-brand a build that was compiled for the other SKU. |
termia:centerurl | string | (none) | Base URL of the Termia Center gateway. Relay, center API, and Supabase auth are all routed through it by path prefix. Seeded once from the build's TERMIA_CENTER_URL, or written by the enterprise setup wizard. |
termia:theme | string (system|light|dark) | dark | Overall app theme. Set from Settings → Appearance. |
termia:lang | string | (none) | UI language (e.g. en, zh-CN). Set from Settings → Language; broadcasts to every open tab instantly. |
app:* — window chrome and hotkeys
| Key | Type | Default | Description |
|---|---|---|---|
app:* | bool | Wildcard reset for the app: namespace — see Override order. | |
app:globalhotkey | string | (none) | A systemwide shortcut, active even when Termia isn't focused, that brings the most recent Termia window to the front (or opens a new one). Key names are joined with :, e.g. Ctrl:Option:e. See allowed key names below. |
app:dismissarchitecturewarning | bool | false | Suppresses the startup warning shown when Termia is running under ARM64 translation (e.g. an Intel build on Apple Silicon). |
app:defaultnewblock | string | term | View used for a new block: term for a terminal, launcher for the launcher block. Anything else falls back to term. |
app:showoverlayblocknums | bool | true | Whether holding the block-number modifier shows the number overlay on each block. |
app:dismissedhints | string | (none) | Comma-separated list of dismissed one-time hint-banner ids. Declared in the schema but not currently wired to a visible hint banner in this build. |
ai:* — Termia Agent credentials (mostly legacy)
Almost all of this group is inherited schema from the removed AI chat view and is no longer read
by anything. Model selection today happens in Settings → AI (a picker over relay and
BYOK providers), not through a ai:preset value — see Termia Agent. Only
ai:apikey is live.
| Key | Type | Default | Description |
|---|---|---|---|
ai:* | bool | Wildcard reset for the ai: namespace — see Override order. | |
ai:apikey | string | (none) | The relay/gateway credential the signed-in Termia Agent uses to call the relay. Written and cleared automatically by login/logout; supports $ENV: resolution, but is not meant to be hand-edited. |
ai:relayurl | string | (none) | Legacy relay address. Always cleared to empty on login — the relay address is now derived from termia:centerurl. wsh setconfig still watches this key and resyncs the (empty) relay bundle when it changes. |
ai:relaybundle | string | (none) | Legacy JSON blob of relay-issued provider credentials that used to get synced into env-var vaults. Always cleared on login, same as ai:relayurl. |
ai:centerurl | string | (none) | Legacy per-preset center URL. Cleared on logout; superseded by the top-level termia:centerurl. |
ai:preset | string | ai@global | Legacy: which ai@ preset a chat block would default to. No ai@ presets ship anymore and nothing reads this key. |
ai:apitype | string | (none) | Legacy chat-provider type (open_ai, azure, anthropic, perplexity). Unused. |
ai:baseurl | string | (none) | Legacy OpenAI-compatible base URL for the removed chat view. Unused. |
ai:apitoken | string | (none) | Legacy literal API token for the removed chat view. Unused — do not confuse with ai:apikey, which is still live. |
ai:name | string | (none) | Legacy display name for a chat provider. Unused. |
ai:model | string | gpt-5-mini | Legacy chat model name. Unused. |
ai:orgid | string | (none) | Legacy OpenAI organization id. Unused. |
ai:apiversion | string | (none) | Legacy Azure API version. Unused. |
ai:maxtokens | float | 4000 | Legacy max-tokens setting for the removed chat view. Unused. |
ai:timeoutms | float | 60000 | Legacy request timeout for the removed chat view. Unused. |
ai:proxyurl | string | (none) | Legacy HTTP proxy for AI requests. Unused. |
ai:fontsize | float | (none) | Legacy chat text font size. Unused. |
ai:fixedfontsize | float | (none) | Legacy chat code-block font size. Unused. |
term:* — terminal blocks
| Key | Type | Default | Description |
|---|---|---|---|
term:* | bool | Wildcard reset for the term: namespace — see Override order. | |
term:fontsize | float | (none) | Terminal font size in points. Also settable per-connection and per-block. |
term:fontfamily | string | (none) | Terminal font family. Also settable per-connection and per-block. |
term:theme | string | (none) | Id of a theme from termthemes.json (see Customization). When unset, the terminal follows the app's light/dark mode automatically (default-light / default-dark). Also settable per-connection and per-block. |
term:disablewebgl | bool | false | Disables the WebGL renderer, falling back to the canvas renderer. |
term:localshellpath | string | (none) | Overrides the shell binary path used for new local terminals. |
term:localshellopts | string[] | (none) | Extra arguments passed to term:localshellpath (or the default shell), e.g. ["-NoLogo"] for PowerShell. |
term:scrollback | int | (none, code default 2000) | Scrollback buffer size in lines. Clamped to 50000. |
term:copyonselect | bool | true | Copies selected terminal text to the clipboard automatically. |
term:transparency | float | (none, code default 0.5) | Terminal background transparency, 0 (opaque) to 1 (fully transparent). |
term:allowbracketedpaste | bool | false | Allows bracketed-paste escape sequences in the terminal. |
term:shiftenternewline | bool | false | When enabled, Shift+Enter sends an escape + newline (\n) instead of a plain return — useful for TT agents and similar tools that treat that sequence as "insert newline, don't submit." |
term:showagentscenario | bool | false | Shows a first-run "start an agent" entry (and floating button) on a fresh terminal block, prompting you to launch the Termia Agent instead of a plain shell. |
term:confirmcloserunning | bool | true | Declared with a default, but not currently read by the close-confirmation logic in this app (closing a block running the Termia Agent or a detected TUI always confirms, independent of this key). |
editor:* — code editor blocks
| Key | Type | Default | Description |
|---|---|---|---|
editor:minimapenabled | bool | true | Shows the Monaco minimap in code editor blocks. Also settable per-block. |
editor:stickyscrollenabled | bool | false | Pins the current class/function header at the top while scrolling. Also settable per-block. |
editor:wordwrap | bool | false | Wraps long lines instead of scrolling horizontally. Also settable per-block. |
editor:fontsize | float | (none) | Code editor font size in points, clamped to 6–64. Also settable per-block. |
web:* — web view blocks
| Key | Type | Default | Description |
|---|---|---|---|
web:* | bool | Wildcard reset for the web: namespace — see Override order. | |
web:openlinksinternally | bool | false | Opens links clicked inside a web block in Termia itself instead of the system browser. |
web:defaulturl | string | https://github.com/open-fusion/termia | Home page shown in a web block when no URL is given. |
web:defaultsearch | string | https://www.google.com/search?q={query} | Search template used for bare search terms typed into a web block's address bar; `{query}` is replaced with the search text. |
blockheader:* — block header bar
| Key | Type | Default | Description |
|---|---|---|---|
blockheader:* | bool | Wildcard reset for the blockheader: namespace — see Override order. | |
blockheader:showblockids | bool | false | Shows the first 8 characters of each block's id in its header, useful when scripting against blocks with wsh. |
autoupdate:* — app updater (all require a restart)
| Key | Type | Default | Description |
|---|---|---|---|
autoupdate:* | bool | Wildcard reset for the autoupdate: namespace — see Override order. | |
autoupdate:enabled | bool | false | Enables background update checks. |
autoupdate:intervalms | float | 3600000 | Milliseconds between update checks. |
autoupdate:installonquit | bool | true | Installs a downloaded update automatically the next time the app quits. |
autoupdate:channel | string | (none) | Update channel to track. |
markdown:* — markdown preview
| Key | Type | Default | Description |
|---|---|---|---|
markdown:fontsize | float | (none) | Body text font size when rendering markdown in a preview block. Also settable per-block. |
markdown:fixedfontsize | float | (none) | Code-block font size when rendering markdown in a preview block. Also settable per-block. |
preview:* — file preview blocks
| Key | Type | Default | Description |
|---|---|---|---|
preview:showhiddenfiles | bool | (none, code default true) | Shows dotfiles in the directory preview. |
tab:* — tab defaults
| Key | Type | Default | Description |
|---|---|---|---|
tab:preset | string | (none) | A bg@ preset id (see Presets) applied automatically to new tabs, e.g. bg@green. |
style:* — appearance memory
| Key | Type | Default | Description |
|---|---|---|---|
style:lastlighttheme | string | (none) | Last overall theme picked while in light mode; restored automatically if you switch back. |
style:lastdarktheme | string | (none) | Last overall theme picked while in dark mode. |
style:transparency | float | (none) | Global transparency (0–1) for blocks and window chrome. Unset follows the light/dark theme's own default. |
style:backgroundblurpx | int | (none) | Global backdrop blur in CSS pixels for blocks and window chrome. |
widget:* — right-hand widget rail
| Key | Type | Default | Description |
|---|---|---|---|
widget:* | bool | Wildcard reset for the widget: namespace — see Override order. | |
widget:showhelp | bool | (none) | Shows help/tip entries in the widget rail. |
window:* — window chrome (most require a restart)
| Key | Type | Default | Description |
|---|---|---|---|
window:* | bool | Wildcard reset for the window: namespace — see Override order. | |
window:transparent | bool | false | Makes the window background transparent. Cannot combine with window:blur. Requires restart. |
window:blur | bool | false | Applies a background blur to the window. Cannot combine with window:transparent; ignored if window:transparent is set. Requires restart. |
window:opacity | float | (none, code default 0.8) | Window opacity (0–1) when window:transparent or window:blur is set. |
window:bgcolor | string | (none) | Base window background color (hex), used together with window:transparent/window:blur. |
window:reducedmotion | bool | false | Disables most animations, in addition to following the OS's prefers-reduced-motion setting. |
window:tilegapsize | int | 3 | Gap in CSS pixels between tiled blocks. |
window:showmenubar | bool | false | Uses the OS-native menu bar instead of the overlay menu (Windows/Linux). Requires restart. |
window:nativetitlebar | bool | true | Uses the OS-native title bar instead of Termia's overlay title bar. Requires restart. |
window:disablehardwareacceleration | bool | false | Disables Chromium GPU acceleration, as a workaround for graphical glitches. Requires restart. |
window:maxtabcachesize | int | 10 | Number of tabs kept warm in memory for instant switching. Requires restart. |
window:magnifiedblockopacity | float | 0.6 | Opacity of the backdrop behind a magnified (zoomed-in) block. |
window:magnifiedblocksize | float | 0.9 | Size of a magnified block as a fraction of its parent layout. |
window:magnifiedblockblurprimarypx | int | 10 | Backdrop blur, in CSS pixels, directly behind a magnified block. |
window:magnifiedblockblursecondarypx | int | 2 | Backdrop blur, in CSS pixels, applied to the other (non-magnified) blocks while one is magnified. |
window:confirmclose | bool | true | Asks for confirmation before closing a window. |
window:savelastwindow | bool | true | Reopens the last window that was closed the next time Termia launches. |
window:dimensions | string | (none) | Default size for a brand-new window with no saved size yet, as WIDTHxHEIGHT in pixels, e.g. 1920x1080. |
window:zoom | float | (none) | Declared in the schema but not currently read anywhere in this app. |
telemetry:* — telemetry
| Key | Type | Default | Description |
|---|---|---|---|
telemetry:* | bool | Wildcard reset for the telemetry: namespace — see Override order. | |
telemetry:enabled | bool | false | Enables telemetry. See Telemetry for what is and isn't collected. |
conn:* — connection defaults
These are the global defaults; per-connection values in connections.json (see
Connections) override them for that connection.
| Key | Type | Default | Description |
|---|---|---|---|
conn:* | bool | Wildcard reset for the conn: namespace — see Override order. | |
conn:askbeforewshinstall | bool | true | Prompts before installing the wsh helper on a new remote connection. |
conn:wshenabled | bool | true | Enables the wsh remote helper for connections that don't override it. |
conn:passwordsaveenabled | bool | true | Allows saving SSH passwords so you aren't prompted every time you reconnect. |
conn:passwordcachetimeout | int (seconds) | 2592000 | How long a saved SSH password is cached before it must be re-entered (default: 30 days). |
userconfig:* — device config sync
| Key | Type | Default | Description |
|---|---|---|---|
userconfig:uploadintervalms | float | 300000 | How often, in milliseconds, this device's config is uploaded when sync is active. |
userconfig:autosync | bool | false | Enables automatic config upload. |
vaultssync: / vaultsautosync: — Vaults cloud sync
See Vaults Sync and Versioning for what gets synced.
| Key | Type | Default | Description |
|---|---|---|---|
vaultssync:termiasync | bool | false | Master switch for Termia cloud sync of Vaults data. Also settable from Settings → Sync. |
vaultsautosync:enabled | bool | true | Syncs automatically on the interval below, instead of only on manual "Sync Now." Also settable from Settings → Sync. |
vaultssync:intervalms | float | 300000 | Auto-sync interval in milliseconds. Also settable from Settings → Sync. |
vaultmemory:* — Vaults notebook memory files
| Key | Type | Default | Description |
|---|---|---|---|
vaultmemory:* | bool | Wildcard reset for the vaultmemory: namespace — see Override order. | |
vaultmemory:enabled | bool | true | Enables the Vaults memory-file integration. |
vaultmemory:basedir | string | vaultsmem | Subdirectory (under the data directory) where memory files are kept. |
vaultmemory:maxfilesize | int (bytes) | 1048576 | Maximum size of a single memory file (1 MiB). |
vaultmemory:maxtotalsize | int (bytes) | 104857600 | Maximum combined size of all memory files (100 MiB). |
vaultmemory:cleanupinterval | int (seconds) | 3600 | How often stale memory files are swept, in seconds. |
Allowed global hotkey key names
For app:globalhotkey, key names are joined with : (e.g. Ctrl:Option:e, or F5 on its own).
Supported names:
Ctrl,Cmd,Shift,Alt,Option,Meta,Super- Letters
a–z - Digits
c{Digit0}throughc{Digit9}(non-numpad) - Numpad digits
c{Numpad0}throughc{Numpad9}, plusDecimal,Add,Subtract,Multiply,Divide F1–F20, andSoft1–Soft4(mapped toF21–F24)Space(or a literal space)Enter,Tab,CapsLock,NumLock,Backspace,Delete,InsertArrowUp,ArrowDown,ArrowLeft,ArrowRight,Home,End,PageUp,PageDown,EscAudioVolumeUp,AudioVolumeDown,AudioVolumeMuteMediaTrackNext,MediaTrackPrevious,MediaPlayPause,MediaStopPrintScreen
Example: to bind F5 as the global hotkey, run wsh setconfig app:globalhotkey=F5 and restart
Termia.