Architecture Overview
You don’t need this page to use Orbit, but it explains the load-bearing facts that make the rest of the product behave the way it does. Every part of Orbit is arranged around one principle: the app you look at and the server that does the work are separate processes, so the interface is always available even when the engine is off.
The Electron app and the server are separate
Section titled “The Electron app and the server are separate”The Orbit desktop app is an Electron shell. The Orbit server — Express, the MCP endpoint, the agent process manager, the file watchers — is a separate sidecar process that Electron manages over HTTP on localhost:4853. It is not a child of Electron’s main process.
The practical consequence: the app loads and runs without the server. With the server off you can still browse every project and its status, read config and context files, decrypt and use the Vault locally, browse files, view the prompt queue, read completion logs, and start, stop, or restart the server itself. What needs the server is the live work: MCP tool calls from your AI chat, streaming agent output, the REST API for mobile, the tunnel, and spawning agents to run prompts.
System files live under ~/.orbit/
Section titled “System files live under ~/.orbit/”All of Orbit’s state is centralized in one directory: config.json (projects and settings), vault.json (encrypted secrets), queue.db (the prompt queue), and folders for global/ context, per-project locks/, logs/, and memory/. Path constants live in a single src/paths.js so nothing is hardcoded elsewhere.
The queue is SQLite
Section titled “The queue is SQLite”The prompt queue is a SQLite database at ~/.orbit/queue.db. This replaced an older flat-file approach and fixed a class of problems: prompts no longer re-execute on restart, rapid queue events no longer race, and dequeue has clean semantics. Any prompt left in a running state when the server restarts is reset to pending so it can be picked up again.
Remote access is tunneled and woken on demand
Section titled “Remote access is tunneled and woken on demand”Your phone reaches Orbit through a Cloudflare Tunnel that runs as an independent Windows Service, paired with a small Wake Receiver service and SSE keep-alive pings that hold streaming connections open over the tunnel. Mobile authenticates with a shared secret stored in the Vault. None of this depends on the server’s own lifecycle — the tunnel lives as its own service.