Overview
Tempest splits state between two layers:- React frontend — UI state lives in 24 custom store modules under
src/store/, all built on React’suseSyncExternalStorehook. No Redux, Zustand, or Jotai. - Rust backend — process management (PTY sessions, git operations, Docker isolation) lives in
src-tauri/. The backend holds no persistent state of its own.
db_* commands. See Tauri Commands for the full command reference.
Persistence layer
All user-facing persistent state lives in a single SQLite database,tempest.db, inside the app data directory for the identifier com.user.tempest:
- Windows
- macOS
- Linux
%APPDATA%\com.user.tempest\tempest.db
Preferences are not a forest of files. They are a single JSON blob in
app_state under the key "runtime", read and written through the db_load_app_state and db_set_app_state commands and mirrored in RuntimeState (below).
Other on-disk locations
Beyond the main database, a few pieces of state live outside it:RuntimeState shape
File:src/lib/runtimeState.ts
RuntimeState is the shape of the "runtime" preferences blob. Every field is optional from the database’s point of view — missing keys fall back to defaults:
Boot sequence
src/main.tsx hydrates every in-memory mirror from SQLite in parallel before the first render:
loadAppState— loads the"runtime"preferences blobloadSessions/loadProjects— hydrate from thedb_loadsnapshot (projects, branches, sessions)loadRecents/loadTabs— hydrate fromdb_load_recentsanddb_load_tabsterminalRendererPolicy.initialize()— decides WebGL vs. canvas rendering before the first terminal mounts
Store modules
All 24 store modules live insrc/store/. Each is a singleton built on useSyncExternalStore: components subscribe through a use* hook and re-render only when their slice changes.
Ephemeral vs. persisted
The Message Queue is deliberately not persisted: it is a short-lived handoff surface for typed-but-not-sent messages, and queueing stale text across restarts would surprise the user. Work state, likewise, is re-derived live from PTY output and agent hooks.
Project settings and tempest.yml
Per-project security settings are edited in the Project Settings panel (ProjectSettingsPanel/useProjectSettings.ts) and grouped into seven sections:
A project can also commit a
tempest.yml. Because the file arrives with the code, it is merged in the tightening direction only (clampSecurity in src/lib/tempestConfig.ts): a repo can lock itself down further than the user’s panel, never loosen it. Sandbox mode only escalates, blocklists only grow, allowlists only shrink, quotas only shrink. The config’s env block is additionally filtered through a denylist of loader and DB-isolation variables (PATH, NODE_OPTIONS, LD_PRELOAD, DATABASE_URL, and similar), so a hostile repo cannot use environment variables for code execution. Full schema on the tempest.yml page.
Migration notes
Earlier versions of Tempest persisted state in browserlocalStorage. That era is over: legacy keys were migrated into SQLite at startup and are no longer read. Current builds keep exactly three localStorage uses, all deliberate and all UI-local:
Everything else — settings, sessions, tabs, threads, prompts, agent configs — belongs to
tempest.db now.
Example: reading and writing preferences
Stores read settings through the runtime state; a write persists synchronously to memory and asynchronously to SQLite:app_state table: