System design
Architecture
Floating Keys separates what you see from what is true. Interfaces present state; Core owns it; workers carry out admitted runs. That separation is what lets the same Project mean the same thing on the web and on the desktop.
Three layers#
- Substrate — Core
- The single writer of Projects, threads, runs, policy, approvals, connector grants and receipts. Every client talks to the same versioned APIs.
- Projection — views
- Permission-checked presentations of that state for a role or task. A view can reorganize information but cannot store its own truth or widen access.
- Surfaces — clients
- The Floating Keys web and desktop apps, built from shared components so a workflow looks and behaves the same in both.
Surfaces
OpenSaddle Core
Work and knowledge
Web and desktop#
The design goal is one product across web and desktop: the same Projects, threads, runs, approvals and receipts. The local desktop app exists today. The signed-in browser workspace offers navigation and explicit previews; its hosted execution backend is planned. Desktop adds local powers, each behind an explicit permission and clearly labelled.
Shared in web and desktop
- Projects and threads
- Runs, approvals and receipts
- Connectors and Keys
- Library and results
Desktop only, with permission
- Local project folders
- Installed coding agents
- Native agent session history
- Device pairing and local runtime controls
- The browser never inherits desktop file access. Getting local files to the web will use a file you select or a separately approved device connection.
- Local runs and files need an explicit step to be shared before they appear on the web.
- Parity is measured by workflow: an approval or receipt means the same thing in either client.
The hosted beta design#
Today, Core runs as a trusted local service with local storage. That composition is not an internet-facing, multi-user service. The hosted beta is designed as separate pieces, each with its own identity and least privilege:
| Piece | Role | Status |
|---|---|---|
| Public site and waitlist | Marketing pages and email-confirmed waitlist only; cannot reach agents or connectors | Live |
| Account identity | Firebase Authentication for Google and emailed links; Twilio Verify for phone identity, separately from beta admission | Partial |
| Web gateway | Checks session, invitation, membership, limits and capability before calling Core; streams ordered events that survive reconnects | Planned |
| Private Core | Sole authority for Projects, threads, runs, policy, approvals and receipts | Planned |
| Durable database | Cloud SQL PostgreSQL in us-east1 for chats and agent state; Firestore already stores the waitlist | Planned |
| Model gateway | Server-side OpenRouter calls with membership, model and spend admission; no browser provider key | Planned |
| Isolated workers | Leased, checkpointed agent execution with time, spend and cancellation limits | Planned |
| Credential broker | Holds provider credentials server-side; never in the browser or prompt | Planned |
| Audit trail | Redacted, append-only record without prompt, file or token contents | Planned |
Extensions#
Extension packages can add descriptors for resources, actions, views, participants and evaluators. Locally, a package is signed, installed as an exact version and enabled per Project. Enabling it does not load code, connect accounts, grant scopes or start work, and adding a new coding agent still requires Core integration.
Status reflects September 2026. Planned items are design targets, not commitments to a date.