Skip to main content

Overview

Tempest splits state between two layers:
  • React frontend — UI state lives in 24 custom store modules under src/store/, all built on React’s useSyncExternalStore hook. 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.
The two layers synchronize through Tauri IPC commands. Anything that must survive a restart is written to a SQLite database by the frontend through 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:
%APPDATA%\com.user.tempest\tempest.db
The database has 16 tables: 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:
Access is centralized in four functions:

Boot sequence

src/main.tsx hydrates every in-memory mirror from SQLite in parallel before the first render:
  • loadAppState — loads the "runtime" preferences blob
  • loadSessions / loadProjects — hydrate from the db_load snapshot (projects, branches, sessions)
  • loadRecents / loadTabs — hydrate from db_load_recents and db_load_tabs
  • terminalRendererPolicy.initialize() — decides WebGL vs. canvas rendering before the first terminal mounts
Only after all six resolve does React render, so no component ever sees a half-hydrated store.

Store modules

All 24 store modules live in src/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 browser localStorage. 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:
Under the hood this is two Tauri commands over the app_state table: