Skip to main content

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:
The frontend owns UI logic and user interaction. The backend owns every OS-level operation: spawning processes, streaming PTY output, running git, managing worktrees, confining processes, and talking to Docker. Several side processes fan out from the backend: git worktrees under the project’s .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:
  1. invoke — request/response. Every command returns Result<T, String>; errors surface in the frontend as strings.
  2. 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.
  3. app.emit — app-wide event broadcasts.
Emitted events: 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:
The Rust side of the same flow:

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.
Other on-disk locations:

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:
  1. Junctions and symlinks are removed before remove_dir_all — otherwise the recursive delete follows the junction into the real node_modules.
  2. Removal retries in a loop on Windows while directory handles drain.
  3. git worktree prune clears dangling git metadata.

6. Agent Spawn Pipeline

The frontend pre-assembles the agent invocation and calls create_pty_session with:
  • session_id, cwd, rows, cols
  • optional command and args (a plain shell session omits both)
  • optional sandbox (a SandboxSpec) and policy (a SessionPolicy)
  • db_isolation, env (the tempest.yml env map), worktree_add
  • on_event — the output channel

Launch policy gate

Before any resource is acquired, the backend vets the launch: the agent must be in the project’s permitted_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 to powershell.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.json
  • opencode.jsonc
All of these are gitignored. Codex gets a global entry in ~/.codex/config.toml under [mcp_servers.atlas], and Goose gets ~/.config/goose/profiles.yaml.

Output pump

A reader thread per PTY batches output into the Channel (~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

  • 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, IOCTLs 0x800, 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.
Enforcement is honest about its limits: resource limits are enforced on Windows only, max_disk_write_mb is accepted but not enforced anywhere, and Windows network policy filters cooperating processes rather than containing them.

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 is off. 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_basebackup against 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 container tempest-<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_index spawns node <atlas>/dist/mcp/server-entry.js --init --path <project>, adding --semantic --model-cache when semantic search is enabled. The semantic model is a one-time ~25 MB MiniLM download via download_atlas_model.
  • Daemon: one per project, managed by start_atlas_daemon / stop_atlas_daemon and tracked in atlas-daemons.json.
  • Agent access: agents reach the daemon through the MCP config files written at index time (see the spawn pipeline above).
The default MCP surface is 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:
  1. BYOK — the Vercel AI SDK’s streamChat runs in the frontend against 9 providers, using keys from the OS keyring.
  2. CLI bridges — Node sidecars at resources/{claude,codex,opencode,gemini}-bridge/bridge.mjs, spawned by claude_stream_start and streaming NDJSON over claude://{stream_id} channels. The Claude bridge drives Claude Code through @anthropic-ai/claude-agent-sdk.
  3. Warp (experimental) — the warp_chat / warp_model_info Rust commands over the warpllm 0.4 crate. Off by default.
See Threads for the canvas itself.

11. Mobile Pairing & Remote

The mobile relay is a Rust WebSocket router in pairing_relay.rs. The transport is selected by the TEMPEST_MOBILE_TRANSPORT environment variable:
  • lan (default) — binds 0.0.0.0:0 and discovers the LAN IP via a UDP route probe.
  • tunnel — a cloudflared quick-tunnel sidecar exposes wss://<random>.trycloudflare.com/ws, with readiness polled via the metrics /ready endpoint.
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 via box.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 as session.updated, agent.output, and permission.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 emits automation: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 in src/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, and 777, title classification, DEC 2004/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.