Skip to content
Floating KeysDocs

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

Web appInvite-only hosted betaPartial
Desktop appPlus permissioned local powersLocal

OpenSaddle Core

Projects and threads
Runs and approvals
Policy and receipts

Work and knowledge

Agent harnessesCodex, Claude CodePartial
Connectors and KeysOutside servicesPlanned
KRAIL knowledgeRepository-backedLocal
Diagram Requests flow down through Core; confirmed state flows back up to every client.

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
Diagram The design goal: shared workflows in both clients; local powers only where the desktop bridge and your permission are present. See availability for what is live.
  • 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:

Hosted composition, November 2026
PieceRoleStatus
Public site and waitlistMarketing pages, docs and email-confirmed waitlist only; cannot reach agents or connectorsLive
Account identityFirebase Authentication for Google and emailed links, separate from beta admission; phone sign-in awaits configurationLive
Web gatewayChecks session, invitation, membership and limits on every request; serves chat, Project files, file search and the MCP serverPartial
Remote MCP serverOAuth-approved, revocable access for outside AI tools, limited to chosen Projects and permissionsPartial
Private CoreSole authority for Projects, threads, runs, policy, approvals and receiptsPlanned
Durable storageFirestore holds the waitlist, account admission, hosted Projects and files; durable agent state is not hosted yetPartial
Model gatewayServer-side OpenRouter calls with account admission and usage receipts; no browser provider keyPartial
Isolated workersLeased, checkpointed agent execution with time, spend and cancellation limitsPlanned
Credential brokerHolds provider credentials server-side; never in the browser or promptPlanned
Audit trailRedacted record without prompt, file or token contents; today only connected AI tool activityPartial

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.