Concepts · Huddle

Workspaces

A workspace is the billing and access boundary. Every account gets a personal workspace by default, and you can create more for a team, a client, or a side project. Billing, usage limits, member roles, and audit logs are all scoped to the workspace — what happens in one never bleeds into another.

Workspace membership is explicit: you are a member, an admin, or not in the workspace at all. Admins can invite and remove members, manage billing, and install workspace-wide integrations.

Projects

A project lives inside a workspace and is the container for the files your team edits. Think of it as a repo or a working directory — it has its own file tree, its own git history, and its own list of sessions. Most teams have one project per codebase; some keep a scratch project around for pairing interviews and whiteboard sessions.

Sessions

A session is the thing that shows up on your screen. It binds a project to a set of participants, a Yjs document for every open file, a terminal PTY, and a chat thread. Sessions are long-lived by default — close your browser, come back tomorrow, your cursor is where you left it and the chat history is intact.

Nested sessions let a mentor spin off a side-session with one teammate inside a larger group huddle, which is handy when you need to break into pairs for a few minutes without kicking everyone else out.

Participants and roles

Everyone in a session has a role. There are three built-in ones:

Host — can invite, remove, and promote participants, and can end the session. Usually the creator.
Editor — can edit files, run terminal commands, and post to chat. The default for invited humans.
Viewer — can watch and chat but cannot mutate the document or the terminal. Good for demos and onboardings.

Agent participants (Claude, Gemini, Codex, or anything else connected over MCP) are modelled the same way — they have a role, and the role gates what tools they are allowed to call. An agent with viewer access cannot silently edit a file behind your back.

BYOK keys

Huddle does not sell inference. You bring your own keys for Anthropic, OpenAI, Google, DeepSeek, or any compatible endpoint. Keys live on your account (or the workspace, if you want a shared key paid for by the team), encrypted at rest with AES-256-GCM. The server decrypts just-in-time for each request, proxies to the provider, and forgets the plaintext.

This keeps the economics honest: your Anthropic bill is your Anthropic bill. Huddle charges a flat seat price regardless of how many tokens you move.

Realtime via Yjs

Every editable thing in a session — the file content, the presence cursors, the chat, even the sidebar layout — is a Yjs document. Yjs is a CRDT, which means two participants can edit the same buffer offline and their changes merge deterministically when they reconnect. No central locking, no conflicting branches.

The sync server (Hocuspocus) relays update vectors between participants and persists them to Postgres. When you open a file, you grab the latest snapshot from the server, subscribe to updates, and start emitting your own. The round-trip target is under 80ms on a well-lit connection.

You do not have to think about any of this in day-to-day use — it is the plumbing that makes two people typing in the same file feel like one person typing. But when you are debugging a sync issue, this is the model.