00 · Ensemble overview

Ensemble is a shared workspace for a person and their agents: tasks, pages, projects, people, files, meetings and code in one place. The web app, desktop app, CLI and editor bridge share the same work context. It is source available under FSL-1.1-MIT.

This page maps what works today and its limits; each row links to the guide that owns the details.

Principles

1. Work keeps its context. A task links a project, repositories, people, files, meeting notes and skills; its page and run history stay with it.
2. The person chooses what comes in. Connecting an app imports nothing. Content arrives only through explicit search, attach, upload or import.
3. Several ways to work. The Hub assistant operates the app, assigned agents do research or code work, and the CLI and editors read the same context.
4. Model choice is explicit. Personal API keys, subscriptions on a paired computer, or included models with a monthly allowance.
5. Changes are reviewable. Apply and Undo, run permissions, publishing approvals, revision checks and run evidence each have a job. A chat reply is not proof that an action succeeded.

1. Where Ensemble runs

Hosted MCP OAuth is authorization-code/PKCE with DCR/CIMD, one-hour access tokens, refresh rotation by default and account-owned-space consent. Its catalog offers the same allowed capabilities through named tools; legacy editor keys and stdio retain their existing names. Connect your apps shows OAuth connections separately from manually created keys and disconnects the entire token family. Client/plugin distribution assets are in ensemblework/ensemble-integrations; vendor approval is separate (Context Bridge §4.1).

• The desktop app with an account shows the account itself, so it and the web are always in sync. Pairing a desktop or CLI does not replicate the hosted database into the computer: the paired computer claims jobs, answers Code and terminal requests and runs subscription calls; its included-model calls go through the hosted account (25). A local-only desktop app keeps its own database and never contacts Ensemble's servers (DESKTOP §1).
• Original source files are read from the computer and relayed without being kept as cloud originals. Code/Node editor buffers stay in browser memory; file lines a person explicitly quotes and sends are part of their chat history (16, 35 §8.18).
• Node's session inventory includes exact recorded node/crew usage and original-file references across each session's run chain. Its compact list opens originals beside the session without a work-description feed (35 §8.9).
• Owner-confirmed session deletion stops active work and removes the underlying coding agent's saved history on its computer before hiding it from session inventories. Project files stay; nodes request deletion through an owner-only chat confirmation (35 §8.9).
• Root release.json sets the version of every surface. Desktop updates are signed; OS code signing is not configured.

2. How work flows

Person adds work / explicitly imports content
    → tasks, pages, files and linked context
    → Hub assistant action OR an assigned research/code job
    → Apply / review / Needs me when required
    → saved result, run evidence and history

The scheduler runs product jobs (reminders, retention, device leases) and the person's assistant routines. Morning brief is one editable built-in routine (05 §2).

3. Accounts, spaces and profiles

4. Work surfaces

5. Assistant

The Hub assistant operates the app through typed tools. Its instructions stay the same through a chat; each message brings only its own context (date, view, open item, mentions), and records, playbooks and app details come from tools when needed. Built-in playbooks (apps/hub-api/src/assistant/skills/*.md) route each request to a small toolset; saved personal skills add instructions. On the person's own AI subscription, one chat is one session of that agent. Settings → Prompts shows every prompt Ensemble sends. 11 explains the loop; 34 maps every tool.

• Hub writes run at once by default (Settings → Assistant → "Just do it (undoable)"); Preview makes them wait. Connected-app writes, settings, workflows and agent assignments always wait for Apply.
• An interrupted workflow step with an unknown outcome is not replayed. Starting an import is not finishing it.
• There is no native email, Slack or Teams send. Calendar invitations can notify guests; some connected-item updates and vendor MCP tools write after Apply.
• Surface context is structured app state, not screenshots or DOM access. Neither the assistant nor Ensemble Node ever opens Ensemble's own web app in a browser (39). Credentials, account deletion, sharing permissions and folder trust are human-only.
• Connected-app content is read only when the person asks for remote content or gives an item link (assistant/apps.ts). The attachment button uploads into Files or lists saved Files and searches no connector.
• Files attached in chat, in Ensemble Node or to a task go to the model as the files themselves, whatever their kind; a provider that refuses one gets the request again without it. A person's own subscription agent gets them in its own input form. Ensemble's extracted text of a file is not given to models; plots on a task page arrive as settings and data (38).
• Replies, receipts and previews name records by title and link to them; ids stay in tool data and link targets, and show only when the person asks (11 §4.1).

6. Connected apps and imports

A catalog entry is a connection option, not a promise of native search, an importer or sync.

7. Core domain model (shared across modules)

apps/hub-api/prisma/schema.prisma and packages/shared-types/src/ are authoritative. Roles:

Content is scoped by the open space's userId; sharing policy limits what a guest may read or write. Credentials, reminders and personal settings never become shared with an item (28, 29).

Migration 20261006010000_account_data_lifetime adds SQL foreign keys that stop writes after account deletion. They are NOT VALID (existing rows are not checked) and absent from Prisma's relation model. Never accept generated migrations that drop them; src/workspace/constraints.integration.test.ts checks the allowed difference. This is not row-level security.

8. Models and credits

• Personal API keys are checked and stored encrypted per account. Provider discovery is cached with explicit refresh. Provider and model are always named together; effort levels are validated.
• Included AI defaults to GPT-5 mini and GPT-4.1 mini, with 20,000 credits per account per UTC month (DEFAULT_MONTHLY_CREDITS), within each environment's operator ceiling and a per-call reservation. Hosted dev/test uses Visual Studio Azure credits. Luna, Sol and Grok are not currently included; eligible deployments can be explicitly enabled later. Azure paid grounding is opt-in; free web search remains available (33).
• Included models work on the web, on Ensemble Node and on a paired desktop or CLI, from one list and one allowance per account. A local-only desktop app has none (it uses the person's own keys and AI subscriptions); no Azure key is ever copied to a computer.
• Subscriptions on paired computers are a separate source. External coding engines use their own local sign-in.
• Run usage separates reported tokens, included credits, estimated prices and unknown prices.

Details: 01 §6, 30, 33.

9. Assigned agents and Code

• Assignment creates a durable workspace job that the API or a paired computer claims and runs. The person picks only the agent (or Auto, the agent their Settings → Models names for the task's complexity) in one picker with model, thinking level and context window; where it runs decides the rest: work in a folder or checkout, or research and writing on the server. Branch, Git, instructions, sandbox and limits sit under More options. Continuing an earlier task resumes the coding agent's own session (one conversation across the tasks continued in it); the assistant lists sessions and assigns into one. Engines: Ensemble, Claude Code, Codex, Cursor, GitHub Copilot, Grok Build, OpenCode, Gemini CLI, Antigravity (30).
• Run profiles hold model, thinking level, context window, mode, sandbox, network and git permissions, destination and budgets. Engines: Claude Code, Codex, Cursor, GitHub Copilot, and through one ACP runner Grok Build, OpenCode, Gemini CLI and Google Antigravity (installed by Ensemble). Each coding agent's menus list the models its computer reports, with that model's own levels, windows and fast mode (Claude's 1M window and fast mode, Codex's levels and fast tier, Copilot's long context), and Settings shows Claude's and Codex's 5-hour and weekly usage. Conflicting jobs run one at a time, and a run that starts changing a folder another run on that computer is changing waits for it, works in a git worktree or goes alongside, as the person chooses (Run unattended waits). Needs me holds exact pending decisions; no mode needs a trusted folder, reading never asks, Review only asks once per other folder it changes, Run unattended never waits and works across the workspace, and only keys, system files, Ensemble's own code and limits the person chose are refused. A folder the person trusts is trusted in the engine too. Publishing uses saved approvals.
• A stop or restart keeps partial work and marks the interruption instead of claiming success; a paired computer that comes back reattaches a run that kept going and carries on one it lost to a restart, at most twice. Runs keep Results, Files (including those changed outside the run's folder) and Traces, with readable tool JSON, an exact raw view and copy, and incomplete-content warnings (02 §3.4).
• On the web, code review, editing, source control and the passkey-unlocked terminal go through a paired computer; ordinary accounts cannot reach the server's filesystem or terminal.
• OS sandbox: Seatbelt (macOS), bubblewrap or Landlock (Linux), the sandbox-runtime account (Windows).

Details: 05, 06, 16, 24, 25.

10. Data controls and measurement

• Settings → Data → Danger zone: type a scope-specific phrase, then confirm again. Deletion and its receipt are one transaction. Everything erases usage details, metrics, baselines and audit payloads; used credits stay charged (07 §6).
• IncludedCreditBalance is keyed by an HMAC of the account email, so erasing a workspace or recreating the account does not renew the allowance.
• Metrics uses recorded events and says when observations are too few. Included credits are metered apart from provider cost estimates.
• The Hub logs how signed-in people use it (screens, active time, named actions; never content) for the operator's dashboards (07 §1.3).

11. Not supported

12. Source map

Directory map: 17. Configuration, development and CI: 01. Setup: root README. Which docs move with which code: AGENTS.md. All guides: index.