Skip to main content

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:

  1. If ~/.termia exists and contains a wave.lock file (a pre-v0.9 combined install), the config directory is ~/.termia/config instead.
  2. Otherwise, the TERMIA_CONFIG_HOME environment variable, if set.
  3. Otherwise, XDG_CONFIG_HOME/termia, if XDG_CONFIG_HOME is set.
  4. 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​

The settings interface is the starting point for reviewing current configuration.
The settings interface is the starting point for reviewing current configuration.View full size ↗

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:

  1. 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.
  2. 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.
  3. 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​

KeyTypeDefaultDescription
termia:skustringsaasProduct 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:centerurlstring(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:themestring (system|light|dark)darkOverall app theme. Set from Settings → Appearance.
termia:langstring(none)UI language (e.g. en, zh-CN). Set from Settings → Language; broadcasts to every open tab instantly.

app:* — window chrome and hotkeys​

KeyTypeDefaultDescription
app:*boolWildcard reset for the app: namespace — see Override order.
app:globalhotkeystring(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:dismissarchitecturewarningboolfalseSuppresses the startup warning shown when Termia is running under ARM64 translation (e.g. an Intel build on Apple Silicon).
app:defaultnewblockstringtermView used for a new block: term for a terminal, launcher for the launcher block. Anything else falls back to term.
app:showoverlayblocknumsbooltrueWhether holding the block-number modifier shows the number overlay on each block.
app:dismissedhintsstring(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.

KeyTypeDefaultDescription
ai:*boolWildcard reset for the ai: namespace — see Override order.
ai:apikeystring(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:relayurlstring(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:relaybundlestring(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:centerurlstring(none)Legacy per-preset center URL. Cleared on logout; superseded by the top-level termia:centerurl.
ai:presetstringai@globalLegacy: which ai@ preset a chat block would default to. No ai@ presets ship anymore and nothing reads this key.
ai:apitypestring(none)Legacy chat-provider type (open_ai, azure, anthropic, perplexity). Unused.
ai:baseurlstring(none)Legacy OpenAI-compatible base URL for the removed chat view. Unused.
ai:apitokenstring(none)Legacy literal API token for the removed chat view. Unused — do not confuse with ai:apikey, which is still live.
ai:namestring(none)Legacy display name for a chat provider. Unused.
ai:modelstringgpt-5-miniLegacy chat model name. Unused.
ai:orgidstring(none)Legacy OpenAI organization id. Unused.
ai:apiversionstring(none)Legacy Azure API version. Unused.
ai:maxtokensfloat4000Legacy max-tokens setting for the removed chat view. Unused.
ai:timeoutmsfloat60000Legacy request timeout for the removed chat view. Unused.
ai:proxyurlstring(none)Legacy HTTP proxy for AI requests. Unused.
ai:fontsizefloat(none)Legacy chat text font size. Unused.
ai:fixedfontsizefloat(none)Legacy chat code-block font size. Unused.

term:* — terminal blocks​

KeyTypeDefaultDescription
term:*boolWildcard reset for the term: namespace — see Override order.
term:fontsizefloat(none)Terminal font size in points. Also settable per-connection and per-block.
term:fontfamilystring(none)Terminal font family. Also settable per-connection and per-block.
term:themestring(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:disablewebglboolfalseDisables the WebGL renderer, falling back to the canvas renderer.
term:localshellpathstring(none)Overrides the shell binary path used for new local terminals.
term:localshelloptsstring[](none)Extra arguments passed to term:localshellpath (or the default shell), e.g. ["-NoLogo"] for PowerShell.
term:scrollbackint(none, code default 2000)Scrollback buffer size in lines. Clamped to 50000.
term:copyonselectbooltrueCopies selected terminal text to the clipboard automatically.
term:transparencyfloat(none, code default 0.5)Terminal background transparency, 0 (opaque) to 1 (fully transparent).
term:allowbracketedpasteboolfalseAllows bracketed-paste escape sequences in the terminal.
term:shiftenternewlineboolfalseWhen 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:showagentscenarioboolfalseShows 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:confirmcloserunningbooltrueDeclared 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​

KeyTypeDefaultDescription
editor:minimapenabledbooltrueShows the Monaco minimap in code editor blocks. Also settable per-block.
editor:stickyscrollenabledboolfalsePins the current class/function header at the top while scrolling. Also settable per-block.
editor:wordwrapboolfalseWraps long lines instead of scrolling horizontally. Also settable per-block.
editor:fontsizefloat(none)Code editor font size in points, clamped to 6–64. Also settable per-block.

web:* — web view blocks​

KeyTypeDefaultDescription
web:*boolWildcard reset for the web: namespace — see Override order.
web:openlinksinternallyboolfalseOpens links clicked inside a web block in Termia itself instead of the system browser.
web:defaulturlstringhttps://github.com/open-fusion/termiaHome page shown in a web block when no URL is given.
web:defaultsearchstringhttps://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​

KeyTypeDefaultDescription
blockheader:*boolWildcard reset for the blockheader: namespace — see Override order.
blockheader:showblockidsboolfalseShows 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)​

KeyTypeDefaultDescription
autoupdate:*boolWildcard reset for the autoupdate: namespace — see Override order.
autoupdate:enabledboolfalseEnables background update checks.
autoupdate:intervalmsfloat3600000Milliseconds between update checks.
autoupdate:installonquitbooltrueInstalls a downloaded update automatically the next time the app quits.
autoupdate:channelstring(none)Update channel to track.

markdown:* — markdown preview​

KeyTypeDefaultDescription
markdown:fontsizefloat(none)Body text font size when rendering markdown in a preview block. Also settable per-block.
markdown:fixedfontsizefloat(none)Code-block font size when rendering markdown in a preview block. Also settable per-block.

preview:* — file preview blocks​

KeyTypeDefaultDescription
preview:showhiddenfilesbool(none, code default true)Shows dotfiles in the directory preview.

tab:* — tab defaults​

KeyTypeDefaultDescription
tab:presetstring(none)A bg@ preset id (see Presets) applied automatically to new tabs, e.g. bg@green.

style:* — appearance memory​

KeyTypeDefaultDescription
style:lastlightthemestring(none)Last overall theme picked while in light mode; restored automatically if you switch back.
style:lastdarkthemestring(none)Last overall theme picked while in dark mode.
style:transparencyfloat(none)Global transparency (0–1) for blocks and window chrome. Unset follows the light/dark theme's own default.
style:backgroundblurpxint(none)Global backdrop blur in CSS pixels for blocks and window chrome.

widget:* — right-hand widget rail​

KeyTypeDefaultDescription
widget:*boolWildcard reset for the widget: namespace — see Override order.
widget:showhelpbool(none)Shows help/tip entries in the widget rail.

window:* — window chrome (most require a restart)​

KeyTypeDefaultDescription
window:*boolWildcard reset for the window: namespace — see Override order.
window:transparentboolfalseMakes the window background transparent. Cannot combine with window:blur. Requires restart.
window:blurboolfalseApplies a background blur to the window. Cannot combine with window:transparent; ignored if window:transparent is set. Requires restart.
window:opacityfloat(none, code default 0.8)Window opacity (0–1) when window:transparent or window:blur is set.
window:bgcolorstring(none)Base window background color (hex), used together with window:transparent/window:blur.
window:reducedmotionboolfalseDisables most animations, in addition to following the OS's prefers-reduced-motion setting.
window:tilegapsizeint3Gap in CSS pixels between tiled blocks.
window:showmenubarboolfalseUses the OS-native menu bar instead of the overlay menu (Windows/Linux). Requires restart.
window:nativetitlebarbooltrueUses the OS-native title bar instead of Termia's overlay title bar. Requires restart.
window:disablehardwareaccelerationboolfalseDisables Chromium GPU acceleration, as a workaround for graphical glitches. Requires restart.
window:maxtabcachesizeint10Number of tabs kept warm in memory for instant switching. Requires restart.
window:magnifiedblockopacityfloat0.6Opacity of the backdrop behind a magnified (zoomed-in) block.
window:magnifiedblocksizefloat0.9Size of a magnified block as a fraction of its parent layout.
window:magnifiedblockblurprimarypxint10Backdrop blur, in CSS pixels, directly behind a magnified block.
window:magnifiedblockblursecondarypxint2Backdrop blur, in CSS pixels, applied to the other (non-magnified) blocks while one is magnified.
window:confirmclosebooltrueAsks for confirmation before closing a window.
window:savelastwindowbooltrueReopens the last window that was closed the next time Termia launches.
window:dimensionsstring(none)Default size for a brand-new window with no saved size yet, as WIDTHxHEIGHT in pixels, e.g. 1920x1080.
window:zoomfloat(none)Declared in the schema but not currently read anywhere in this app.

telemetry:* — telemetry​

KeyTypeDefaultDescription
telemetry:*boolWildcard reset for the telemetry: namespace — see Override order.
telemetry:enabledboolfalseEnables 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.

KeyTypeDefaultDescription
conn:*boolWildcard reset for the conn: namespace — see Override order.
conn:askbeforewshinstallbooltruePrompts before installing the wsh helper on a new remote connection.
conn:wshenabledbooltrueEnables the wsh remote helper for connections that don't override it.
conn:passwordsaveenabledbooltrueAllows saving SSH passwords so you aren't prompted every time you reconnect.
conn:passwordcachetimeoutint (seconds)2592000How long a saved SSH password is cached before it must be re-entered (default: 30 days).

userconfig:* — device config sync​

KeyTypeDefaultDescription
userconfig:uploadintervalmsfloat300000How often, in milliseconds, this device's config is uploaded when sync is active.
userconfig:autosyncboolfalseEnables automatic config upload.

vaultssync: / vaultsautosync: — Vaults cloud sync​

See Vaults Sync and Versioning for what gets synced.

KeyTypeDefaultDescription
vaultssync:termiasyncboolfalseMaster switch for Termia cloud sync of Vaults data. Also settable from Settings → Sync.
vaultsautosync:enabledbooltrueSyncs automatically on the interval below, instead of only on manual "Sync Now." Also settable from Settings → Sync.
vaultssync:intervalmsfloat300000Auto-sync interval in milliseconds. Also settable from Settings → Sync.

vaultmemory:* — Vaults notebook memory files​

KeyTypeDefaultDescription
vaultmemory:*boolWildcard reset for the vaultmemory: namespace — see Override order.
vaultmemory:enabledbooltrueEnables the Vaults memory-file integration.
vaultmemory:basedirstringvaultsmemSubdirectory (under the data directory) where memory files are kept.
vaultmemory:maxfilesizeint (bytes)1048576Maximum size of a single memory file (1 MiB).
vaultmemory:maxtotalsizeint (bytes)104857600Maximum combined size of all memory files (100 MiB).
vaultmemory:cleanupintervalint (seconds)3600How 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} through c{Digit9} (non-numpad)
  • Numpad digits c{Numpad0} through c{Numpad9}, plus Decimal, Add, Subtract, Multiply, Divide
  • F1–F20, and Soft1–Soft4 (mapped to F21–F24)
  • Space (or a literal space)
  • Enter, Tab, CapsLock, NumLock, Backspace, Delete, Insert
  • ArrowUp, ArrowDown, ArrowLeft, ArrowRight, Home, End, PageUp, PageDown, Esc
  • AudioVolumeUp, AudioVolumeDown, AudioVolumeMute
  • MediaTrackNext, MediaTrackPrevious, MediaPlayPause, MediaStop
  • PrintScreen

Example: to bind F5 as the global hotkey, run wsh setconfig app:globalhotkey=F5 and restart Termia.