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 invited accounts free-model chat, private Projects with saved files, and connections for outside AI tools; hosted agent execution 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#
Core runs as a trusted local service with local storage; that composition is not an internet-facing, multi-user service. A hosted gateway now serves invited accounts for chat, Project files and connected AI tools, but it does not start Core runs. The full hosted design is separate pieces, each with its own identity and least privilege:
| Piece | Role | Status |
|---|---|---|
| Public site and waitlist | Marketing pages, docs and email-confirmed waitlist only; cannot reach agents or connectors | Live |
| Account identity | Firebase Authentication for Google and emailed links, separate from beta admission; phone sign-in awaits configuration | Live |
| Web gateway | Checks session, invitation, membership and limits on every request; serves chat, Project files, file search and the MCP server | Partial |
| Remote MCP server | OAuth-approved, revocable access for outside AI tools, limited to chosen Projects and permissions | Partial |
| Private Core | Sole authority for Projects, threads, runs, policy, approvals and receipts | Planned |
| Durable storage | Firestore holds the waitlist, account admission, hosted Projects and files; durable agent state is not hosted yet | Partial |
| Model gateway | Server-side OpenRouter calls with account admission and usage receipts; no browser provider key | Partial |
| 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 record without prompt, file or token contents; today only connected AI tool activity | Partial |
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 November 2026. Planned items are design targets, not commitments to a date.