Tempest Architecture
Tempest is a desktop app for running many AI coding agents in parallel, each in its own isolated git worktree. This page describes how the system is put together: the Rust backend, the React frontend, the IPC layer between them, the worktree model, process isolation, database branching, and Token Intelligence.1. High-Level Overview
Tempest splits responsibilities between a web-technology frontend and a native Rust backend, connected by Tauri’s IPC:.tempest/ directory, one Atlas MCP daemon per indexed project, Node bridge sidecars for chat (claude, codex, opencode, gemini), and a cloudflared sidecar used for mobile pairing.
Hephaestus
Per-session process isolation with Job Objects, Seatbelt, and bubblewrap.
Database branches
Docker-based PostgreSQL branching for agent sessions.
Token Intelligence
A semantic code graph exposed to agents over MCP.
Mobile pairing
End-to-end-encrypted remote control from a phone.
2. Repository & Process Model
Tempest is a Tauri 2 + React 19 desktop application; frontend and backend versions are matched at 0.1.25. A local Windows build produces NSIS and MSI installers (bundle targets["nsis", "msi"]); released macOS and Linux artifacts are built in CI.
The Rust side is a Cargo workspace:
The root crate’s modules:
144 Tauri commands are registered in
generate_handler!. Every command is documented in Tauri commands, and the persisted state model is described in App state internals.
3. IPC Communication
The frontend and backend talk over three Tauri mechanisms:invoke— request/response. Every command returnsResult<T, String>; errors surface in the frontend as strings.Channel<PtyOutputPayload>— a typed channel passed into a command so the backend can stream results back. PTY output is streamed this way, batched in roughly 16 ms / 64 KiB windows.app.emit— app-wide event broadcasts.
PTY output is deliberately not one of these broadcasts — it streams over the per-session
Channel passed to create_pty_session, so each terminal only receives its own data.
A frontend invoke that streams PTY output through a Channel:
4. Persistence (SQLite)
All persistence lives in a single SQLite database at<app-data-dir>/tempest.db (app identifier com.user.tempest) with 16 tables:
App preferences persist as a single JSON blob row in
app_state under the key "runtime", read and written by the db_load_app_state / db_set_app_state commands. The frontend hydrates it into a RuntimeState object containing settings, keybindings, attribution, onboardingComplete, sessionOrder, activeInstanceId, prompts, atlasProjects, agentConfigs, customAgents, theme, chatProvider, and chatModel.
Boot hydration happens in src/main.tsx, which runs loadAppState, loadSessions, loadProjects, loadRecents, and loadTabs in parallel before the first render.
There is no
runtime-state.json and no localStorage session persistence. Legacy localStorage data was migrated into SQLite; new code reads and writes only the database and React stores.5. The Worktree Model
Every agent session runs in a git worktree at<project>/.tempest/<name> — slashes in a name map to -. Each worktree is a full checkout with its own branch, backed by the shared .git directory, so agents never touch each other’s files or the main working tree.
Creation flow
1
Claim from the warm pool when possible
Tempest keeps a warm pool of 3 pre-created slots with a 5-minute TTL, staged in
.tempest/.warm-<uuid8> on branch tempest-prep/<uuid8>. A new session claims a warm slot when one is available, which makes opening a workspace near-instant.2
Fall back to a fresh worktree
On a pool miss, Tempest runs
git worktree add --no-checkout and then materializes the checkout.3
Copy env files
.env, .env.local, .env.development, and .env.production are copied from the project root so agents can read them.4
Link dependency directories
node_modules and .venv are linked, not copied — a Windows junction on Windows, a Unix symlink elsewhere. This avoids copying hundreds of megabytes per session.5
Persist the child PID
The shell’s PID is written to
<worktree>/.tempest-pid, kept out of git status via .git/worktrees/<name>/info/exclude. This lets Tempest kill orphaned processes after an app restart.6
Validate
An empty tree (only
.git/) is rejected, so an agent never starts in a blank checkout.Cleanup flow
close_pty_session tears a session down in order: lifecycle job, then isolate destroy, then DB-branch delete, then a taskkill / kill sweep. After the processes are gone:
- Junctions and symlinks are removed before
remove_dir_all— otherwise the recursive delete follows the junction into the realnode_modules. - Removal retries in a loop on Windows while directory handles drain.
git worktree pruneclears dangling git metadata.
6. Agent Spawn Pipeline
The frontend pre-assembles the agent invocation and callscreate_pty_session with:
session_id,cwd,rows,cols- optional
commandandargs(a plain shell session omits both) - optional
sandbox(aSandboxSpec) andpolicy(aSessionPolicy) db_isolation,env(thetempest.ymlenv map),worktree_addon_event— the output channel
Launch policy gate
Before any resource is acquired, the backend vets the launch: the agent must be in the project’spermitted_agents, and if allow_skip_permissions is false, any skip-permission flag found in args is refused.
Shell and quoting
The frontend sends arguments as a list; Rust shell-quotes them — doubling single quotes for PowerShell on Windows, POSIX'\'' escaping elsewhere. The shell is resolved once and cached:
- Windows: probe
pwsh, falling back topowershell.exe, spawned with-NoLogo -NoExit -Command. - Unix: use
$SHELL(falling back to/bin/bash), spawned with-lic "<invocation>; exec $SHELL -il"so the agent runs in a login shell that stays open afterwards.
Environment
TERM=xterm-256color is set on non-Windows hosts. A project’s tempest.yml can contribute extra environment variables through the env map, but a denylist is enforced — PATH, NODE_OPTIONS, LD_PRELOAD, DYLD_*, PYTHONPATH, DATABASE_URL, PG*, and similar names are rejected. Database-isolation variables are written into the live shell after spawn, not at spawn. See Agents for the bundled agents and their launch defaults.
MCP config files
When Token Intelligence indexes a project, Tempest writes MCP config files so every supported agent CLI finds the Atlas server:.mcp.json— read by Claude Code, Cline, Roo, Zed, and Windsurf.cursor/mcp.json.gemini/settings.json.kiro/settings/mcp.jsonopencode.jsonc
~/.codex/config.toml under [mcp_servers.atlas], and Goose gets ~/.config/goose/profiles.yaml.
Output pump
A reader thread per PTY batches output into theChannel (~16 ms / 64 KiB windows), keeping the frontend terminal live without flooding IPC.
7. Hephaestus: Process Isolation
Hephaestus (crates/hephaestus) is Tempest’s process isolation SDK. Each session can carry a SandboxSpec:
Platform enforcement
- Windows
- macOS
- Linux
- Job Objects with
KILL_ON_JOB_CLOSE, with optional memory and process caps plus CPU rate weight. - An ETW ProcessWatcher (Kernel-Process provider) assigns brokered descendants into the job. This requires admin or Performance Log Users membership and is silently skipped otherwise.
- An optional kernel driver (
\\.\HephaestusDriver, IOCTLs0x800,0x801,0x802). - Every unsandboxed session still gets a lifecycle job: kill-on-close plus ETW tracking plus a teardown sweep.
- Network policy is env-var proxy injection — a policy filter, not a containment boundary.
Network policy engine
A network policy engine runs as an in-process HTTPS CONNECT proxy (proxy.rs). Hostnames are matched against HostPattern entries — **.x suffix, *.x subdomain, or exact match — and a blocked match always beats an allowed one.
Configuration
The default mode isoff. Sandboxing is configured per project through Project Settings (Security group) or tempest.yml, with a tightened-only merge — a project can make its sandbox stricter than the default, never looser. See Security.
8. Database Branches (dbiso)
crates/dbiso gives each session an isolated PostgreSQL 16 database, built from the project’s real database via the bollard Docker API (image postgres:16-alpine).
Snapshot methods
basebackup—pg_basebackupagainst the source database.pgdump— logical dump; forced for pooler hosts such as*.pooler.supabase.com.- Schema-only — structure without data.
Build flow
1
Stage
A staging container
tempest-staging-<uuid8> runs with PGDATA=/pgdata — deliberately not the image’s VOLUME path, so the commit includes the data.2
Import
initdb, then import the snapshot.3
Prewarm
ANALYZE; CHECKPOINT so the first queries on a branch are fast.4
Tune
Write a tuned
postgresql.auto.conf: fsync=off, synchronous_commit=off, full_page_writes=off, wal_level=minimal, max_wal_senders=0, shared_buffers=256MB.5
Commit
Commit the container as image
tempest-db-base-<project-slug>-<uuid>.Branching and delivery
A branch runs as containertempest-<branch_name>, with the branch name derived from the session id (tempest-<8 chars>). The host port is the first free port in 15432..=65000, bound to 127.0.0.1, and readiness polls pg_isready for up to 15 s.
On success, DATABASE_URL, PGHOST, PGPORT, PGUSER, and PGDATABASE are written into the live session shell — PowerShell $env: or POSIX export — before the agent invocation runs, so the agent talks to the branch without any manual setup.
Registry and lifecycle
The registry at~/.tempest/dbiso.db tracks base_images and branches. Branches are deleted when their session closes, and an orphan sweep runs at startup. The Tauri commands are db_check_docker, db_check_ready, db_build, db_list_branches, and db_sweep_orphans. See Database branches.
9. Token Intelligence (Atlas)
Atlas is Tempest’s code-intelligence engine, shipped as the npm package@usetempest/atlas (v1.3.x, MIT). Its postinstall script, scripts/install-atlas.mjs, stages it into src-tauri/resources/atlas/, pruning to the current platform and refusing to stage an incomplete dist.
- Index database:
<project>/.tempest/atlas/atlas.db(SQLite, WAL mode). - Indexing:
start_atlas_indexspawnsnode <atlas>/dist/mcp/server-entry.js --init --path <project>, adding--semantic --model-cachewhen semantic search is enabled. The semantic model is a one-time ~25 MB MiniLM download viadownload_atlas_model. - Daemon: one per project, managed by
start_atlas_daemon/stop_atlas_daemonand tracked inatlas-daemons.json. - Agent access: agents reach the daemon through the MCP config files written at index time (see the spawn pipeline above).
atlas_explore, atlas_assets, atlas_asset_content, and atlas_semantic_search. The legacy tools — node, search, callers, callees, impact, files, status — remain callable through the ATLAS_MCP_TOOLS environment variable.
The Tempest UI reads the same graph through get_atlas_graph / atlas_query to power the Knowledge Base page. Separately, write_canvas_mcp_config registers a tempest-canvas MCP server that is served by Tempest’s own binary (launched with --canvas-mcp). See Token Intelligence and Knowledge Base.
10. Chat & Bridge Sidecars
Chat nodes on the Threads canvas have three backends:- BYOK — the Vercel AI SDK’s
streamChatruns in the frontend against 9 providers, using keys from the OS keyring. - CLI bridges — Node sidecars at
resources/{claude,codex,opencode,gemini}-bridge/bridge.mjs, spawned byclaude_stream_startand streaming NDJSON overclaude://{stream_id}channels. The Claude bridge drives Claude Code through@anthropic-ai/claude-agent-sdk. - Warp (experimental) — the
warp_chat/warp_model_infoRust commands over thewarpllm0.4 crate. Off by default.
11. Mobile Pairing & Remote
The mobile relay is a Rust WebSocket router inpairing_relay.rs. The transport is selected by the TEMPEST_MOBILE_TRANSPORT environment variable:
lan(default) — binds0.0.0.0:0and discovers the LAN IP via a UDP route probe.tunnel— a cloudflared quick-tunnel sidecar exposeswss://<random>.trycloudflare.com/ws, with readiness polled via the metrics/readyendpoint.
start_pairing_relay / stop_pairing_relay return a TunnelInfo:
Relay behavior: the desktop always dials its own router via loopback; each session supports exactly one laptop plus one phone; frames are forwarded blindly and bidirectionally, with __relay control frames and a __ping / __pong keepalive every ~25 s.
End-to-end encryption lives in TypeScript, not in the relay:
@tempest/crypto— X25519 keypairs, nacl secretbox, session key viabox.before, 8-hex fingerprint.@tempest/core— wire types and RPC methods:session.list/get/open/close/hop,queue.*,agent.send/interrupt/resize,permission.list/decide,protocol.hello,push.register; server events such assession.updated,agent.output, andpermission.pending.@tempest/transport—RpcPeer,wsChannel, E2EE frames{n, c}, exponential backoff from 500 ms to 30 s.
apps/relay is a Cloudflare Worker + Durable Object alternative router kept for a future switch — it is not the live path. apps/mobile is the Expo companion app. See Mobile.
12. Automations
Automations live in the SQLite tables described above. A Rust scheduler thread ticks every 60 s and emitsautomation:dispatch for due automations. The frontend then runs the headless agent: it builds the invocation from the agent manifest’s printArgs (plus modelArgs and autoApproveArgs) and runs it in a PTY with TEMPEST_SESSION=<runId> in the environment.
Run statuses move through dispatching → dispatched → succeeded or dispatch_failed. Prompt versions are stored per automation, so schedule edits never lose the prompt that produced a given run. See Automations.
13. Frontend Architecture
The frontend is React 19 on Vite (dev server on port 1420), 250+ TS/TSX files. There is no Redux or Zustand: 24 store modules insrc/store/ are built on useSyncExternalStore singletons. Notable stores include sessions, sessionManager, workState, messageQueue, automations, tabs, threads, threadMessages, quotas, islandNotifs, updates, agentAvailability, mobilePairings, mobileControlledSessions, and more.
sessionManager
sessionManager owns PTY channels, scrollback ring buffers (2 MB attached, 128 KB detached), and work-done detection:
- Precise hooks (default): the loopback agent-hook receiver plus 8 adapters.
- Fallback PTY heuristics: OSC sequences
1337,9;4,9,133, and777, title classification, DEC2004/1049, the Claude permission fingerprint, and timers — 5 s quiet, 300 ms dead zone, 12 s ceiling, 200-byte gate.
Panes and the Threads canvas
Sessions live either in the top tab bar or in a binary split tree (lib/paneLayout.ts). The Threads canvas (ThreadsView) supports node kinds chat, text, agent, terminal, file, image, media, site, and collapsed, laid out with cytoscape-fcose in a worker. See Threads and Agents.
Terminal rendering
A pool of 6 WebGL contexts serves xterm, with a canvas fallback, WSL-aware.14. Key Dependencies
Backend (Rust)
Frontend
15. File Layout
Directory purpose summary
Summary
Tempest pairs a React 19 frontend with a Tauri 2 Rust backend over three IPC mechanisms —invoke for request/response, Channel for streamed PTY output, and app.emit for events — with all persistence in a single SQLite database. Agents run in git worktrees under .tempest/, warmed by a small pool and torn down through a careful junction-aware cleanup sequence. Hephaestus confines each session per platform with honestly documented limits, dbiso gives each agent a disposable PostgreSQL branch, and Atlas puts a semantic code graph in front of every agent through MCP config files. Bridges, the mobile relay, and automations build on the same primitives, so one process model — spawn, confine, stream, persist, clean up — covers everything Tempest does.