Architecture overview

Crewdesk has four parts. Each has one job, and only one of them holds credentials.

The Hub is the only part that holds credentials. The brain decides; the Hub checks and runs; your Mac runs the tools that touch your computer.

The clients

• The Mac app is a Tauri 2 app with a React interface. Its native core talks to the Hub and runs the local tools; the sign-in token stays in the native core and the Keychain and never enters the web view. Only the main window can call native commands, under a strict content security policy.
• The terminal client (crewdesk, Python) talks to the Hub over the same HTTP endpoints and live event stream as the app, and runs the same local tools by the same rules. It shares no code with the server.

Both run the tools that touch your computer (files, commands, git, browser) when the brain asks for them, under your permission mode and the sandbox.

The Hub

The Hub is the Crewdesk server: a FastAPI service with a Postgres database. It is the only part that holds credentials: your sign-in, your AMP link and your Enterprise Action Token. For each turn it:

• builds the context block (your connected apps, your organization, memories, relevant knowledge notes, the folder's instructions, permissions, policy and the chat's assistant) and signs it;
• runs the turn in the brain and streams it to your client;
• executes the brain's Hub calls (app actions, automation runs, web search, schedules), after checking permissions and policy;
• relays client calls to your Mac and their results back;
• records everything in the turn journal and the audit log.

It also runs your schedules, keeps your chats and files, and serves releases and updates.

The brain

The brain is a conversational CrewAI Flow with one task agent, deployed on CrewAI AMP. It decides what to do and calls tools; it never holds a credential and is tested never to import the Hub or read its secrets. It verifies its own replies' claims before they go out.

Each user's turns run either on the brain on AMP or in the Hub's own process. If the brain on AMP fails before it has shown anything, the Hub runs that turn itself.

CrewAI AMP

AMP provides the rest:

• the brain's deployment, and helper agents for web research, file analysis and CrewAI questions;
• your organization: the apps you connected (used through app actions, with your Enterprise Action Token), your automations, your skills.

More

• Turn lifecycle: how one message becomes a reply.
• Reliability: journal, reconnect, write-once.
• Latency: where the time goes.