Skip to content
mindsdbPublic

About

Minds-cowork frontend app - Desktop & Web

Resources

Stars

13 stars

Watchers

0 watching

Forks

Latest commit

 

History

914 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

MindsHub Cowork - Frontend

Ask DeepWiki

The Electron desktop app and web SPA for MindsHub Cowork — MindsDB's AI coworker platform. Cross-platform: macOS and Windows installers, and an unsigned Linux .deb (amd64 and arm64) built on every staging and prod run and on a PR with the build-linux-deb label, with no apt repository or update feed. It auto-installs the backend on first run, and provides a chat-based UI backed by a FastAPI server, with Minds integration.

The project is split across two repos:

Repo Purpose Language
mindsdb/cowork (this repo) Electron shell + React SPA TypeScript / React
mindsdb/cowork-server FastAPI backend — projects, conversations, agent orchestration Python

The frontend and backend are developed and released independently. At runtime, the Electron main process spawns cowork-server as a local sidecar and communicates with it over HTTP (127.0.0.1:26866). Both the UI and server support over-the-air updates — see Over-the-Air Updates.


Shared projects

On deployments with selective project sharing, a recipient sees shared projects in Projects with a read-only file view. Files are addressed by project UUID, so an owned project with the same name stays separate. Received projects show the last eight characters of that UUID on their cards and file views, with the full project ID in a tooltip, to distinguish equal names without revealing owner identities. Shared projects are excluded from task, schedule and move pickers, and send handlers reject them. HTML is shown as text; downloads use authenticated requests. The view rechecks access on focus and every 15 seconds, clearing its contents if access is revoked or a recheck gets no answer within 10 seconds. The server enforces these restrictions and must support /shared-projects/{id}/files; older deployments keep their existing project behavior.

Environments

MindsHub Cowork runs in several contexts. The React SPA is identical across all of them — only the shell and server lifecycle differ.

Environment Frontend Backend How to run
Local dev (Electron) Vite dev server on :5173 uv run cowork-server from sibling source dir npm run dev
Local dev (web) Vite dev server on :5173 uv run cowork-server from sibling source dir npm run dev:web
Packaged Electron (macOS/Windows) Bundled or OTA-cached React build cowork-server binary via uv tool install from PyPI Download from downloads.mindshub.ai
Docker (web deployment) Static files served by uvicorn cowork-server installed in /opt/venv docker build + docker run

Docker builds with a supplied dependency lock

For an exact server environment, put a hashed requirements.lock and Git source identities in server-lock/, then run:

docker build --build-arg COWORK_SERVER_LOCK=true -t cowork:locked .

The contract selects both server and anton, replacing the ordinary version/ref arguments. Registry packages install from exact hashed wheels before either app is imported. The installer checks the complete environment, source commits, dependency compatibility, and the PyJWT security floor. A missing artifact or a mismatch fails the build; it does not select a newer package. Change the supplied contract explicitly when updating dependencies.

Builds without COWORK_SERVER_LOCK=true select a server version or Git ref and consume that release's dependency contract, as described below. Git build backends, apt packages, and the frontend have separate build inputs.

Build Channels

The Environments table above covers how you run the app. A build channel (or "kind") covers which env it targets and where it stores its data. Every launch resolves to one of four kinds. src/main/channels.ts is the source of truth: its CHANNELS table maps each kind to a data home, API host, and default sidecar branch, and every other layer derives from it.

Kind User-facing name Data home API env Source Produced by
dev MindsHub Cowork (Dev) ~/.cowork-dev staging (api.staging.mindshub.ai) your working tree npm run dev — a runtime kind, never a shipped installer
preview MindsHub Cowork (Preview) ~/.cowork-preview staging the PR branch CI per-PR installer, for testers
stable MindsHub Cowork (Staging) ~/.cowork-stable staging staging CI rolling installer
prod anton ~/.cowork prod (api.mindshub.ai) main released installer from downloads.mindshub.ai

How the kind is decided (resolveBuildKind): a COWORK_BUILD_KIND env var wins if set; otherwise any unpackaged run is dev; otherwise the kind comes from the bundled build-config.json, and an absent config falls back to prod. So dev only exists when you run from source — it is never packaged into a distributed installer. CI stamps build-config.json with preview, stable, or prod when it packages those.

Ordinary local pack / dist produce a prod package. npm run pack and npm run dist bundle the checked-in build-config.json ({"buildKind":"prod"}) as-is — nothing stamps it — so the launched app resolves the prod kind and uses the ~/.cowork home and the prod API. Setting COWORK_BUILD_KIND for the pack does not make a non-prod package: the env var is never written into the bundle, and pack's plain electron-builder --dir also skips the per-kind bundle identity applied by scripts/run-electron-builder.mjs. So COWORK_BUILD_KIND=stable npm run pack yields a prod-identity bundle that still resolves prod at launch, while a staging VITE_MINDS_API_URL bakes the staging host into the renderer — a prod-home app talking to staging. A real non-prod package is a CI-only path (CI writes build-config.json with the target kind and runs the identity-aware packaging scripts). To exercise a non-prod kind locally without packaging, run from source (npm run dev = the dev kind), or launch the packaged binary with COWORK_BUILD_KIND set in its environment — that runtime env var does win in resolveBuildKind, overriding the prod bundle onto the non-prod home and keychain (pair it with a matching baked VITE_MINDS_API_URL so the API host agrees).

Things that trip people up:

  • "Staging" is the stable kind. The internal name is stable and its home is ~/.cowork-stable. Users see the label "Staging", and it targets the staging env. The name is historical.
  • Only prod talks to production. The other three kinds target api.staging.mindshub.ai. Keycloak follows the API host (api.X → auth.X), so their auth resolves to auth.staging.mindshub.ai. A bare dev run must never authenticate against prod. No build targets a dev API env — that realm is effectively dead.
  • prod keeps the historical paths. Its home is ~/.cowork and its Electron userData name stays anton, never re-set. Every other kind uses ~/.cowork-<kind> and its own userData name.

Where each channel saves its data

A channel's state is not all under one folder. It spreads across several locations, each keyed on the build kind so channels never clobber each other. Non-prod kinds keep their state under (or near) ~/.cowork-<kind>; prod keeps every historical global location, byte-for-byte unchanged. Paths below are for macOS.

Location (non-prod / prod) What lives there How it's isolated
Data home — ~/.cowork-<kind> / ~/.cowork SQLite cowork.db, .env, state.json, .master_key, and the projects/ files/ skills/ data-vault/ trees (full layout) COWORK_HOME
uv tool install — ~/.cowork-<kind>/uv/ / ~/.local/{share/uv,bin} The cowork-server + anton-agent Python sidecar (binary + venv). Beside the tools/ folder, never inside it: .cowork-release-contracts/, the release installer's rollback snapshots (install_release_server.py). uv reads every folder in tools/ as a tool, and uv tool list fails on one it can't name UV_TOOL_DIR / UV_TOOL_BIN_DIR
Server logs — ~/.cowork-<kind>/logs/ / ~/Library/Logs/anton cowork-server.log Non-prod redirects to the data home
Electron userData — ~/Library/Application Support/<app name> (prod = anton) Renderer localStorage (terms consent, UI prefs); on Windows/Linux the encrypted MindsHub refresh token (mindshub-refresh.bin, safe-storage) app.setName per kind
MindsHub refresh token — macOS: ~/.cowork-<kind>/refresh-token.dat / ~/.cowork/refresh-token.dat; Windows/Linux: userData mindshub-refresh.bin The Keycloak refresh token COWORK_HOME (macOS) / userData (Win/Linux) — see token-store.ts
OTA UI cache — non-prod: ~/.cowork-<kind>/ui-cache / prod: userData ui-cache/ Hot-swapped renderer bundle COWORK_HOME (non-prod) / userData (prod) — see ui-updater.ts
Shell-update downloads — ~/Library/Caches/anton-updater-{prod,stable} electron-updater's pending shell installer (prod + stable only; other kinds have no shell auto-update) Per-channel cache dir name, in the OS cache root — not userData
OS keychain — service cowork-oauth-<kind> / cowork-oauth Connector OAuth refresh tokens Per-kind service name
Legacy ~/.anton Pre-channel global config (.env, state.json); still read as a fallback and migrated into the prod home once prod only

The packaged bundle identity (appId, productName, icon, Linux package name) is also set per kind at build time (scripts/channel-identity.mjs), so non-prod builds install as distinct apps beside prod.

Everything under the ~/.cowork-<kind> home — the data home, uv install, and non-prod server logs — is identical on every OS; only ~ resolves differently. The three OS-managed locations follow each platform's convention:

Location macOS Windows Linux
Electron userData ~/Library/Application Support/<app name> %APPDATA%\<app name> ~/.config/<app name>
prod server log (getPath('logs')) ~/Library/Logs/anton %APPDATA%\anton\logs ~/.config/anton/logs
Shell-update cache (anton-updater-<channel>) ~/Library/Caches %LOCALAPPDATA% ~/.cache
Keychain / secret store Keychain Credential Manager (DPAPI) Secret Service (libsecret)

The fresh-install reset function below wipes all of these locations; use it as a checklist of everywhere state hides.

Caveat — standalone cowork-server defaults to prod. The Electron shell enforces the home split by injecting COWORK_HOME. A cowork-server launched outside the desktop app — a bare uv run cowork-server, or an Alembic command — inherits no COWORK_HOME and silently targets the prod home ~/.cowork. Set the target explicitly before any standalone DB or migration work: COWORK_HOME=~/.cowork-dev (or DATABASE_URI=sqlite:///$HOME/.cowork-dev/cowork.db). Back up the target .db first.


Quick Start

Local development

Both dev modes expect a sibling cowork-server directory (override with COWORK_SERVER_DIR):

parent/
  cowork/              ← this repo
  cowork-server/       ← github.com/mindsdb/cowork-server
npm install
# Electron no longer downloads its binary on install; fetch it once.
npx install-electron --no

# Build everything (main + renderer)
npm run build

# Run locally
npm start

Or jump straight into dev mode:

# Electron dev (hot reload for renderer)
npm run dev

# Web dev (no Electron, opens in browser)
npm run dev:web

In dev mode the server runs from source (uv run cowork-server), so local Python edits are picked up immediately.

Environment variables

Copy .env.example to .env and fill in any optional tokens (e.g. VITE_POSTHOG_MINDSHUB_MAIN_PROJECT_TOKEN for analytics). Vite auto-loads .env at build/dev time. The .env file is gitignored.

Dev Mode With Inspector

npm run dev:debug

This opens the Electron app against the Vite dev server and auto-opens Chromium DevTools in a detached window. It runs three processes concurrently:

  1. tsc --watch for main process
  2. vite dev for renderer (port 5173)
  3. Electron with VITE_DEV=1 flag

DEV_MODE (packaged app testing)

When testing a packaged build (npm run pack), the DEV_MODE variable in ~/.anton/.env controls which renderer the app loads:

Value Behavior
live Load from Vite dev server (localhost:5173) — requires npm run dev:renderer running separately
full Load the bundled renderer only — skips OTA cache entirely
(unset) Production mode — loads OTA-cached UI if available (prod builds only — see Over-the-Air Updates), otherwise bundled

To set it, add DEV_MODE=full (or live) to ~/.anton/.env. Remove the line to return to production behavior. When DEV_MODE is set, the OTA update check is skipped entirely.

Tip: If you build the app and it looks outdated, the OTA cache may be serving an older published bundle. Either set DEV_MODE=full to bypass it, or clear the cache: rm -rf ~/Library/Application\ Support/anton/ui-cache/current

Fresh-install reset (macOS)

To test first-run onboarding you need a true fresh-install state. App state hides in several places: the cowork homes (~/.cowork plus per-build-kind variants), the legacy ~/.anton home, the Electron userData dirs (one per build kind — prod's anton plus the Dev/Preview/Staging apps), the prod log dir, the per-channel shell-update caches (anton-updater-{prod,stable}), the uv-managed tool installs, and the macOS Keychain (connector OAuth tokens, one service per kind: cowork-oauth plus cowork-oauth-{dev,preview,stable}). This zsh function wipes them all — drop it in ~/.zshrc:

# Reset MindsHub Cowork to a fresh-install state: kills the app, wipes
# per-user state (API keys, chat history, .env, DB, OTA cache, keychain
# tokens), and uninstalls the uv-managed packages so the .app runs full
# onboarding on next launch.
# Usage: anton-reset [--deep]   (--deep also removes uv itself + shims)
anton-reset() {
  local deep=0
  [[ "$1" == "--deep" ]] && deep=1

  echo "About to wipe Cowork state for $(whoami) (HOME: $HOME)"
  (( deep )) && echo "Deep mode: also removes uv and ~/.local/share/uv"
  read -q "?Proceed? [y/N] " || { echo; echo "Aborted."; return 1; }
  echo

  # Stop the app (current product name, plus older builds)
  killall "MindsHub Cowork" 2>/dev/null
  killall Anton 2>/dev/null
  sleep 1

  # Per-user runtime state — all build kinds (prod uses ~/.cowork and the
  # 'anton' userData dir; dev/preview/stable use suffixed homes and their own
  # userData dirs). The homes also hold the macOS refresh-token.dat and the
  # non-prod ui-cache; the 'anton' userData dir holds prod's ui-cache.
  rm -rf "$HOME/Library/Application Support/anton" \
         "$HOME/Library/Application Support/MindsHub Cowork (Dev)" \
         "$HOME/Library/Application Support/MindsHub Cowork (Preview)" \
         "$HOME/Library/Application Support/MindsHub Cowork (Staging)" \
         "$HOME/Library/Logs/anton" \
         "$HOME/Library/Caches/anton-updater-prod" \
         "$HOME/Library/Caches/anton-updater-stable" \
         "$HOME/.anton" \
         "$HOME/.cowork" "$HOME/.cowork-dev" "$HOME/.cowork-preview" "$HOME/.cowork-stable"
  rm -f  "$HOME/Library/Preferences/com.anton.app.plist"

  # Connector OAuth tokens live in the macOS Keychain, not on disk — one
  # service per build kind (prod keeps the historical unsuffixed name)
  for svc in cowork-oauth cowork-oauth-dev cowork-oauth-preview cowork-oauth-stable; do
    while security delete-generic-password -s "$svc" >/dev/null 2>&1; do :; done
  done

  # uv-installed packages (the installer re-installs these on next run)
  uv tool uninstall anton anton-agent cowork-server 2>/dev/null

  # Deep clean: force the installer to bootstrap uv itself too
  if (( deep )); then
    rm -f  "$HOME/.local/bin/uv" "$HOME/.local/bin/uvx" "$HOME/.local/bin/anton"
    rm -rf "$HOME/.local/share/uv" "$HOME/.cache/uv"
  fi

  # Verify the key file is actually gone (the critical check)
  if [[ -e "$HOME/.anton/.env" || -e "$HOME/.cowork/.env" ]]; then
    echo "STILL THERE: a .env survived the wipe"
    return 1
  fi
  echo "GONE: all Cowork state removed. Relaunch the .app for fresh onboarding."
}

Web Build

The cowork SPA also runs as a plain web app, served by the same FastAPI backend. The renderer is shell-agnostic — there is one source tree, one component library, and two entrypoints.

Run dev (web)

npm run dev:web

Web development defaults to MindsHub UI off. In this build, Settings hides LLM Providers and Model Router, the composer hides model and reasoning-effort controls, and questions send model: null without a reasoning_effort override. The server uses its configured models and role-specific efforts. To configure providers and models in the development UI, run VITE_PLATFORM_UI=true npm run dev:web.

This boots both processes:

  1. The cowork-server FastAPI backend on 127.0.0.1:26866 (via uv run cowork-server from the sibling source directory).
  2. Vite dev server on localhost:5173, with BUILD_TARGET=web.

The dev server opens at http://localhost:5173/ (a small Vite middleware rewrites / → /index-web.html so the bare URL is canonical). API calls hit the FastAPI sidecar via Vite's /api proxy. Press Ctrl-C once for a clean shutdown — vite quiesces first, then the python child.

Build a production bundle

npm run build:web

Outputs to dist/renderer-web/ (separate from dist/renderer/ which is the Electron build). Drop this directory behind any static-file server and point its /api requests at a running cowork-server process.

Browser tab icon

Settings > Appearance lets web users upload a browser tab icon independently of the sidebar logo. PNG, ICO, SVG, and WEBP files must be smaller than 100 KB; a square image of at least 32 × 32 pixels works best. Changes preview immediately and persist through the settings API. Removing the override restores the page's original icon, including a deployment's custom branding. Desktop does not show this control, and the browser's home-screen icon is unchanged.

Deployment brand

A web build with MindsHub UI off (BUILD_TARGET=web and VITE_PLATFORM_UI not true) reads an optional brand from its own origin when the page loads. One build then serves any number of deployments, and a deployment changes its brand by serving different files, with no rebuild. Hosted web and desktop never load a brand: their HTML has no reference to it.

Path What it is
/brand/brand.js A classic script that only assigns window.COWORK_DEPLOYMENT_BRAND = { ... };
/brand/brand.css A stylesheet, loaded after the app's own CSS
/brand/<file> Any image the config names

The build marks the stock title, favicon comment and icon links with <!-- cowork-deployment-brand:start --> and <!-- cowork-deployment-brand:end -->. A deployment server can replace that entire region with its escaped title and literal icon links before sending the page. The markers appear only in web builds with MindsHub UI off. Without a replacement, the stock content stays.

The blocking brand script and title line follow this region, before the app's bundle, so the first render already has the brand. The script must never be async or defer. The stylesheet goes last in <head>. Cowork ships empty stock files in src/renderer/public/brand/, and scripts/spa_wrapper.py and the frontend image's nginx (scripts/nginx-frontend.conf) serve them, so a deployment that serves nothing of its own looks stock. A hosted deployment that serves its own brand mounts its files over the image's /brand/ folder. nginx sends them with Cache-Control: no-cache and an ETag, and answers a missing one with a 404.

scripts/spa_wrapper.py marks its HTML shell responses with X-Cowork-Spa-Shell: 1, including /, /index-web.html and deep client routes. Assets, API responses and redirects have no such header. A deployment proxy can use the header to distinguish the shell from other HTML. The build rejects missing, duplicate or reordered title and icon anchors, and markers already present in the source.

The hosted build adds the draft hosts to the page's CSP meta tag as well. That tag allows same-origin scripts, inline scripts, styles and images, so the brand's script, its title line, its stylesheet and its images load there too. Both changes are made at build time, and either order gives the same page.

Every field is optional. A field that breaks its rule is ignored, with one console warning, and the rest still apply. Unknown keys are ignored, so the format only ever gains optional fields.

Field Rule Used for
productName 1 to 64 characters after trimming The tab title and the places that name the product
skin { "id", "label" }: an id of lowercase letters, digits and single hyphens, up to 32 characters; a label of 1 to 32 characters A style listed first in Settings > Appearance > Style. brand.css styles body[data-skin="<id>"]
theme light or dark The theme a browser starts in
skinLocked true or false true keeps every browser on the default style: the brand's skin when its id is not a stock style's (normal, 8bit or custom), or Normal otherwise. Settings shows the style without a picker, and the corner and top-bar buttons switch only light and dark. A browser's saved style is kept and comes back once the lock is off. The theme stays each person's choice
logoUrl, iconUrl, appleTouchIconUrl /brand/<file>, with an optional ?v=<token> The sidebar logo, the tab icon and the home-screen icon

A person's own Settings win over the brand: a sidebar title, logo or tab icon set there is shown instead, and clearing the tab icon brings back the brand's. The style is the one exception while the brand sets skinLocked: true. If brand.js doesn't load, or doesn't set an object, the page shows stock names, styles and icons with no style lock, and logs one console error naming the file. A server that serves the brand should send Cache-Control: no-cache with an ETag, so a changed brand shows after a reload.

Platform abstraction

The cowork tree (src/renderer/cowork/) never touches window.antontron directly. All host-bridge access goes through src/renderer/platform/host.ts, which exposes:

Method Electron Web
getPlatform() / isMac() 'darwin' | 'win32' | 'linux' 'web' / false
getApiOrigin() http://127.0.0.1:26866 window.location.origin
openExternal(url) Electron shell.openExternal window.open(url, '_blank')
openPath / showItemInFolder / trashItem OS shell { ok: false, reason: 'unsupported' }
serverInfo / serverStart / serverStop IPC to main static {running: true, …}
oauthConnect(...) IPC PKCE loopback flow inline error (redirect-based OAuth not yet wired)

Affordances that depend on Electron-only bridge calls (server pill + power button in the sidebar, "Open in OS" / "Show in Finder" / "Move to Trash" buttons in the artifact views, the ServerOfflineHelpModal) are hidden when host.isWeb is true.

Web entry layout

src/renderer/
  index.html              # Electron entry (loads main.tsx)
  index-web.html          # Web entry (loads web-main.tsx)
  main.tsx                # Electron entry: App.tsx → CoworkApp (with onboarding gates)
  web-main.tsx            # Web entry: cowork SPA directly (no onboarding gates)
  platform/host.ts        # Shell abstraction (the only sanctioned bridge surface)
  cowork/                 # The shared SPA — never imports window.antontron

vite.config.ts branches on BUILD_TARGET=web: when set, rollupOptions.input points at index-web.html and outDir becomes dist/renderer-web/. When unset (the Electron path), behavior is byte-identical to before.


Architecture

src/
  main/                  # Electron main process (Node.js)
    index.ts             # Window creation, IPC handlers, menu
    installer.ts         # First-run installer for cowork-server (uv; plus git + Xcode CLT on git-channel builds only)
    server-process.ts    # FastAPI sidecar lifecycle (start/stop/health)
    server-updater.ts    # OTA server update (PyPI check, upgrade, rollback)
    ui-updater.ts        # OTA UI update system (fetch, verify, cache, rollback)
    updater.ts           # Update orchestrator (couples server + UI, shell notice)
    shell-auto-update-runtime.ts # Shell (Electron app) auto-update via electron-updater
    preload.ts           # contextBridge — exposes antontron API to renderer
  renderer/              # React UI (bundled by Vite)
    App.tsx              # App flow: loading -> setup -> onboarding -> cowork
    CoworkApp.tsx        # Main chat-based cowork shell
    pages/
      Setup.tsx          # Install wizard with step progress
      Onboarding.tsx     # LLM provider selection (Anthropic / Minds)
    cowork/              # Shared SPA — never imports window.antontron
    platform/host.ts     # Shell abstraction (the only sanctioned bridge surface)
    styles.css           # Full dark theme
    global.d.ts          # TypeScript types for window.antontron API
  shared/
    ipc-channels.ts      # All IPC channel constants
assets/
  icon.png / icon.icns   # App icon (gradient cyan-to-purple "A")

Key Design Decisions

  • FastAPI sidecar: The Electron main process manages the cowork-server Python FastAPI backend on 127.0.0.1:26866, installed from PyPI via uv tool install. The renderer communicates exclusively through this HTTP API — there is no PTY or terminal emulator.

  • Minds integration: The GUI replicates the /connect flow — lists minds via REST API, handles datasource selection (normalizes string/object refs), and writes non-credential config to ~/.cowork/.env. The MindsHub credential itself is never written there; see MindsHub credentials.

  • OTA updates: The React UI and the Python backend update over-the-air (coupled, auto-applied at boot) without a new installer; the Electron shell auto-updates on stable/prod via electron-updater, installing on relaunch. See Over-the-Air Updates.


IPC Reference

All channels defined in src/shared/ipc-channels.ts:

Channel Direction Purpose
install:check invoke Check if cowork-server is installed
install:start invoke Run the installer
install:log/progress/done/error send Installer status events
install:cancel invoke Cancel an in-progress install
install:cancelled send Confirms install was cancelled
settings:read/save/check-configured/validate invoke Settings & API key management
terms:accept invoke Record terms acceptance
usage-events:get/set invoke The agent's anonymous usage events switch (desktop Settings)
ui:update-check invoke Check for OTA UI updates
ui:update-apply invoke Download and apply a pending UI update
ui:update-status send Update status events (available/reloading)
server:restart invoke Restart the FastAPI sidecar
server:update-status send Server OTA update progress (PyPI check)
auth:get-access-token invoke Retrieve current access token
auth:logout invoke Clear auth session
oauth:cancel invoke Cancel an in-progress PKCE OAuth flow
mindshub:login invoke Start MindsHub OAuth login
mindshub:refresh invoke Refresh MindsHub token
mindshub:finalize invoke Pick the organization and hand the credential to the sidecar
mindshub:get-cached-token invoke Read cached MindsHub token
mindshub:list-orgs invoke Organizations this account belongs to
mindshub:switch-org invoke Change organization and refresh the session credential
app:ready send App finished initializing
app:get-platform/ui-version/open-external invoke Platform info, open URLs
shell:show-item-in-folder invoke OS shell operations
browser:ready invoke The UI shows the in-app browser; main may register it with the sidecar
browser:show/hide/set-bounds invoke Show a task's in-app browser over the pane's stage, park it while the stage is covered or under 200 px, or stop showing it; show and set-bounds answer whether it draws
browser:navigate/activate-tab invoke The person's back, forward, reload and tab switch
browser:take-over/hand-back invoke The person takes the browser, or hands it back with Done
browser:answer-login/answer-download/clear-data invoke Answer a site's sign-in prompt or a waiting download; Sign out of all sites
browser:state send A task's in-app browser changed (page, tabs, control)
browser:registered send The local server took the in-app browser's registration, so the UI asks /browse/status again

Provider validation is answered in main, not proxied to the sidecar

settings:validate is handled entirely in the main process. The IPC handler is in src/main/app.ts and the validators it calls (validateMinds, validateOpenAICompatible, validateAnthropic) live in src/main/provider-validation.ts. It never reaches the Python sidecar. The same logic also lives in the sidecar (cowork-server/cowork/services/providers.py), and that copy answers POST /api/v1/settings/validate-provider, which is the path the web build takes because it has no main process.

So a change to how a provider is validated has to land in both places. The two have drifted before: a fix that moved the MindsHub probe onto the free model landed in the sidecar and left main probing a paid one, and probing a paid model means an account with an empty wallet is told its working key is invalid.

The rule both copies follow: probe mindshub_air, whose usage draws the free included allowance rather than the wallet, so the result reports reachability and key validity instead of billing state. For openai-compatible and anthropic a model the caller asked for explicitly is sent as asked; provider: 'minds' always sends the probe model and ignores model on both copies.

Which copy a given build actually runs is decided by the onboarding screen, not by the platform alone. The MindsHub card renders a pasted-key form on web and Keycloak sign-in buttons on Electron (OnboardingScreen.tsx), and the pasted-key form is the only caller that passes provider: 'minds'. Since host.validateProvider reaches this IPC channel only under Electron, main's validateMinds has no live caller: on desktop the MindsHub path goes through mindshub:finalize, which provisions a key and probes no model. The validators a packaged build does run are the openai-compatible and anthropic ones, from the BYOK step. Main's MindsHub probe is kept in step with the sidecar anyway, because the drift is what caused this bug and a future caller should not have to rediscover it.

Rollout is not symmetric between the two. On prod the renderer bundle hot-updates at boot, while the Electron shell (so everything under src/main/**) downloads its own update in the background (shellAutoUpdateEnabledFor in src/main/shell-auto-update-rollout.ts, on by default for prod and stable) and only changes on the next relaunch — so each new UI first runs on the previous shell until the user quits. On stable only the shell moves: UI OTA is prod-only (otaUiEnabled in src/main/update-logic.ts). Either way a main-process change lands a relaunch later than a sidecar change, and how far a prod shell may fall behind before the UI says so is the "Supported desktop window" in docs/update-behavior.md. See Shell updates.


Minds Integration

The GUI provides a visual /connect flow:

  1. If LLM provider is Minds (from onboarding), credentials are pre-filled
  2. Lists available minds via GET /api/v1/minds/
  3. Handles datasource selection (auto-selects if only one)
  4. Fetches engine type via GET /api/v1/datasources
  5. Writes to ~/.cowork/.env:
    • ANTON_MINDS_URL
    • ANTON_MINDS_MIND_NAME
    • ANTON_MINDS_DATASOURCE
    • ANTON_MINDS_DATASOURCE_ENGINE
    • ANTON_MINDS_SSL_VERIFY
  6. Writes mind's system prompt to project cortex
  7. Auto-restarts the server to pick up new config

ANTON_MINDS_API_KEY is deliberately absent from that list — see below.

MindsHub credentials

The app writes no MindsHub credential to disk. Signing in gets you a Keycloak session (Authorization Code + PKCE, refresh token in OS secure storage, access token in memory), and that access token is what the sidecar presents to the gateway. MindsHub's /v1/authenticate/ accepts a JWT and an mdb_ key alike, picking the branch from the token's shape.

The sidecar is a separate process, so the value has to cross that boundary. It crosses over loopback rather than through a file: main holds it and PUTs it to /api/v1/runtime-credential/minds, which the sidecar keeps in memory and overlays onto its settings. src/main/minds-credential.ts owns that hand-over.

Four consequences worth knowing:

  • Every sidecar start needs a fresh hand-over. Nothing persists the value, so a sidecar that has just come up holds nothing and /health answers config_ready: false until main pushes again. The renderer paints that answer as "Connect a provider to start chatting", so a signed-in user reads a wiring gap as a billing prompt. The sidecar goes down far more often than a launch: an over-the-air update and its rollback, the sidebar's stop/start, and the installer's first start on a fresh machine. Wiring the push into each of those is how one gets missed, so it hangs off the single function they all call. src/main/app.ts registers handOffMindsCredentialToStartedSidecar with setServerStartedHook, and startServer awaits it after every successful start (src/main/server-process.ts). That hook also releases the wake barrier below, because a sidecar restarting mid-hand-over is exactly when a turn is parked waiting for one. It is awaited rather than fired off, because callers read /health as soon as startServer resolves. Sign-in and the token-refresh tick push on top of that, since both produce a new credential without restarting anything.

  • A wake can hold your next message for up to 12 seconds. Sleeping past the access token's ten-minute life leaves the sidecar holding a JWT the gateway will reject, so a resume near expiry arms a barrier over POST /api/v1/responses and /responses/answer until the refreshed value has been accepted. src/main/minds-resume-gate.ts owns it. Three things bound the damage. It waits at most MINDS_RESUME_READY_TIMEOUT_MS (12s) and then cancels the request, which stays under the renderer's ~13s stranded-reservation reap so a held turn fails visibly instead of vanishing with its thinking placeholder still on screen. It only arms when the sidecar's /health says a resolved required planning or coding role actually uses the runtime MindsHub credential, so direct OpenAI and Anthropic turns are never held. And Stop is deliberately outside it. An unknown or unreachable health answer is treated as "needs it", because an older sidecar cannot prove otherwise.

  • A key you supply yourself goes to the OS keychain, not to .env and not to the sidecar's settings table. It wins over the session credential while it is set. mindshub:set-user-key is the IPC channel that carries it.

  • Signing out takes the credential away, and an install upgrading from a build that minted a per-device key is signed out once so that key can be revoked while the session still names the organization it belongs to.

  • Sign-out answers as soon as the credentials are gone. It also restarts the sidecar, to flush provider objects that might still hold the previous user's credential in memory, and that restart runs in the background rather than holding the reply: the stop and start together are capped near 190 seconds, and longer behind a start already in flight, which is far past what anyone waits in front of a confirm dialog. src/main/sign-out-restart.ts owns it and is single-flight. Signing the next user in waits for it, so their credential is not handed to a sidecar the restart is about to take down, and boot routing answers "not configured" until it settles.

A sidecar you start by hand, outside the app, therefore has no MindsHub credential. Set ANTON_MINDS_API_KEY yourself with a key minted in the console if you need one for that.

The MindsHub hub routes

Nothing under /api/v1/hub/* calls MindsHub directly. The renderer calls its own sidecar, which forwards on the caller's behalf. /api/v1/hub/usage/ carries the free MindsHub Air allowance, the balance, the period's credit spend and auto top up state, and backs Settings → Usage and the stopped-task cards. /api/v1/hub/workspaces/ answers the MindsHub workspace listing and backs the workspace selector described in the next section.

MindsHub's ingress allows the console origins and no Cowork host, and a per-PR Cowork host cannot be added to a static allow-list. A direct call would therefore work in the packaged app (webSecurity is off there) and fail in the web SPA. Going through the sidecar is what lets both hosts read the same thing, which is why Settings → Usage is offered on the hosted build and not filtered off it.

The credential goes in X-MindsHub-Authorization, not Authorization. The main process overwrites Authorization on every loopback request with the sidecar's own token, so the Keycloak JWT cannot arrive under that name. The exceptions are requests from the document preview frame, from frames inside it, and requests with no frame: the main process adds no token to those (src/main/document-preview-guard.ts).

Only /api/v1/hub/usage/ and the /api/v1/hub/workspaces/ routes send X-MindsHub-Authorization. The sharing reads, /api/v1/hub/teams/ and /api/v1/hub/people/, send none, because cowork-server answers them from the Authorization the gateway validated (cowork.principal.caller_bearer).

The MindsHub workspace selector

A bordered control at the bottom of the sidebar, docked with the account row, names the MindsHub workspace you are working in and opens a menu listing every workspace you can use with a check on the active one. A MindsHub Workspace is an org-internal container that owns MindsHub resources (API keys, artifacts, model entitlements) and lives in MindsHub. It is not the working folder this app also calls a workspace, which is why the stored key and the code are named hubWorkspace throughout. There is no create entry: workspaces are created in the console, and the last row deep-links there.

One workspace draws nothing. Everyone starts in Default on their own, and a switch offering only the place you are already in asks a first-time reader to work out what a workspace is for no benefit. The control appears once the organization has a second one, which is the first moment "which workspace am I in" has more than one answer. The count is taken on the rows the sidecar offers, which already exclude archived workspaces except the one you are currently in. So a live workspace beside an archived one counts as one and draws nothing, and a live workspace beside the archived one you are in counts as two and does draw. The second case is deliberate: the control is the only way out of a workspace that was archived under you.

It sits at the bottom rather than the top of the rail. A workspace is a container inside the organization, not what a reader starts a task from, and the top of the rail is where the first task begins. It is not a group inside the account menu either, which is where it shipped first. Two things were wrong with that: the current workspace was invisible until you opened the menu, which is the opposite of what a scope indicator is for, and the account menu is where the organization selector lands, so two levels of one hierarchy would have nested inside a menu about identity.

State Control
The gate is off absent
The read has not come back yet absent
MindsHub could not be reached absent
Gate on and reachable, but the org has no workspace absent
One workspace, with nowhere to move to absent
One live workspace and an archived one you are not in absent
One live workspace and the archived one you are in shown, so you can leave it
Two or more, gate on shown

A read that has not settled is retried three times over about forty seconds and then left alone. The renderer can mount before the sidecar is listening, so one attempt per session made an ordinary cold-start blip hide the control until the app was relaunched. Two shapes count as unsettled: a thrown transport error or 5xx, and a 200 that says the gate is on but MindsHub could not be reached, which is how the sidecar reports a failed hop to MindsHub in band. A 404 is not retried, because a sidecar without the route will not grow one, and neither is a gate-off answer, because it is definite.

After a successful desktop organization switch, useMindsOrgs notifies useHubWorkspaces to discard the old listing and read the new organization. Late reads and workspace switches from the old organization cannot replace it. If leaving an archived workspace hides the focused selector, focus moves to the sidebar's Settings button. Focus already moved elsewhere stays there.

The switch is a server-side Statsig gate, not a build flag. MindsHub declares authorization_ui in its own configs/statsig_gates.json, evaluates it with its server SDK, and reports the verdict; cowork-server reads it and passes it on. So one gate governs the console and this app, and turning the surface off does not need an installer. That matters here specifically: src/main/** reaches users only through a new installer, so a CODING_MODE_OPTIONS_ENABLED-style preload flag could not be switched off in an incident. COWORK_HUB_WORKSPACES_FORCE_ON=true on the sidecar is an ON-only development override for walking the surface where no rule targets you.

Picking a workspace changes what this app shows, not what a turn is billed to. Attribution rides the credential a turn presents, and neither credential carries a workspace today.

Which organization the session uses

The access token's activate_organization claim decides whose credits a turn spends. On web it also partitions tasks, settings, and storage; desktop's local database is not organization-filtered. The current server auth path resolves that identity for each request. A turn already in flight keeps the scope it started with; later requests use the refreshed credential's organization.

Packaged desktop sign-in still runs through the Electron bridge and main process. Main owns the Keycloak session and hands its access token to the sidecar at /api/v1/runtime-credential/minds. Its selection rules live in src/shared/minds-orgs.ts, and the Keycloak calls live in src/main/minds-auth.ts.

Three things decide it, in order:

  1. A pick the person made — stored in state.json under preferences.mindsOrganization, keyed by the Keycloak subject so one machine signed into a second account does not inherit the first's choice. Only a pick is ever written: the onboarding picker and the account menu. Where a sign-in happens to land is not recorded, because the key is a single slot and an automatic write to it would replace whatever a person chose — possibly another account's, which no guard keyed on the stored value can even see.
  2. Company organizations rank ahead of the personal one, which Keycloak names personal_<userId>. Within each group the order Keycloak returned is kept, so "the first company organization" means the same thing on every sign-in.
  3. The claim the token already carried, which used to be the whole answer. That is how turns ended up billed wherever a console tab happened to be pointing.

ensureActiveOrg switches only when the answer differs from the claim, so an account with one organization makes no extra round-trip.

Changing it later happens in the account menu's Organization group (components/UserMenu.jsx, hook hooks/useMindsOrgs.js). It lives there because an organization is who pays. A MindsHub workspace is a container inside one, which is why its picker is its own control lower down the rail rather than a group in this menu.

Desktop lists and switches through mindshub:list-orgs and mindshub:switch-org. Main switches the Keycloak session, refreshes its token, and hands that token to the sidecar before it reports success. A later failure switches back, and main stores the preference only after the hand-over succeeds.

Web lists and switches directly against Keycloak through public-client; cowork-server has no organization-switch write proxy. The selector has no product or authorization feature flag, but it stays hidden until the same-origin server reports organization-boundary protocol v1 as both enforced and enabled. That compatibility handshake lets the transition-aware client deploy before old browser bundles are rejected and the picker is exposed. The menu shows switch rows only when the listing contains multiple organizations. Names also come from the listing, including the generated label for a personal organization; the token claim supplies only its id. An unsuccessful read times out after ten seconds, keeps the rows hidden, and retries after 2, 8, and 30 seconds.

After Keycloak accepts the web switch PUT, Cowork forces keycloak.updateToken(-1). A confirmed switch, or any result where the PUT may have committed, clears the settings and composer-draft caches and hard reloads every open same-origin Cowork document. On canonical web, settings and drafts are namespaced by the initial token's subject and organization as well as the durable transition epoch. That keeps a close, external Keycloak switch, and reopen from hydrating the former organization's data; the epoch also means a late old-document write cannot overwrite or delete the current value. A switch request that does not settle within ten seconds is treated as possibly committed. Known refusal statuses 400, 401, 403, and 404 leave the current page and organization in place.

Web Locks serializes switch attempts across tabs, and a local-storage marker blocks ordinary token reads from the moment the PUT starts until refusal or reload. Each document remembers the epoch in which its JavaScript heap started and rechecks it after bfcache restore. A browser without exclusive Web Locks or writable same-origin storage refuses before sending the PUT.

Mandatory reloads are budgeted. A tab that reloads three times inside ten seconds did no work in between, which is a loop rather than a person changing organization, so the fourth reload does not happen. That tab has already cleared its tenant caches and it goes on refusing access tokens, so it fails closed and visibly instead of reloading forever.

Every authenticated browser API request also carries X-Cowork-Expected-Organization-Id, pinned to the organization in which that document started. In MindsHub mode, cowork-server always enforces this boundary for browser JWT requests. A missing header from a pre-protocol bundle receives HTTP 426; a malformed header or one that differs from the gateway-resolved organization receives HTTP 409. Both responses require a reload. This closes the gap between the token check and actual request dispatch, and it also catches a Keycloak session change made from another origin. The client clears tenant state and reloads before consuming such a response.

Canonical-web attachment and project-file bytes use that same authenticated fetch path, then render, open, or download from a checked Blob URL; a native resource navigation cannot attach the expected-organization header. Project HTML preview URLs are the exception: the server mints a short-lived preview token bound to the requesting tenant scope, so a token requested in one organization returns no content after the principal changes. Private artifact serveUrl routes are unavailable in MindsHub mode and therefore are not part of the organization-switch protocol.

The initial four-stage rollout was superseded by cowork-server#524, promoted to main through #489 on 2026-09-13. It removed COWORK_ORGANIZATION_BOUNDARY_MODE and enabled the picker in the dev, staging, and production overlays. There is no audit setting that can reopen the boundary. The server still logs organization boundary: for refused requests.

COWORK_ORGANIZATION_SWITCH_ENABLED=false remains the deployment control for hiding switch targets without weakening enforcement. The capability handshake still requires MindsHub mode and enforced identity before advertising switching. Verify every deployed replica and authenticated browser behavior when checking a rollout; an enabled source value alone does not prove the deployed state.

Shared-resource permissions come from the server

Hosted Cowork never derives project, skill, project-memory, or instruction permissions from a role in the renderer. Each resource response carries its allowed actions, and a missing capability fails closed: the corresponding rename, edit, disable, or delete control stays unavailable until a fresh server response explicitly allows it. Packaged skills and the General project therefore remain immutable according to the same response contract. The packaged desktop app keeps its local-owner fallback because its files have no organization principal or server-owned capability record.

Attribution is display metadata, not authority. The UI may name the immutable creator and current last editor, but only the capability fields decide whether a control is enabled. Protected deletes wait for the server before removing anything from local state; a refusal keeps the resource, selection, tasks, drafts, and route in place. Successful protected mutations force a fresh read generation, superseding any coalesced pre-mutation request so stale attribution or capabilities cannot overwrite the response that just succeeded.

The server ships first. Because the hosted client fails closed on an absent capability, a renderer that reaches hosted users before cowork-server#417 is deployed reads every response as carrying no capabilities, and rename, delete, edit, and disable go unavailable for everyone, creators and organization admins included. Deploy cowork-server#417, confirm hosted responses carry capabilities, and only then deploy the renderer.

A person can share their own skill with everyone, read-only, or stop sharing it. The skill's page and its Edit form show that "Who can use it" control only when the skill's capabilities.canShare is true; a change goes to PUT /api/v1/skills/{skill}/sharing (the Edit form sends it after saving the rest). Creating a skill (the Write form, Upload and the chat's skill card) asks the same question, with Only me preselected, only when the skills list's top-level canShare is true, and sends the answer as shared. The chat's skill card creates a skill shared with everyone without the chat's project scope, since a reader applies the creator's scope. Unlike the other capabilities, a missing canShare is false on every build, desktop included. cowork-server grants it only where each person keeps their own skills, so hosted Cowork, the desktop app and a deployment whose skills everyone already shares never show it. Deploy cowork-server first: against an older server the renderer shows no control and sends no shared field.

The Connections page reads the same way. Each connection carries managed and shared, and the page keys its Reconnect, Remove and read-only note on them; a missing field keeps every control, and cowork-server's 403 enforces the rule when a change is refused.

MindsHub mode, single-tenant mode, single-user mode and MindsHub UI

Two separate switches decide what the app shows: how the cowork-server it talks to keeps tenants, and whether the web build carries MindsHub UI. Neither implies the other. The cloud build turns both on; the self-hosted VM runs single-tenant mode with MindsHub UI off.

Name Set where How the app reads it What changes
MindsHub mode cowork-server COWORK_TENANCY_MODE=org: many organizations, many people /health's org_mode, read at boot (host.checkConfigured) into src/renderer/lib/orgMode.ts (useOrgMode). A web build that can't reach /health at boot takes itself for MindsHub mode (App.tsx). Artifacts are addressed by project and id and shared through PUT /api/v1/artifacts/workspace/{project}/{id}/access; desktop's /publish routes (version history, Stop sharing, Update) are hidden; sharing inside the org can turn on (below).
Single-tenant mode cowork-server COWORK_TENANCY_MODE=local with COWORK_TRUST_IDENTITY_HEADERS=true: one organization, many people, each with their own space org_mode false No sharing inside the org: an artifact is shared with people by email, and a skill offers "Who can use it" (Only me, or Everyone (read-only)) where its capabilities.canShare, or the skills list's canShare for a new skill, is true.
Single-user mode cowork-server COWORK_TENANCY_MODE=local without trusted identity headers: the desktop app org_mode false No sharing inside the org; artifacts share by email.
MindsHub UI the web build flag VITE_PLATFORM_UI=true, baked in by src/renderer/vite.config.ts and read as PLATFORM_UI (src/renderer/lib/deployment.ts). The cloud image sets it (Dockerfile.frontend, .github/workflows/build-deploy.yml). PLATFORM_UI MindsHub's model, provider and workspace controls, the organization menu and its landing (lib/orgLanding.js), and Public as a first share's starting choice.

Sharing inside the org

In MindsHub mode, when GET /api/v1/skills/sharing-capabilities answers enabled: true, skills and artifacts are shared with Only me, Everyone at ‹org›, or Specific teams and people. An artifact also takes people outside the org by email, a password, or a public link. The org's default team ("All members") is never listed: an audience that names it reads as Everyone at ‹org›.

  • Who may pick Everyone at ‹org›: canShareSkillsOrg (skills.share_org) for a skill, canShareArtifactsOrg (artifacts.share_org) for an artifact. Without it the card is grayed with "Only admins can share with everyone in the organization" for a skill. Every built-in MindsHub role holds artifacts.share_org, so for an artifact only a custom role that withholds it grays the card, with "Your role can't share with everyone in the organization". MindsHub refuses an artifact save that newly sets everyone without artifacts.share_org, whichever client sends it. cowork-server answers that refusal with 403 {"detail": "<the reason>", "code": "share_org_required"} on PUT .../access, POST /publish, and POST /publish/update, and PUT .../access answers its own check of the same that way, before anything publishes. The app shows the reason once, as it is, with no "Sharing failed:" or "Update failed:" in front and no Try again, since asking again gets the same answer: under the Share panel's choices, and in a toast on the Artifacts page, whose card keeps its state (publishRefusalMessage in components/artifact/publish/publishErrors.js; the code is SHARE_ORG_REQUIRED_CODE in lib/sharingContract.js).
  • When MindsHub couldn't be asked: permissionsKnown: false means the can… flags say nothing, so a locked control reads "Couldn't reach MindsHub" instead of a permission lock, and the artifact Share panel and the Skills page offer Retry. teamsKnown: false means skills shared with the caller's teams are left out of the list; the Skills page says so, with Retry. Such an answer is never cached.
  • Always on: a skill shared with everyone or with a team can be part of every task for everyone it reaches. The switch on a skill shared with everyone needs canShareSkillsOrg; on a team skill it needs edit rights (its owner, a member of one of its teams, or an admin). People named one by one always use a skill on demand.
  • Waiting on reads: the artifact Share panel waits for the capabilities read and, in MindsHub mode, for the access route. An artifact card there doesn't say who a restricted artifact reaches: cowork-server answers its orgAllowed, ownerOnly, allowedTeamIds, and allowedUserIds as null, and lib/sharingContract.js's readArtifactAudience reads a null as unknown, never as an empty audience or "Only me". A failed read, or an access answer with nulls, offers Retry and saves nothing. Until the access route answers, the Share button and the panel title read "Share", never "Shared", a draft seeded from the card picks nothing and can't be saved, and the Artifacts list says "Restricted. Open Share to see who can open the link." The Skills page waits for the capabilities read too, and a failed read shows "Couldn't load the sharing settings." with Retry instead of the list.
  • The people directory: GET /api/v1/hub/people/ lists the org's members, the caller left out, up to MindsHub's cap; truncated: true says there are more. ?ids= names stored people and ?emails= finds members past the cap. Typing filters the loaded list and asks nothing. An address the list has is that person. One a list over a minute old, or a capped one, doesn't have reads "Add …", with no claim about the org. Adding it (Enter, Tab, a comma, or a click) holds it as "Checking…" while the app reads the whole list again (GET /hub/people/, for a list over a minute old) or asks MindsHub about the address (?emails=, past a capped list's end, also once a list read again comes back capped). Then it is added as that member, added as an outside email ("Outside ‹org›"), or reported "Not added: … (not in ‹org›)" where only people in the org may be named; a check that gets no answer leaves it in the input with its reason, and Enter checks again. Only an address a list under a minute old answers for (the list is complete, or MindsHub has answered for that address) reads "Invite … (outside ‹org›)" or "Only people in ‹org›" while it is typed. Addresses are checked with lib/emailAddress.js, the rule MindsHub's lookup applies; one cowork-server still refuses (400 invalid_email) is reported as not an email, and the rest of its batch is asked again. A stored id cowork-server refuses as no UUID (400 invalid_id) reads as an Unknown person and is never asked about again; the rest of its batch is asked again.
  • When MindsHub says no: a people or teams read that MindsHub refused (403 or 400 mindshub_refused) or throttled (429 mindshub_throttled) says so in its own words, never as an outage. A refusal reads "MindsHub refused to list your organization's people" (the directory), "MindsHub refused to name some people." (stored people) or "MindsHub refused to list your teams.", with no Retry, since asking again gets the same answer; the next open asks again. A throttle reads "MindsHub is limiting requests. Try again in a minute.", with Retry where the field has one, and nothing asks again on a timer. An outage keeps its "Couldn't load …" line, and Retry where the field has one. lib/sharingContract.js's readMindsHubFailure reads the code, and lib/orgSharing.js's mindsHubFailureText picks the line.
  • The organization's name: "Everyone at ‹org›" reads the organization's name from the same two places as the account menu (useSharingOrgName, sharingOrgName in lib/orgSharing.js). The app's own organization list (useMindsOrgs' active organization) gives its display name. The browser reads that list only where GET /api/v1/capabilities/organization-switch answers enabled (COWORK_ORGANIZATION_SWITCH_ENABLED). Without the list, the access token's activate_organization claim gives the organization's Keycloak name, which can differ from its display name: it can be a slug, and for an organization MindsHub's staff created it is an id, staff-org-<uuid>. With no name known, it reads "Everyone in the organization": MindsHub UI off, the token not read yet, a personal organization (one named personal_<the viewer's id>), or a claim that names the organization only by an id: staff-org-<uuid>, or personal_<uuid> for someone else's personal organization. So where switching is off, the label of such an organization stays generic.

Which file owns what, under src/renderer/cowork/:

File Owns
lib/sharingContract.js (.d.ts) The wire field names, one reader per answer field and one builder per request body, LOAD_STATUS, the bounds the app mirrors, and the refusal and lookup codes
lib/orgSharing.js What the capabilities allow (isOrgSharingOn, orgShareLockReason, skillAlwaysOnLock), the audience choices and their copy (AUDIENCE_CHOICE, "Only me", "Specific teams and people"), the default team, and the Share or Shared state
hooks/useOrgSharing.js The reads, once per organization: useSharingCapabilities, useMindsHubTeams, useKnownPeople, useOrgDirectory, and the organization's name (useSharingOrgName)
api.js fetchSkillSharingCapabilities, setSkillAccess, fetchMindsHubTeams, fetchMindsHubDirectory, fetchMindsHubPeopleByIds, fetchMindsHubPeopleByEmails
components/AudiencePanel.jsx, AudienceOption.jsx The cards both panels use (onlyMeOption, everyoneOption, specificOption)
components/RecipientField.jsx, hooks/useRecipientTokens.js The teams, people and emails picker, and how a typed or pasted address resolves
components/RecipientRows.jsx The read-only rows of who something is shared with
components/LoadStatus.jsx Loading, a failed read, and the Retry notices
components/SkillAudienceFields.jsx, SkillShareMenu.jsx, SkillModal.jsx, SkillDetail.jsx, views/SkillsView.jsx, views/useSkillSharing.js Skills
components/artifact/publish/AccessChooser.jsx, PublishMenu.jsx, useArtifactShareState.js, usePublish.js, publishErrors.js, components/artifacts/ArtifactStatus.jsx Artifacts

Sharing wire names

Requests take snake_case and answers come back camelCase only; lib/sharingContract.js reads no other spelling.

Request field Answer field Means
org_allowed orgAllowed Everyone at ‹org›
allowed_team_ids allowedTeamIds Teams, by MindsHub team id
allowed_user_ids allowedUserIds People in the org, by MindsHub user id
allowed_emails (MindsHub mode), emails (desktop POST /publish) accessEmails People outside the org, artifacts only
owner_only ownerOnly Only me, artifacts only
always_on alwaysOn Part of every task, skills only
notify: { user_ids, emails } none The individuals a save adds whom MindsHub emails

GET /api/v1/skills/sharing-capabilities answers enabled, canShareSkillsOrg, canWriteSkillsOrg, canShareArtifactsOrg, permissionsKnown and teamsKnown. It names no organization.

Sharing limit Value Mirrors
MAX_IDS_PER_LOOKUP: ids per GET /hub/people/?ids= batch 50 MindsHub's MAX_IDS_PER_LOOKUP
MAX_EMAILS_PER_LOOKUP: addresses per GET /hub/people/?emails= batch 50 MindsHub's MAX_EMAILS_PER_LOOKUP

The per-rule caps (MAX_TEAMS_PER_RULE and MAX_PEOPLE_PER_RULE, 100 teams and 100 people a rule names, and MAX_NOTIFY_EMAILS, 100 outside addresses a save may notify) belong to cowork-server and MindsHub. The app doesn't check them before a save; a save past one shows the server's refusal.

A model that can't run right now is not selectable

MindsHub's /v1/models marks each model with whether it can run for the org right now: a paid model on a drained wallet, any model once a free org has spent its free allowance, or a model an org admin's model rule blocks, arrives as enabled: false. That map reaches the renderer as settings.modelEnabled, and isModelLocked (lib/modelCatalog.js) is the single definition both pickers read, so the Settings rows and the composer's menu can never disagree about what a user may choose.

A locked model renders visible, tagged "Needs credits", disabled, and carrying an "Add credits" button. It stays on screen so the model is still discoverable, and the button is what keeps the row from naming an action it does not offer: once the row is closed off it is no longer a click target, so a tag and a tooltip would leave a user told to add credits with nowhere to do it. ModelSelect attaches that button from the option's locked flag, so Settings and the composer cannot end up offering different ways out.

Settings additionally puts a "Top up your balance" link under the picker, but only when the current model is locked — the stranded-pin case, where the wallet drained under a model already saved. It says nothing about a row the user is merely looking at, which is why the button on the row is the general answer and the hint is the specific one.

An admin's model rule is the one reason money cannot fix, so it is told apart. MindsHub sends each disabled row's disabled_reason, and cowork-server relays it from the MindsHub listing only (never a custom endpoint) as modelDisabledReasons. A row whose reason is model_restricted renders disabled and tagged "Restricted", with the tooltip "An admin in your organization restricted this model.", and is never locked, so it carries no "Add credits" button. unavailableModelFields in lib/modelCatalog.js builds the row fields for both pickers, so they cannot drift. The Settings hint under a restricted current model names the admin and has no billing link, and Code Mode's new-task check says "An admin restricted this model. Choose another model." A server too old to send reasons leaves every disabled row on "Needs credits", exactly as before. cowork-server relays any non-empty reason string, so knownModelDisabledReasons keeps only model_restricted, wallet_empty, included_allowance_exhausted and budget_exceeded: a row with any other reason reads as having none, and shows "Needs credits". mergeRecommendedModels replaces the reason map whenever it replaces modelEnabled and keeps it whenever it keeps that map, so a reason never outlives the enabled map it described. A row whose reason is budget_exceeded (the org's spending budget is used up) renders disabled and tagged "Budget reached", also never locked: credits do not raise a budget. The Settings hint under such a current model links to the console's Budgets tab instead.

Why it is not merely tagged: cowork-server resolves a stored model it knows the gateway will deny into an affordable one instead, so allowing the pick meant the turn ran a different model from the one the picker named. The user was told one model wrote their code while another did. The stored choice is never rewritten, so the moment the balance goes positive the original pick resolves again with nothing to re-select.

Availability is re-read whenever either picker opens, so a top-up made in a browser unlocks the rows on the next open rather than after a restart. A failed refresh keeps the map already held, and a model the map does not mention counts as available, so a degraded response can never empty a picker.

The app says how much is left before a task stops

The app reads GET /hub/usage/ on the sidecar every 30 seconds while signed in, and again whenever the window regains focus, so a top-up made in a browser shows up without a relaunch. useHubUsage holds the answer. One read carries the free MindsHub Air allowance, the paid balance, auto top up state and credit spend for the period. reachable: false is the resting state, so every surface renders exactly as it did before this existed until the sidecar says otherwise. A sidecar too old to serve the route answers 404, which reads as unreachable and paints nothing.

deriveComposerWarning in lib/usageWarnings.js turns that read into at most one notice, and it is the only thing that decides which. The notice sits above the composer rather than in the conversation, so it is in view when the next task starts and never becomes part of the task history. usageTransitions handles the other half: when the free tokens cross a step of the low band, run out, or auto top up fails while a task is streaming, ChatView drops a card into the timeline instead, because that turn is still running and the person has not come back to the composer yet. It reads the same BYOK gate the bar does, so a task billing someone else's key never hears about these tokens.

Which resource the warning names depends on what the next turn will spend. An explicit MindsHub Air pick runs on the free tokens, an explicit paid model only ever bills the balance, and the router can land on either, so both matter for it. The two resources are always named apart. "Out of tokens" on its own is never one of the outputs.

When nothing is wrong, the bar still says where the free grant stands: "3.4M of 5M free tokens left. Resets on Oct 1." A warning a person first meets at 20% left is a warning they cannot plan around, and the grant is the only conversion moment the product has, so it is not left to a blank space. The standing figure is neutral rather than amber and carries no close button. An uncapped grant has nothing to count down and gets no figure. A BYOK user, a signed-out one and an unreachable sidecar get nothing, exactly as before. An empty balance is named here too, in the same words the warning uses, because it is true and actionable from the moment it empties rather than from the moment the grant crosses 20%. The tone stays neutral: while the grant can still pay, nothing is blocked.

An explicit paid pick cannot spend the grant, so it gets no figure, but the bar's height is reserved with a hidden copy of it. Otherwise switching picks moved the whole composer up and down, and for a free user the healthy state is the state they are in nearly all month.

Announcing is a separate, permanently mounted sr-only region rather than a role on the bar. aria-live announces content CHANGES, so a region has to be in the DOM and empty first; since the bar is now on screen all month, adding a role to it when a warning arrives would only be promoting a node that is already there, and the warning would be silent. The region is polite rather than assertive, and a standing figure puts nothing in it, so nothing is read out on a poll that only moves the number.

Closing a notice hides it per dismissal key, not forever. A "low" state is a band the resource sits in the whole way down, so keying on the kind alone would let one close hide the last warning until the resource emptied. Both low states carry a stepped key instead, from balanceDismissStep and freeDismissStep, so a close holds for the step it was made in and the next step down asks again. The free grant's steps are 20%, 10% and 5% remaining, and 20% is also the band's own edge, so a task that runs from healthy into the band crosses a mark like any other. That is what lets usageTransitions report a crossing mid-task rather than only reporting the tokens being gone. Every dismissal is forgotten once usage is healthy, and a standing figure never counts as something to forget.

Closing the free warning steps down to the standing figure, never to nothing. The close button means stop shouting, not hide the number, and 20% left is where the number is worth most. The warning carries that figure with it as whenDismissed, so one place decides what the bar says at rest.

The free grant's 20% line is the console's 80%-used line read from the other side. FREE_TOKENS_LOW_FRACTION is the one place it is written, and Settings reads the same constant, so the meter's warning tint cannot drift from the bar.

Money moves in the console, never here. Each action opens a console URL through usageActionUrl. A billing owner lands on the form itself: add credits for "Add funds", the automatic tab for "Set up auto top up". Anyone else gets the billing page, because every wallet control the console offers is owner-only and a member following a deep link would reach a dialog they cannot submit.

Settings carries the same figures under Usage, on desktop and on the hosted web build alike: the free grant with its reset date, the balance, the spend for the period and auto top up state. The web nav drops the sections a hosted user cannot act on, and Usage is not one of them. It reads the route both hosts already call and every control opens the console in a browser, so hiding it left a hosted free user with nowhere to see the grant at all.

To see the notices without an account near its limits, run npm run dev:renderer and open /usage-bar-fixture.html. It renders every state from the real deriveComposerWarning, so the copy on the page is the copy a user sees. Add ?theme=dark for the dark pass. Each case carries an id off its label, so a screenshot run can crop to one state rather than a page too tall to read.

A task that stops on a billing limit gets a card in its timeline, and the card names the limit that fired. The drained-wallet card (token_limit) reads the same usage view through freeAllowanceState in lib/usageWarnings.js, and stops speaking from it once that view shows a wallet that can pay (a balance isBalanceEmpty does not flag): the card stays in the task, and the view describes the account as it is now. A view with no balance, which cowork-server sends when its wallet read fails, leaves the stop standing. With free allowance left, it says the priced model is what stopped and offers Switch to MindsHub Air. With the allowance spent, it names both resources and the refill time, in the sentence the spent-allowance card uses for the same state (allowanceStopCopy). It keeps the fixed balance copy, with Add funds only, when the view gives it nothing to go on (usage unreachable, no grant, an uncapped grant, or no usable time), when there is no Switch to offer (the task already runs on MindsHub Air, Air is not offered or is locked, or there is no message to resend), and when the wallet can pay again, as it can after a top up. The spent-allowance card (included_allowance_exhausted) names the refill time the gate sent on the failure, on a desktop or a hosted turn. When the failure carries none, as a hosted turn from an older cowork-server does, the card takes the refill time from the usage view. With no usable time from either, it offers funds alone and promises no refill. For an org with no free grant (the usage view's freeTokens.limit is 0, which cowork-server sends when MindsHub reports free_grant_eligible: false), freeAllowanceState answers no_grant and the card shows the console's no-grant sentence (NO_FREE_GRANT_SENTENCE) with no refill time, whatever time the gate sent. free_serving_paused has its own card: MindsHub's daily spend fuse has paused free MindsHub Air for every org that cannot pay, which is not the user's allowance, so the card says so and names when it lifts, from the reset time on the failure. Without one, as on a hosted turn from an older cowork-server, it says the pause lasts until the daily budget resets. model_restricted is not a billing stop but shares the page: an org admin's model rule refused the model, so the card names the model and an admin, and offers Open Settings only. budget_exceeded has its own card: the org's hard-capped spending budget is used up, which credits do not lift, so the card never asks for funds. It offers View budgets (the console's Budgets tab, recorded as billing_opened with trigger budget_exceeded), and Switch to MindsHub Air while the usage view shows the free allowance has room.

To see those cards, open /billing-stop-fixture.html under the same dev server. It renders the drained-wallet card in each usage state and after a top up, the spent-allowance card with the gate's refill time, with the usage view's, with no usable time at all, and for an org with no grant, the paused card with and without a time, the restricted-model card with and without a model name, the budget card with and without Air room, and the connect-a-provider card, all from the components ChatView renders. ?theme=dark works the same way, and each case has a fixed id for cropping.

Settings > Agent tests configured providers by default on desktop and web, independently of VITE_PLATFORM_UI. For the Python-served Docker app, set COWORK_PROVIDER_TESTS_ENABLED=false in the container environment to skip provider tests on open, save and retry. Recreate the container and reload the page after changing it; the same image supports either value. The setting accepts true or false and defaults to true. The SPA wrapper supplies the value before the renderer starts. Static hosting and desktop retain enabled defaults.

With MindsHub UI off, provider and model controls are hidden, but that does not disable background provider testing. Configure the runtime flag separately when the operator manages providers outside Cowork. Memory and Advanced Settings remain visible, and model or provider error cards direct users to the operator.

An operator can show the composer's model picker in that build at run time. For the Python-served Docker app, set COWORK_MODEL_PICKER in the container environment to default or open; it defaults to off, which writes nothing into the page. The picker's first row, "Operator default", sends no model, so the question runs on the operator's role models. The other rows are the models the server lists for the planning provider, less any it lists with enabled: false. With none left, the composer shows no picker. In default mode each new conversation starts on "Operator default"; in open mode it starts on the user's last pick until the page reloads. A conversation saved on a model the picker no longer lists sends no model. Settings' model rows stay hidden in every mode. Recreate the container and reload the page after changing it.

With the picker on, the operator can also let users pick a reasoning effort. Set COWORK_MODEL_EFFORTS to a JSON object of each model's efforts users may pick, such as {"opus-5-5": ["xhigh"]}. The composer then shows an effort control on a model the object lists, with "Default" first, which sends no effort, then those efforts. With "Operator default", it offers the efforts both PLANNING_MODEL and CODING_MODEL list there, since the question runs on both. A model the object doesn't list shows no effort control. The server applies the effort to the question's planning and coding calls, not to its router call. The app refuses to start when COWORK_MODEL_EFFORTS is set with the picker off, or holds anything but lists of lowercase efforts. Without it, the effort control stays hidden.

A conversation keeps the model and effort its latest question sent: cowork-server saves them on the conversation, and the conversation list and a reopened conversation return them, so the composer shows them again after a reload. A pick made in the composer stays on the conversation through the list's background refreshes until a question saves it. A question sent on "Model Router", "Operator default" or "Default" sends no model or effort and names that pick in reset_picks instead, so cowork-server clears the saved one and a reload shows the default. A saved model the picker no longer offers, such as one the wallet locks, also goes out as no model, but sends no reset, so the conversation keeps that pin. A conversation with no saved pick shows and sends the default, whatever the home composer shows: the home composer's picks seed only a new conversation.

The Share box in that build follows where cowork-server publishes. When COWORK_PUBLISH_TOKEN is set in the container environment, the server publishes with that one shared token, so Share offers no "Only me" (a shared token has no owner to let in) and Public says "Anyone with the URL". Without it, the server publishes to MindsHub with the person's own key, so Share offers "Only me" and Public says "Anyone on the internet with the URL". The SPA wrapper tells the page only whether the token is set, never its value. It reads only the container environment: cowork-server also takes the token from its .env files, so a token kept only there still publishes with the shared token while Share offers "Only me", which the publisher refuses. A page served without the wrapper keeps the shared-token choices. Share starts with nothing picked in either case. The wrapper doesn't read ANTON_PUBLISH_URL or a saved publish URL, so a deployment that points either at a publisher other than MindsHub, without a shared token, still sees the MindsHub choices.

With testing disabled, Save still persists changes and validates configuration; its tooltip says "Save changes." and no provider test is reported as passed. Existing stored provider results remain available. This controls browser requests, not API authorization. For a failed MindsHub probe the sidecar adds providerStatusReasons, the gateway's own reason per provider type ({ code, resetAt }), and only for a response from the configured MindsHub host. mindsProbeNotice in lib/providerStatus.js turns it into the notice under each role row: no credits (wallet_empty), the spent-allowance copy shared with the card (included_allowance_exhausted), the paused copy shared with the card (the daily fuse), a spent org budget with a View budgets link and no funds action (budget_exceeded), a muted slow-down line (rate_limited), or a muted billing-outage line (policy_unavailable). The LLM Providers row names the same stop instead of calling every 429 "Rate limited". A sidecar that sends the map but names no reason for a failed probe, such as an upstream vendor's 429 that the gateway relays without its own reason, gets the generic "failed its last test" warning and no billing notice. Only a sidecar too old to send the map at all keeps the old check, where any 402 or 429 in the detail reads as no credits. The map lives in the settings blob beside providerStatusDetails: it is left out of the Save button's dirty check, never written back, cleared for a provider whose key is edited, and replaced per provider type on every test (a tested type the sidecar named no reason for is held as null, which is how the notice tells it from a type an old sidecar never classified). To see the notices, the Providers row copy, the restricted hint and an open picker with a restricted row, open /settings-agent-fixture.html under the same dev server; ?theme=dark and the per-case ids work the same way.

Settings > Appearance carries "Show where figures came from", on by default and kept with the server's settings (show_figure_sources); the switch shows only when the server serves that key. With it on, each figure in a finished answer that cowork-server traced (the response.figure_sources event) is a button: a grey dotted underline when a step returned it, a solid amber one when no step did. A figure no step of this turn returned but one of the chat's earlier answers gave also gets the grey underline, and says "Repeated from an earlier answer" with no source listed. Hover or keyboard focus shows where it came from, and a click or Enter lists every source: its SQL and requests with a Copy button each, a web link, Open step, and View file. View file opens the file read only, as it is now: a project file by its path, offered only while the chat is in the project the answer ran in, or a file attached to the chat by its files-store id, offered only while the chat has a project, since the attachment route goes through it. Inside a table the figures share one tab stop and the arrow keys move between them. With the setting off, answers render with no marks.

To see every mark without running such a turn, open /figure-sources-fixture.html under the same dev server; ?theme=dark and the per-case ids work the same way. npx playwright test --config playwright.figure-sources.config.ts checks on that page that a figure's popover stays on screen on 375x667 and 320x568 phones and at 200% zoom.


The shared browser

The agent and the person share one browser beside the chat. On the web, the browser router serves it under /browser on the app's own origin.

  • Settings > Agent shows a "Shared browser" group when GET /browse/status answers available: true. On the web that means a browser router is configured and the person's account may use it. On the desktop it means the app's own browser has registered with the local server. An answered unavailable shows no group. Settings and the + menu read the status the same way (lib/browseStatus.js): a server with no such route (a 404) predates the browser and counts as an answered unavailable, and a read with no answer in 20 s has failed. The renderer sends this call no MindsHub credential header. Settings asks again when the window gets focus, when the tab shows again, and on the desktop when main sends browser:registered. As in the + menu, a focus or a visible tab while a read is still out waits for that read, so its 20 s limit still passes.
  • An account the browser isn't enabled for gets available: false with status: "not_entitled", and the group shows one line: "Not available for your account." An organization whose admin turned the browser off gets status: "organization_off", and the line reads "Your organization turned off the browser." Either way the group still offers Sign out of all sites. When the status call fails before any answer came, on the web or a desktop that hosts the in-app browser, the group says "Couldn't confirm the browser right now. Try again in a moment." with a Retry button, and keeps the switch and Sign out of all sites, which need no answer. A call that fails after an answer keeps that answer.
  • The group holds one switch, off by default until the person turns it on. Each task can still switch the browser off from the composer's + menu, whose tooltip names the agent the person set. The + menu shows that switch while /browse/status last answered available: true (hooks/useBrowseAvailable.js, joined in lib/browserSwitch.js), so a self-hosted stack, which offers no browser, shows none. The hook reads the status as Settings does (lib/browseStatus.js), so a 404 counts as an answered unavailable and a read with no answer in 20 s has failed. The hook asks again on focus, when the tab shows again, on the desktop when main sends browser:registered, and after a failed read, at 5 s, 15 s and then every 60 s. A failed read keeps the last answer. If a read fails before any answer has come, the switch shows while Settings has the browser on. A task's pane and the web warm-up follow the same answer. A switch that hides keeps the person's Off, so a task started from Home still starts with its browser off. Switching a task's browser off mid-turn leaves the running turn's pane open until that turn ends.
  • The group says what runs today: where websites see the browser come from, that sign-ins are kept for later tasks in every organization the person belongs to (on the web until 90 days unused or until the person signs out of all sites; on the desktop until the site signs them out or they sign out of all sites, and a site's session cookies end when the app quits), and that page text and screenshots go to the model provider, which a desktop signed in to MindsHub names as MindsHub. On the web it adds what "Fast answers with Jev" sends: the goal of each browser step, the page's address, title, element names and first 1,500 characters, and the recent steps.
  • Sign out of all sites on the web calls DELETE /browse/logins, which clears every site's cookies and sign-ins from the browser and from storage. Saved tabs stay. cowork-server answers 424 browser_unreachable when its call to the router fails or times out. After a timeout the router can still finish the sign-out, so the group says the sign-out didn't confirm in time and may have finished, and asks the person to sign out again to be sure.
  • On the web the browser runs in MindsDB's cloud, so websites see MindsDB's addresses. There is no city, proxy or exit choice, and no setting for a browser service of your own.
  • The web pane says, under its header, that what the pane shows and what the person types there, passwords included, pass through Cloudflare and MindsDB's browser service, that the agent's page reads go to the model provider, and, in Settings' own words, what Jev gets and that sign-ins stay. The desktop pane says where page reads go and, while the person holds the browser, that sign-ins stay, also in Settings' words.
  • The commit hold. The web browser holds a step that submits, buys, sends or deletes until the person approves it on the chat card. That card's question id is browser:approve:<session_id>:<pending_id>. Its Approve first calls POST /browse/approve {session_id, pending_id} and answers the card only after a 200 that names the same step; on any refusal the card stays open and says why (lib/browserApproval.js). An Approve sent again after the card's answer failed doesn't record the approval twice. A card with that prefix whose ids can't be read refuses Approve and runs nothing. Skip, Cancel and every other answer first call POST /browse/decline {session_id, pending_id}, which drops the held step and any approval already recorded for it. That call is best effort: the card is answered whatever it answers, a 404 from a server without the route included, or after 10 seconds with no answer. A card with another id, and every card on the desktop, is answered directly.
  • The agent's response.browser_session_opened event carries the session id alone, and becomes a Browser step on the turn. The live turn's step opens the pane while the browser is on. A past turn's step opens it only when the person clicks it. A pane the person closes stays closed until the next turn's step or a click.
  • The pane mints a viewer link with POST /browse/embed each time it shows the viewer, because the router honors a link once. It mints when the pane opens, when the tab becomes visible again, when the network comes back, on Reload, and when the viewer posts {type: "browser-viewer-closed"}. It never mints on a timer.
  • The pane checks that message's source against its own frame, because the sandboxed frame's origin is null. Every router refusal of the view is a page that posts that message with a close code. A close that comes before the viewer posts {type: "browser-viewer-ready"}, however late, or within 10 seconds of its link, is a failed open, and after two in a row the pane stops asking and offers Try again. A 4401 before ready and 10 seconds or more after the link is the starting page's own link lapsing, so the pane mints again without counting it. On 4503 the pane says every browser is busy, and on 4429 that the person's browser already has 4 tasks open. Neither mints on its own; Try again, the tab coming back and the network coming back still do. The "taking longer" state comes 90 seconds into a wait, and the new links a close brings don't restart that clock.
  • The pane frames only /browser/sessions/<id>/view for its own session, on the app's own origin, with no user name or password, and refuses an answer with no ticket_expires_at, the time by which the link must be opened. The viewer it opens closes at lease_expires_at. The frame is sandboxed with allow-forms allow-scripts, without allow-same-origin. While the tab is hidden the pane drops the frame, so a browser nobody watches can go to sleep.
  • On the web, a task that used the browser wakes it early with POST /browse/provision, when the task opens and when the person types, at most once every two minutes per task. The desktop wakes nothing.
  • The pane takes a grid column from 1160 px up and floats over the chat below that width. BROWSER_PANE_INLINE_MIN in src/renderer/cowork/lib/breakpoints.js holds the edge for both useBreakpoint and browser-panel.css.
  • The desktop shell frames only its loopback server. Its frame-src and child-src carry no scheme source such as https:, and src/renderer/shellCsp.test.ts refuses one.

The desktop's own browser

On the desktop the shared browser is Electron's own Chromium inside the app's window. It works with a MindsHub account and in bring-your-own-key mode. No browser router, pod, proxy, warm-up or viewer link is involved, and websites see the person's own connection.

  • The bridge. Electron main serves the routes anton's browser tool calls (src/main/browser-bridge.ts) on 127.0.0.1 and a free port. Every request needs this launch's 32-byte key as Authorization: Bearer, compared in constant time. The Host header must be exactly 127.0.0.1:<port>, and a request a web browser sends (with Origin or Sec-Fetch-* headers) is refused, so no web page can drive it. Bodies are capped at 1 MB. There is no /_embed, no route that runs script and no cookie export. GET /healthz answers {ok, api}.
  • Registration. Main tells the local server where the bridge is with PUT /api/v1/runtime-credential/browser {url, token} (src/main/browser-register.ts). It sends it only after the UI sends browser:ready, and only to a server this app started or adopted: a start counts once /health names the owner the app stamped that server with, and nothing goes to the port while a start runs, since another local process may be the one answering it. It sends it again after every server start (the same started hook as the MindsHub credential) and after a key change. When the window closes, or the UI reloads, it sends an empty pair, which clears it. The server keeps the pair in memory only, and a server that predates the route answers 404, which leaves the browser off.
  • Accounts. One profile per account, <userData>/browser-profiles/<key> with the key named by the account's data root (session.fromPath, folder mode 0700), shared by the account's organizations. It sits under the app's userData because Electron 44 and later keep a fromPath session's cookies across a restart only there. An account or organization switch closes every task's tabs and makes a new key, so the old one stops working. The profile and the store follow the account the local server runs on, so they move together with the tasks and the key when the server moves, not when the sign-in does. A launch that can't name its account gets an in-memory profile, whose sign-ins end when the app quits. Saved tabs and signed-in sites live in <account data root>/browser-host.json, mode 0600.
  • Tasks. Each task has its own tabs (one WebContentsView each), an active tab, a control record and a one-at-a-time queue (src/main/browser-sessions.ts). At most 6 tasks stay live: opening another closes the least recently used one, and the person's own use (input in the page, the pane's buttons, showing or hiding the task) counts as use. One idle for 15 minutes closes too. Neither ever closes the task the pane shows or one the person holds; when those are all the live tasks, another task gets 503 at_capacity. Sign-ins stay: a site's persistent cookies last until the site signs the person out or they sign out of all sites, and its session cookies end when the app quits.
  • The views. Each runs sandboxed with context isolation, no preload, no DevTools and Blink's AutomationControlled and SharedWorker features off, on its own profile, never the app's default session; a popup's page gets the same preferences. Every permission and device request is denied, and a site that asks for a TLS client certificate gets none. Top-level pages are http and https only, and the LAN stays reachable. Requests a page makes to the local server's port or the bridge's port are canceled, apart from the two kinds the request listener never sees (see Destinations). The user agent loses the app and Electron tokens. Outside macOS the person's Control+W in a page does nothing, since the app menu's Close would close the window and every task's browser with it. The person's reload chord (Command+R on macOS, Control+R elsewhere) reloads the site, and with Shift it reloads past the cache. A tab the pane doesn't draw, a parked one included, stays laid out at the size the pane last drew at, with one pixel in the window's top-left corner, because Chromium gives a hidden view a zero-sized viewport.
  • Page reads run in an isolated world (src/main/browser-page-script.ts), so element numbers live in that world and nothing is written into the page. Password, one-time-code and card fields, and any field once seen as one of those, never return their value. A watch, started on each new document and when the person takes the browser, marks secret fields so a password the person shows still reads as hidden. Electron runs isolated-world script only once the page stops loading, so the watch starts then: a password shown before the load ends, with no read in between, reads as an ordinary field, and so does one toggled in a closed shadow root before a read has seen it. Ordinary field values are read up to 200 characters. A check frame (Cloudflare, reCAPTCHA, hCaptcha and others) is reported when the person can see it, or by its presence when the page holds it where a read can't see it (a closed shadow root or another frame). A read that takes over 10 seconds answers 409 page_busy.
  • Agent input (src/main/browser-input.ts) attaches the view's debugger for one step, sends only Input.* commands plus focus emulation, and detaches when the step ends. The mouse moves along eased paths to a random point inside the element. A type or press step focuses its element rather than clicking it, as on the web. Text is typed key by key, with a tab character inserted as text so typing never moves the focus, and past its first 100 characters it is inserted in chunks, so the longest text the contract takes ends inside the step's time limit. Keys are named as KeyboardEvent.key names them (Enter, ArrowDown, Control+a), as on the web, and another spelling gets 400. A type, a select, or a press of a key that edits text into a secret field gets 403 password_field; Enter, Tab, Escape and the keys that move or submit still go. Typing checks the focus before every key and stops with 409 stale_element once it leaves its field. The paste shortcuts are refused, since the person's clipboard may hold a password, and so is a middle click outside macOS and Windows, which pastes the person's last selection. No key event carries a native key code, so a key the page leaves alone never reaches the app menu, where Control+W would close the window on Windows and Linux, and the agent's keys never reach the pane's own key claims.
  • Screenshots are captured in main, scaled to at most 1024 pixels wide, and the element numbers are drawn into the bitmap there (src/main/browser-screenshot.ts).
  • Control. The agent hands the browser to the person through the API. Only the person's Done in the pane hands it back; the API refuses holder: "agent" with 403 person_only. While the person holds it, page, action, screenshot, tab and DELETE /sessions/{id} calls get 409 human_in_control, and a step in flight is cut off, its waits included, and answers 409 too, so no debugger is attached during the person's turn. A step that finished as the person took over answers 200 without its page, and a page read or screenshot that control changed under answers 409. A site's sign-in prompt during the person's own take over leaves the hold theirs.
  • Popups become tabs of the same task, keeping window.opener for sign-in flows, but only within a second of an agent step or the person's own input. While the agent holds the browser they open in the background. A site's username and password prompt goes to the person as a form in the pane, and its values go only to that site.
  • Downloads land in the account's own folder inside the OS Downloads folder ("Cowork browser"), never loose in it. While the person holds the browser because they took it over themselves, they save at once. Otherwise, the agent's or a page's hand-over included, each one waits, paused in the account's staging folder outside Downloads, until the person picks Save or Don't save in that task's pane; nothing reaches Downloads without that yes. The pane keeps the oldest waiting download on its line and arms Save a moment after it appears, and a task that closes cancels the downloads it left waiting. A task keeps at most 5 downloads waiting and cancels any past them, and a download no task owns is canceled. Two downloads in flight never get one name. On macOS each saved file gets the com.apple.quarantine mark, so Gatekeeper checks it before it first opens; a file that can't be marked is removed and reads as interrupted. Chromium writes a download's first bytes to a temporary file in the OS Downloads folder before it moves to staging.
  • Destinations. Besides the local server's and the bridge's ports, every page request to MindsHub's own hosts (every name under mindshub.ai except the apex and docs.mindshub.ai, and all of mdb.ai and 4nton.ai) or to a cloud metadata address (169.254.0.0/16, fe80::/10, AWS's fd00:ec2::254, their mapped forms and metadata names) is canceled, and an agent step that asks for one gets 400 with the reason. A name is also checked by what it answers, through the profile's own resolver: an answer in 169.254.0.0/16 or fd00:ec2::254 is canceled anywhere, and a loopback answer on the local server's or the bridge's port. An fe80:: answer is not, since LAN names often give one beside their IPv4 address. Two limits remain. A name that changes its answer between that check and the page's own lookup (DNS rebinding) gets through, and so do a service worker's WebSockets and any WebTransport session, since the request listener sees only a WebSocket that belongs to a frame and no WebTransport at all. Shared workers, whose WebSockets would skip it too, are off in every view. Private ranges and the LAN stay reachable.
  • The pane (LocalBrowserStage.jsx) mounts no frame. It shows the task once when it opens, reports its stage's bounds as they change, and main places the task's tab there. The native view draws above the page, so the pane parks it off screen while anything draws over it (lib/nativeOverlay.js, raised by Modal, OutsidePressLayer, Select and Combobox while open, a shown toast, the floating rail drawer, the narrow sidebar popout and the update curtain) or the sign-in form shows. Main also parks it for any stage under 200 px in either direction after the UI zoom, Code mode's hidden panel included, so the page never draws outside its stage. Only main knows the UI zoom, so main answers each show and each new set of bounds with whether it draws there. A stage too small to draw in, in a short window or a zoomed UI, says "Make the window bigger to see the page", during a take over too. Only the answer to the latest bounds counts, so a task that opens again, or the next task, waits for main's answer to its own show. The line never shows while an overlay is open or the sign-in form shows, since those are why nothing draws then. Parked or not, the task stays the one the pane shows until the pane closes or the task changes, so idle close and the live-task cap still spare it. Its header has back, forward, reload, Take over and Done. While the person holds the browser, the hint names where the page is before the agent's reason: an http(s) page's host ("Your turn on example.com: …"), else its scheme and path with no query or fragment ("about:blank"), and never the page's title, so a lookalike page can't pass its words off as the app's. A download waiting for Save gets its own wrapping row, so Save and Don't save stay in the narrowest pane. Every IPC handler answers only the app's own main frame.
  • Settings on the desktop say that websites see the person's own connection, that the agent's code runs as the person and can read this browser's sign-ins, that some sites, Google's sign-in among them, refuse sign-in from an app's built-in browser, and that sign-ins last until the site signs the person out or they sign out of all sites, with some sites signing them out when the app quits. While the app is signed in to MindsHub, the model-provider line names MindsHub. Sign out of all sites clears the profile's cookies, storage and cache and the sites the store remembers, and closes every tab.
  • Usage events. Every desktop's Settings has "Send anonymous usage events", on by default, in its own group whatever the browser's status. Its help names the agent and MindsDB, which receives the events. Off writes COWORK_USAGE_EVENTS=false to the account's dotenv, and main then starts the server with ANTON_ANALYTICS_ENABLED=false, which stops all of anton's anonymous events, the browser's three included, from the next time the server starts. The app's own analytics events don't read the switch.
  • The Electron floor. The in-app browser holds the person's sign-ins, so it runs only on a supported Electron: 44 or later (MIN_IN_APP_BROWSER_ELECTRON_MAJOR in src/shared/browser-contract.ts, raised as majors leave support and never lowered). Below it the preload reports supportsInAppBrowser: false, the host never starts its bridge and registers nothing, so the shell's turns get no browser tool and the UI shows no pane. e2e/in-app-browser.spec.ts skips below the floor.
  • Version skew. The preload reports supportsInAppBrowser. An older shell has no flag, so the UI shows no desktop pane. A UI that never sends browser:ready never gets the browser registered, so its turns get no browser tool.
  • Limits. At most 6 live tasks (another gets 503 at_capacity when the pane shows or the person holds all six), 20 tabs per task, and 100 saved tabs per project (a new name past them gets 409 too_many_saved_tabs), the same per-project number as the web, which saved_tabs.json's limits pins.
  • The contract. src/shared/browser-contract.ts types the routes and the IPC. src/main/__fixtures__/browser-contract holds verbatim copies of anton's contract fixtures, and browser-contract.test.ts and browser-bridge.contract.test.ts hold the host to them. src/renderer/cowork/__fixtures__/browser-router holds verbatim copies of cowork-server's browser router answers (the embed link, an approval, sign-out), which the web pane and Settings are tested against. POST /sessions answers {session_id, resumed, url} with url null before a page loads, and DELETE /sessions/{id}/sites/{site} drops a site's record, not its cookies. e2e/in-app-browser.spec.ts drives the real host in Electron (npm run build:main && npx playwright test e2e/in-app-browser.spec.ts).

Live-app slot notices

If a launch was refused because the app slots were full, Cowork shows a persistent notice when the server reports available capacity. You can then ask your agent to launch again. The notice does not reserve a slot or launch the app.

The app checks /api/v1/live-apps/availability every 15 seconds while its tab is visible, and when you return to it. This works on every page without sending a chat message, including for someone who has never launched an app. It runs only when /health reports live_apps. The server retains each notice until a visible toast has displayed it and Cowork acknowledges its id. Failed reads and acknowledgements retry; after each failed read the next check waits twice as long, up to one minute, and a successful read returns to 15 seconds. Repeated replies do not create duplicate toasts. A new refusal closes a notice already acknowledged, so the next one shows as new. A change to the authenticated scope clears the previous person's notice.


Over-the-Air Updates

MindsHub Cowork updates three independently-versioned pieces, each through its own mechanism, so most updates land without the user reinstalling anything:

  • UI (React renderer) and Server (Python cowork-server sidecar) update fully over-the-air — no new .dmg/.exe needed. These two are coupled and auto-apply together at boot (server first, then UI).
  • Shell (the Electron app binary — everything in src/main/ and the preload) can't hot-update itself, but on stable/prod it no longer requires a hand reinstall: an electron-updater background download installs the new build on the next relaunch (ENG-850). A manually-downloaded installer remains the fallback (ENG-849). The shell is independent of the UI/server pair and always needs a restart to take effect.

That coupling split is why the user never sees a single combined "3 updates" prompt — the seamless UI/server pair and the restart-required shell are different surfaces. For when updates apply (boot vs. periodic checks, the server-down recovery exception, the UI_UPDATE_MODE escape hatch) and what the user sees for each combination of pending updates, see docs/update-behavior.md.

UI OTA is gated by build kind (ENG-670): enabled in prod builds only — stable, preview, and dev builds always run their bundled renderer so testers see the branch under test.

Server updates (source-aware)

The server updater detects how cowork-server was installed (from the tool venv's direct_url.json) and updates accordingly:

  • git install — re-pulls the configured branch/tag HEAD for cowork-server and anton (trigger: changed remote commit SHA via git ls-remote)
  • PyPI install — version comparison against PyPI, then uv tool install --upgrade

After an upgrade the server is restarted and probed via /health; on failure the previous version is reinstalled automatically, and the rollback itself is health-verified (a still-broken rollback raises a critical notification rather than being reported as recovered). If the server is down, an available server update is applied immediately regardless of update mode — recovery, not routine maintenance. Set COWORK_SERVER_DISABLE_AUTOUPDATE=1 to opt out.

See src/main/server-updater.ts for the implementation.

UI updates (GitHub Releases)

The React UI updates via a separate public repo: mindsdb/antontron-releases. This avoids baking GitHub tokens into the app.

┌─────────────────────────────────────┐        ┌──────────────────────────────────┐
│  mindsdb/cowork (PRIVATE)           │        │  mindsdb/antontron-releases      │
│                                     │        │  (PUBLIC)                        │
│  source code lives here             │        │                                  │
│                                     │  push  │  GitHub Releases:                │
│  .github/workflows/publish-ui.yml ──┼───────▶│    ui-v2.26.7.16.1/…tar.gz      │
│                                     │        │                                  │
│                                     │        │  GitHub Pages (gh-pages branch): │
│                                     │        │    latest.json                   │
└─────────────────────────────────────┘        └──────────────────────────────────┘
                                                              ▲
                                                              │ HTTPS (no auth)
                                                              │
                                                 ┌────────────┴─────────────┐
                                                 │   MindsHub Cowork app       │
                                                 │   (every user's machine) │
                                                 └──────────────────────────┘

How it works:

  1. Code is merged to main — every push to main runs the prod pipeline (prod-build-deploy.yml), whose auto-release job computes a CalVer version (e.g. 2.26.7.16.1) via the shared calver-release.yml reusable in mindsdb/github-actions, tags it, builds the prod installer, and calls publish-ui with that exact version, so the UI bundle and the prod app installer always publish the same version
  2. The publish-ui workflow builds the renderer (with the version baked into __APP_VERSION__) and creates a .tar.gz bundle with a SHA-256 checksum
  3. Using a RELEASES_TOKEN, it pushes the bundle as a GitHub Release and updates latest.json on GitHub Pages — both on the public antontron-releases repo
  4. The app checks latest.json at launch and every 4 hours (static file, no auth, no API rate limits)
  5. An update is taken only if it passes the safety gates: strictly newer than the installed UI (no downgrades), SHA-256 verified, the server-first coupling held (a failed server update defers the UI), and any declared min_server_version floor satisfied
  6. The update is applied automatically at boot — the UI reloads silently, no user choice involved. There is no manual/auto setting in Settings anymore (ENG-858); UI_UPDATE_MODE in ~/.anton/.env remains as an env-only support/QA escape hatch, not a user-facing preference. A mid-session periodic check (every 4h) still only surfaces a banner and never auto-applies, so a long-running session can always see and apply an update without an unplanned reload. A freshly-swapped bundle must finish loading within 15s or it is rolled back and quarantined. See docs/update-behavior.md for the full timing rules.

Shell updates (auto-update / installer)

The Electron shell (src/main/, preload, native deps) can't hot-swap itself while running, so it updates one of two ways:

  • Automatic (ENG-850) — packaged stable and prod builds carry a channel-specific electron-updater feed under downloads.mindshub.ai/mindshub-cowork/updates/. It checks at boot and every 4h — and every 30 minutes once a build is downloaded and waiting for a restart, so the pending installer can't go stale while the feed moves on — downloads the new build in the background, and installs it on the next relaunch (auto mode installs on a normal quit; the quit path first drains any in-flight UI/server apply so the two can't overlap). Enabled by default on both stable and prod (stable led the rollout ring); SHELL_AUTO_UPDATE_ENABLED=false is the emergency kill switch for either ring. preview/dev fail closed. A downloaded target is persisted so the next launch can detect and report a shell update that didn't actually apply. Signature/checksum failures are terminal for auto-update and fall back to the manual path.
  • Manual notice (ENG-849) — a prod-only fallback (also shown when auto-update is disabled or has failed): the poll compares the installed shell CalVer against shellVersion in latest.json and, if newer, shows a dismissible "New version available — Download" banner (per-version dismissal) linking to the installer on downloads.mindshub.ai. Detection only — it never downloads or installs.

Both surface in the sidebar and in Settings → Updates. See src/main/shell-auto-update-runtime.ts (auto-update state machine) and checkForShellUpdate() in src/main/updater.ts (manual notice).

Publishing

Trigger When Version
Push to main (normal path) Every merge — the release train's auto-release calls publish-ui Canonical CalVer, identical to the prod installer (e.g. 2.26.7.16.1)
Manual dispatch Actions UI → Run workflow — re-publish/backfill Entered version, or derived from git describe if empty
Tag push git tag ui-v2.26.7.16.2 && git push origin ui-v2.26.7.16.2 — UI-only release From the tag

The workflow checks for duplicate versions and skips if already published. Because the client refuses downgrades, un-shipping a bad bundle means publishing a newer fixed version, not re-pointing latest.json at an older one.

Verifying a deploy

Security

  • Every UI bundle is integrity-checked with SHA-256 before extraction
  • Checksum mismatch → update discarded, app loads last known good UI
  • Previous UI version kept on disk for automatic rollback; a bundle that fails its post-swap load check is rolled back and quarantined (never re-applied)
  • Cache slots carry versioned provenance (.ota-meta.json) and are served only when strictly newer than the bundled renderer — a stale or legacy cache can never downgrade the UI
  • OTA runs only in prod builds; the gate fails safe to OFF if the packaged build kind is missing or unrecognized
  • All downloads over HTTPS
  • RELEASES_TOKEN only has write access to the public releases repo — source code is never exposed

Boot sequence

App starts
  ├─ If DEV_MODE is set → load Vite dev server or bundled renderer, skip OTA
  ├─ Load cached UI (instant, no network needed)
  │   └─ Served only if: OTA enabled (prod build) + valid provenance
  │      + strictly newer than bundled + server-compat floor verified;
  │      otherwise the bundled renderer loads
  ├─ Start cowork-server (spawn process, poll /health while the child lives)
  └─ After renderer loads: boot update check (UI manifest + server, in parallel)
      ├─ apply now (server first, then UI, health-checked reload) — unless the
      │   UI_UPDATE_MODE=manual escape hatch is set (support/QA only), then banner only
      └─ then re-check every 4h (banner only, never auto-applies)

The app never blocks on a network request — it always loads immediately from cache or bundled files.

File layout (on disk)

{userData}/ui-cache/
  version.json          # { "version": "1.2.0" }
  current/              # Active renderer bundle
  previous/             # Rollback copy

On GitHub (mindsdb/antontron-releases):

gh-pages branch:
  latest.json           # { "version": "1.2.0", "url": "...", "sha256": "..." }

GitHub Releases:
  ui-v1.2.0/
    ui-bundle.tar.gz    # The renderer build output

Desktop Builds & Releasing

This section applies to the packaged Electron app (macOS .pkg / Windows .exe). Not relevant for local development or Docker deployments.

Releasing

The single source of truth for the app version is package.json ("version").

  1. Open a PR that bumps "version" in package.json (e.g. 2.0.5 → 2.0.6).
  2. Merge to main.
  3. .github/workflows/prod-build-deploy.yml automatically creates the git tag and GitHub release, then cuts the installers from it in the same run via build-installers.yml, which builds, signs, and uploads them to S3.

Don't:

  • Create GitHub releases manually — the v* tag namespace is locked via a repo ruleset.
  • Push v* tags directly — same protection applies.
  • Edit "version" in package.json outside a dedicated bump PR — keep version bumps small and reviewable.

Anything under .github/ is owned by @mindsdb/devops via CODEOWNERS. PRs touching workflows require their review.

For hotfixes or out-of-band releases, coordinate with @mindsdb/devops to bypass the tag ruleset. The prod upload job still verifies package.json version matches the release tag.

Building locally

# macOS — unsigned DMG (universal: x64 + arm64)
npm run dist:mac

# macOS — .app only, no DMG (faster, unsigned)
npm run pack

# Windows — NSIS installer (x64)
npm run dist:win

Prerequisites: Node.js 18+, npm. For signed builds: Apple Developer certificates (macOS) or EV code signing certificate (Windows).

Building from local uncommitted source (via parent Makefile)

When working in the minds-platform superproject, use make pack-local instead of npm run pack. It installs cowork-server from the local backend/core_api/ directory (no push required), builds to /tmp to avoid the iCloud re-tagging codesign failure, then copies the result to frontend/release/mac-arm64/.

# from the minds-platform root:
make pack-local
# launch the built app with local server (auto-update disabled):
COWORK_SERVER_DISABLE_AUTOUPDATE=1 open "frontend/release/mac-arm64/MindsHub Cowork.app"

iCloud builds — If the repo lives under ~/Documents (iCloud Drive), npm run pack fails with resource fork, Finder information, or similar detritus not allowed during codesign. Build to /tmp manually:

PATH="/opt/homebrew/opt/node@20/bin:$PATH" \
  npx electron-builder --mac --arm64 --config.directories.output=/tmp/minds-build
cp -R /tmp/minds-build/mac-arm64 release/

Code signing

macOS Code Signing + Notarization

1. Get certificates from Apple Developer portal

You need two certificates:

  • Developer ID Application — signs the app binary
  • Developer ID Installer — signs the DMG/pkg (optional but recommended)
security find-identity -v -p codesigning
# Should show: "Developer ID Application: Your Org (TEAMID)"

2. Set environment variables

# Option A: Apple ID + app-specific password
export APPLE_ID="your@email.com"
export APPLE_APP_SPECIFIC_PASSWORD="xxxx-xxxx-xxxx-xxxx"  # Generate at appleid.apple.com
export APPLE_TEAM_ID="YOUR_TEAM_ID"

# Option B: API key (recommended for CI)
export APPLE_API_KEY_ID="XXXXXXXXXX"
export APPLE_API_KEY_ISSUER="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
export APPLE_API_KEY="/path/to/AuthKey_XXXXXXXXXX.p8"

3. Build signed + notarized

npm run dist:mac
# electron-builder will: sign -> notarize -> staple -> create DMG

The electron-builder.yml config and scripts/notarize.js hook are already included in this repo. The hardened-runtime entitlements (build/entitlements.mac.plist) are required because Electron uses JIT and dynamic linking.

Troubleshooting

codesign -dv --verbose=4 "release/mac-universal/MindsHub Cowork.app"
xcrun stapler validate "release/MindsHub Cowork-0.1.0-universal.dmg"
Windows Code Signing

Option A: EV Certificate (USB token)

export CSC_LINK="/path/to/certificate.pfx"
export CSC_KEY_PASSWORD="your-password"
npm run dist:win

Option B: Azure Trusted Signing (cloud-based, recommended for CI)

See scripts/azure-sign.js for the signing hook configuration.

Option C: Self-signed (dev/testing only)

$cert = New-SelfSignedCertificate -Subject "CN=Cowork Dev" -Type CodeSigningCert -CertStoreLocation Cert:\CurrentUser\My
Export-PfxCertificate -Cert $cert -FilePath cowork-dev.pfx -Password (ConvertTo-SecureString -String "password" -Force -AsPlainText)

Self-signed apps trigger SmartScreen warnings. Only EV certs or Azure Trusted Signing build SmartScreen reputation.


CI/CD

Relevant for maintainers shipping desktop releases.

Installer build flow

Installers are built on GitHub-hosted runners (required for Apple notarization and SSL.com signing) and uploaded to S3 from the self-hosted mdb-prod pod.

Flavor Trigger S3 destination
preview PR with signed-macos-pkg or signed-windows-ev label s3://anton-installer/mindshub-cowork/{mac,windows}/previews/
stable Push to staging s3://anton-installer/mindshub-cowork/{mac,windows}/snapshots/ + mindshub-cowork-staging.{pkg,exe} + staging.json
prod Push to main (via the CalVer release) s3://anton-installer/mindshub-cowork/{mac,windows}/mindshub-cowork-{version}.{pkg,exe} + mindshub-cowork-latest.{pkg,exe} + latest.json

S3 layout

The bucket is anton-installer in us-east-1. It is private — no public reads, no public ACLs. Everything is served through CloudFront. AWS credentials come from the mdb-prod pod's IAM role (not GitHub secrets). The role has s3:GetObject, s3:PutObject, s3:ListBucket and s3:DeleteObject on arn:aws:s3:::anton-installer and arn:aws:s3:::anton-installer/*, granted by the AllowS3AntonInstallerAccess statement in templates/eks-oidc-roles/github-runner.tf in the mindsdb/terraform repo.

s3://anton-installer/
  mindshub-cowork/
    mac/
      latest.json                                  # prod — manifest: version, url, size, sha256
      staging.json                                 # stable — the same, for the staging ring
      mindshub-cowork-{version}.pkg                # prod — versioned, written once
      mindshub-cowork-latest.pkg                   # prod — alias, rewritten every release
      mindshub-cowork-staging.pkg                  # stable — alias, rewritten every staging push
      previews/mindshub-cowork-{version}-preview-{sha}.pkg
      snapshots/mindshub-cowork-{version}-stable-{sha}.pkg
    windows/
      latest.json
      staging.json
      mindshub-cowork-{version}.exe
      mindshub-cowork-latest.exe
      mindshub-cowork-staging.exe
      previews/mindshub-cowork-{version}-preview-{sha}.exe
      snapshots/mindshub-cowork-{version}-stable-{sha}.exe

Each manifest is named after the alias it supersedes, so a consumer already reading -latest or -staging knows which one is its own. Preview builds get no manifest: they are per-pull-request, and nothing should be advertising one.

A prod version's bytes are published once. If a versioned key already exists with different bytes (rebuilding a version re-signs it, and signing stamps a timestamp), the release fails rather than replacing them. Cut a new version instead of republishing one. The -latest and -staging aliases are then written as server-side copies of that key, so the alias always serves the exact build the manifest names.

That rule is prod's, because prod is where a version is cut once and its URL is advertised to users. Previews and stable snapshots overwrite. Both are named after a commit rather than a release and get rebuilt whenever anyone re-runs the job, so create-only would answer an ordinary re-run with "cut a new version" for a key that has no version to cut. They carry the 60-second alias TTL instead of immutable, since advertising a key as immutable while overwriting it is what strands a stale copy at the edge.

Wherever create-only does apply, only a genuine 404 from S3 counts as "not published yet"; a 403, a throttle or an expired token stops the release rather than being read as absence. The same rule governs the updater payloads under updates/, which are immutable in both channels.

Object headers are set at publish time, because CloudFront otherwise applies its own one-hour default to everything:

Object Cache-Control Why
Prod versioned installers public, max-age=31536000, immutable The bytes never change, so a resume can trust a validator that never moves
-latest / -staging aliases public, max-age=60 Rewritten every release; a minute bounds how long a stale edge copy outlives one
previews/ and snapshots/ builds public, max-age=60 Overwritten on a re-run, so immutable would strand the previous bytes at the edge
updates/ payloads and blockmaps public,max-age=31536000,immutable Named in a channel manifest by hash; the bytes behind that hash never change
latest.json / staging.json no-cache, no-store, must-revalidate A cached manifest would hide a release entirely

Installers also carry Content-Type: application/octet-stream and Content-Disposition: attachment; filename="mindshub-cowork-{version}.{pkg,exe}", so a file saved from the alias URL is still named after the version it actually is.

No sidecar .sha256 files are published. The checksum lives in latest.json, and OS-level signature verification (Apple notarization, SSL.com EV) remains the tamper guarantee.

Lifecycle tip: set bucket lifecycle rules to auto-expire objects under previews/ (e.g. 14 days) and snapshots/ (e.g. 60 days) to keep costs bounded. Prod objects have no expiration. The bucket has no abort_incomplete_multipart_upload rule today, so a failed upload leaves billable orphaned parts.

Public downloads at downloads.mindshub.ai

End users never hit S3 directly. The anton-installer bucket is fronted by a CloudFront distribution aliased to https://downloads.mindshub.ai (the legacy domain downloads.mindsdb.com also continues to work during the transition).

Start from the manifest, not the alias. latest.json names the immutable URL for the current release and the checksum to verify it against, which is the only combination that survives an interrupted download:

$ curl -sS https://downloads.mindshub.ai/mindshub-cowork/mac/latest.json
{
  "version": "2.26.8.10.1",
  "key": "mindshub-cowork/mac/mindshub-cowork-2.26.8.10.1.pkg",
  "url": "https://downloads.mindshub.ai/mindshub-cowork/mac/mindshub-cowork-2.26.8.10.1.pkg",
  "size_bytes": 220393119,
  "sha256": "…",
  "published_at": "2026-08-12T00:22:46.681Z"
}

The -latest aliases stay for the consumers that hardcode them, and still work:

The difference matters mid-download. An alias is rewritten on every release, so a transfer interrupted across one resumes with a validator that no longer matches and gets the whole body again instead of the tail. A versioned URL is written once, so the resume succeeds, and the manifest's sha256 is how a truncated file gets told apart from a good one.

Infrastructure:

CloudFront behavior:

  • Path mapping is 1:1 — the S3 key mindshub-cowork/mac/mindshub-cowork-latest.pkg is reachable at https://downloads.mindshub.ai/mindshub-cowork/mac/mindshub-cowork-latest.pkg.
  • Viewer-protocol policy is redirect-to-https.
  • GET / → 302 redirect to https://mindshub.ai via the downloads-root-redirect CloudFront Function (viewer-request).
  • GET /<missing key> (S3 403/404) → /redirect.html, 665 bytes of meta-refresh HTML pointing at https://mindshub.ai, served under a 404. It answered 200 until ENG-1432 corrected the two custom_error_response blocks, which is how a missing manifest could pass a status check.
  • Cache TTL: min 0, default 1 hour, max 24 hours. The default applies only to objects whose origin sends no Cache-Control, and min 0 is what lets no-store on latest.json be honoured. The 24-hour max caps edge retention, so max-age=31536000 on a versioned key is a year to the browser and a day at the edge.
  • Compression is enabled, but no installer content type is on CloudFront's compressible list. No query strings or cookies are forwarded, so a ?cachebust= suffix does nothing here.

Check these URLs by their bytes, not their status. A correct status still cannot tell a current object from a stale one, which is the failure an immutable key is most exposed to. And curl --retry fires only on a timeout or a 408/429/5xx, so it does not cover the case that actually needs waiting: a key created moments ago, shadowed by an edge that cached the 404 for it. Both checks in the release parse the body and compare a checksum, and wait in an explicit loop.

Cache invalidations: the aliases carry max-age=60, so a stale edge copy expires in a minute and a release needs no invalidation to become visible. Versioned URLs are immutable and never need one. Nothing in the release calls for an invalidation, though the mdb-prod runner does hold cloudfront:CreateInvalidation on * already, through the inline sam-deploy policy attached to the same role.

The upload, download, and setup checks watch different parts of this path. upload-installer-to-s3.yml verifies its own work before the release goes green: it re-reads every uploaded object from S3 and compares checksums, then fetches the manifest over the CDN, checks its sha256 against the installer the run built, and asserts the versioned URL answers a Range request with a 206 and a stable ETag. release-smoke.yml then downloads the result in a real Chromium, the way a user does, and runs nightly to catch a key that was correct at publish time and has since drifted. The release runs it against the prod channel only, passing the version it just tagged: staging.json is written by a push to staging, so asserting it from the prod pipeline would fail a release that worked, and without the version the suite would pass just as happily against the manifest the previous release left behind. The nightly run takes both channels and pins neither.

macos-setup-smoke.yml installs the published macOS .pkg and runs its own setup through Start server. It runs after each successful Stable or prod macOS upload, independently of the other platforms, and nightly at 07:30 UTC on both channels. The nightly Stable run checks out staging, so its harness matches the Stable package. Post-publish runs require the manifest to name that upload's URL; prod also requires the tagged release version. This detects a broken published installer but does not prevent someone downloading it before the check finishes.

Stable and prod pipelines finish their running release before starting a newer one, so a new push cannot cancel a published package's setup check. A setup failure fails build-installers; prod's dependent OTA UI publish and download smoke wait on that result and will skip on failure.

The check verifies the package checksum, signature, and notarization assessment, then installs it on a disposable GitHub-hosted macOS runner. Playwright opens the installed executable with a fresh home and browser profile. The app must report that all its data paths stay in that profile and that it cannot find an existing uv, including in system package-manager directories. A runner that already has uv fails preparation; the check does not remove shared tools or silently skip bootstrap.

The harness invokes the app's existing setup IPC without signing in or providing model credentials. It captures the real progress events and requires Install uv, Install cowork-server, Verify installation, and Start server to finish done, followed by a healthy server. A startup warning, error, cancellation, missing step, app exit, or 15-minute setup timeout fails. The installed renderer must remain bundled. Stable's filename version includes the channel and commit; the app's display version uses git describe, so the check correlates those forms instead of comparing them literally.

Every run retains named setup logs, step statuses, package identity, diagnostics, screenshots, and a trace in macos-setup-<channel> artifacts for 14 days. It does not upload the profile or credential files. A separate job sends failures to the engineering channel with the failing step and a run link, including outside a release freeze. The installed app receives no CI tokens. The notification reuses existing organization secrets; callers grant actions: read for the existing notifier.

Run the workflow from Actions, or after it reaches the default branch:

gh workflow run macos-setup-smoke.yml --ref staging -f channels=stable
gh workflow run macos-setup-smoke.yml --ref main -f channels=prod

For a historical check, select stable and provide snapshot-url plus its independently recorded snapshot-sha256. The URL must name a public macOS Stable snapshot. A failure keeps the failing setup step and sends the same notification. uv-tool-list.log also records the resolver's underlying error when an older app's Verify message omits it; uv-version.log records the installed uv version. Pinning the app does not pin the uv bootstrap or server packages it downloads today, so an old app may no longer reproduce an older failure. A dependency replay must be recorded separately from the ordinary user path.

This workflow does not cover authentication, chat, Windows, Linux, or every PR. Its fast failure/provenance tests run on PRs with npm run test:macos-setup-contract; npm run test:macos-setup itself refuses local execution because installing a package changes /Applications.

windows-setup-smoke.yml does the same for the published Windows .exe. It runs after each successful Stable or prod Windows upload and nightly at 07:45 UTC on both channels, with the same manifest pinning, nightly staging checkout, setup verdict, artifacts (windows-setup-<channel>) and failure notice. It requires a valid Authenticode signature, installs the installer silently (/S) for the runner's user, finds the executable from its uninstall registration, and opens it with a fresh profile and an allowlisted environment: the home, app-data and temp variables point into the profile, and PATH holds only Windows' own folders, so the runner's uv, Python and git stay invisible. Electron's home path follows Windows' known folder and stays the runner's; every other path the app reports must be inside the profile.

The Windows harness attaches an observer before entering the bundled setup screen, which starts installation exactly once. It supplies the renderer's onboarding consent and configured signal without saving credentials; the real installation checks, installer call and return value stay unchanged. Screenshots and traces show the actual setup UI, and after.png captures its success or failure before the screen advances.

Before it opens the app, the check trims the runner's root store to what a fresh Windows trusts. Windows ships part of its root list and downloads the rest the first time a program verifies a chain through Windows, but Python's own TLS never asks it to. The hosted image instead holds over 500 roots, including GlobalSign Root CA - R3 (pypi.org) and ISRG Root X1 (raw.githubusercontent.com) among the 14 in LocalMachine\AuthRoot, and turns those downloads off with the DisableRootAutoUpdate policy. So the check empties LocalMachine\AuthRoot, removes both named roots wherever they remain, and confirms LocalMachine\AuthRoot is empty while the downloads are still off. It then turns the downloads back on, lists each root it removed, and fails at "Trim root store" if Python's view still holds either. From then on, any program on the runner can download the roots it needs, as on a fresh machine, setup's own Windows downloads such as the uv installer included; roots-trimmed.json and roots-after-setup.json record which. The other preinstalled roots stay, so a new dependency on one of them would still pass here.

The harness backs up each removed root to RUNNER_TEMP, and an if: always() step restores the roots and the policy before the job ends. The runner reports the job's end over Windows TLS, so without that step the job stalls until GitHub cancels it.

Hosted runners run Windows Server, not Windows 11, and x64 only; a person's check on Windows 11 stays in the release checklist. Run it the same way as the macOS check (gh workflow run windows-setup-smoke.yml --ref staging -f channels=stable); a historical check takes a public Windows Stable snapshot URL and its SHA-256. Its contract tests run on PRs with npm run test:windows-setup-contract; npm run test:windows-setup refuses local execution because it installs an app and edits the machine's root stores.

Workflow files

Workflow Trigger Purpose
dev-build-deploy.yml Pull request Tests, PR env, and label-gated preview installers
staging-build-deploy.yml Push to staging Tests, staging image + rollout, stable installers
prod-build-deploy.yml Push to main Tests, prod image, CalVer tag + release, prod installers, OTA UI bundle
build-deploy.yml Called Build + push the web SPA image, then roll it out
build-installers.yml Called Both platforms' installers: build, sign, upload
pipeline-watchdog.yml Scheduled Alerts on runs that never started (startup_failure)
build-macos-pkg.yml Called Build + sign + notarize .pkg
build-windows-installer.yml Called Build + sign .exe
upload-installer-to-s3.yml Called Publish to S3, write the updater feed and latest.json, verify both over the CDN
release-smoke.yml Called after a prod release / nightly Download the published installers in a real Chromium and check them
macos-setup-smoke.yml After Stable/prod macOS upload / nightly / manual Install the published .pkg on a fresh profile and require every setup step through Start server to succeed
windows-setup-smoke.yml After Stable/prod Windows upload / nightly / manual Install the published .exe on a fresh profile and a fresh machine's root store, and require every setup step through Start server to succeed
publish-ui.yml Push to main / ui-v* tag / manual OTA UI bundle publish

Required GitHub Secrets

Apple signing: APPLE_DEV_ID_APP_CERT_B64, APPLE_DEV_ID_APP_CERT_PASSWORD, APPLE_DEV_ID_INSTALLER_CERT_B64, APPLE_DEV_ID_INSTALLER_CERT_PASSWORD, APPLE_ID, APPLE_APP_SPECIFIC_PASSWORD, APPLE_TEAM_ID, APPLE_INSTALLER_IDENTITY

Windows signing: SSL_USERNAME, SSL_PASSWORD, SSL_CREDENTIAL_ID, SSL_TOTP_SECRET

OTA UI publishing: RELEASES_TOKEN (fine-grained PAT scoped to mindsdb/antontron-releases)

No AWS secrets. The upload job runs on mdb-prod and picks up AWS credentials from the pod's IAM role. The role needs s3:GetObject and s3:PutObject on arn:aws:s3:::anton-installer/* — GetObject as well as PutObject, because the publish path reads a key back to check whether it already holds these bytes, and copies the versioned key onto the alias server-side.

OTA UI publishing setup

This section covers the one-time setup for publish-ui.yml only — it's independent of the installer flow above.

  1. Create mindsdb/antontron-releases as a public repo. It only holds release assets and latest.json — no source code.
  2. Create the RELEASES_TOKEN:
  3. Enable GitHub Pages on antontron-releases: Settings → Pages → Source "Deploy from a branch" → Branch gh-pages / / (root). The gh-pages branch is created automatically by the first workflow run.
  4. Verify with:
curl https://mindsdb.github.io/antontron-releases/latest.json

Updating the Icon

node scripts/generate-icon.js

Source SVG is in assets/icon.svg. The script renders to PNG then creates .icns (macOS) via sips + iconutil. Windows .ico is auto-generated by electron-builder.


Server release dependencies

Fresh installs, updates, repairs and rollback use scripts/install_release_server.py. It reads the exact dependency contract embedded in the selected server wheel, or from the same resolved Git commit. It verifies the server wheel against PyPI's SHA-256, checks that the complete dependency set resolves without additions, then verifies the installed versions and source identity. An unavailable pin or missing contract fails the operation.

On Windows the app also hands the consumer the public root certificates bundled with Electron's Node (tls.rootCertificates), and the consumer trusts them beside the Windows certificate stores. Python on Windows sees only the roots Windows has already downloaded, and Windows downloads a missing root only when a program verifies through Windows, so a fresh machine couldn't verify PyPI or GitHub. Certificate checks stay on, and roots an organization installs in the Windows store keep working. macOS and Linux keep their platform roots alone. The release-server-install Windows jobs remove PyPI's and GitHub's roots from the runner and make real downloads with and without the bundle.

Anton and registry dependencies move through a reviewed server release. A standalone Anton PyPI upload no longer changes an installed server. Normal application updates still select the build's stable or prerelease stream; selecting a release also selects its reviewed dependency set.

Before replacing a healthy older installation that has no contract, the consumer retains its actual versions, official Git identities and server wheel for repair or rollback. This local snapshot is never used to invent a fresh installation. A healthy custom source that cannot be preserved stops migration before replacement. A broken installation keeps its last saved snapshot. Registry wheels and Git source still depend on uv's local cache for fully offline restoration.

Desktop uv tool install enforces exact versions and checks the resulting inventory; it does not provide dependency-hash enforcement. Docker's native installer additionally uses --require-hashes --no-deps --only-binary :all: for registry packages. An explicit ANTON_REF selects code at one Git commit while retaining the server's registry versions. Preflight checks that source against the server's original Anton version requirement and the reviewed registry dependencies before replacing the environment. The supplied server-lock/ Docker option continues to enforce its complete independent requirements and source contract.

For a dependency update, review and publish the upstream server lock and its generated export, then select that server release. For a complete supplied Docker lock, regenerate and review it before rebuilding. Source-only releases never refresh either selection. Python, build backends, npm's existing lockfile and operating-system packages have their own update policies.

COWORK_SERVER_PACKAGE and its optional ANTON_PACKAGE remain explicit development overrides. They bypass the release consumer and resolve the developer's custom source. Leave them unset for reviewed releases. The deprecated scripts/install-anton.sh refuses installation; use Anton's release installer or this application's server installer.

Environment Variables

Variable Source Purpose
ANTON_ANTHROPIC_API_KEY Onboarding Anthropic API key
ANTON_OPENAI_API_KEY Onboarding Minds/OpenAI-compatible API key
ANTON_OPENAI_BASE_URL Onboarding Minds server URL (as OpenAI base)
ANTON_MINDS_API_KEY Minds panel Minds API key for datasources
ANTON_MINDS_URL Minds panel Minds server URL
ANTON_MINDS_MIND_NAME Minds panel Selected mind name
ANTON_MINDS_DATASOURCE Minds panel Selected datasource
ANTON_MINDS_DATASOURCE_ENGINE Minds panel Datasource engine type
ANTON_MINDS_SSL_VERIFY Minds panel SSL cert verification (true/false)
ANTON_PLANNING_MODEL Settings Model for planning tasks
ANTON_CODING_MODEL Settings Model for coding tasks
ANTON_MEMORY_MODE Settings Memory mode (autopilot/copilot/off)
ANTON_LANGFUSE_HEADERS Manual Set to 1 to emit Langfuse-* headers on LLM calls
DEV_MODE Manual Renderer source override (live = Vite dev server, full = bundled only, unset = production with OTA)
UI_UPDATE_MODE Manual OTA UI update behavior (auto / manual; default auto). Env-only support/QA escape hatch — no Settings UI control (ENG-858)
COWORK_SERVER_DISABLE_AUTOUPDATE Manual Set to 1 to skip automatic server updates on launch
COWORK_SERVER_PACKAGE Manual Development override with a literal uv spec; bypasses the release contract and channel/ref selection
ANTON_PACKAGE Manual Override anton install source (local path / uv spec); only honoured when COWORK_SERVER_PACKAGE is also set

Troubleshooting

App shows blank white screen

npm run build
ls dist/renderer/index.html

Server shows "Disconnected" immediately after launch

The packaged .app doesn't inherit shell PATH. Ensure cowork-server is installed: uv tool install cowork-server. Check that ~/.local/bin/cowork-server exists.

Backend takes a long time to come up on a first launch (Windows)

Expected, and it is waited out rather than killed. The first execution of a freshly installed uv venv makes Windows Defender scan hundreds of MB of DLLs and .pyd files, which can push the pre-uvicorn import phase past half a minute; every launch after that is warm and takes a couple of seconds.

The start wait is progress-aware: /health is polled for as long as the child process is alive, up to a hard cap (SERVER_START_CAP_MS, 180s, in src/shared/server-status.ts). A sidecar that dies is reported the moment it exits, with its exit code and stderr, rather than after the full budget. The renderer's status poll is derived from the same cap so the UI cannot declare the backend offline while the main process is still waiting.

One cap covers every build and platform, deliberately. A dev-only allowance means a start that passes locally can still be killed in a packaged build, so the failure would only ever reproduce on a customer's machine. The cap is therefore sized for the slowest case any build can hit (a dev source tree building a fresh .venv on a cold cache) and everything else inherits it. It costs nothing in the normal case: the wait ends the moment /health answers or the process dies, so the cap only ever bounds a process that is genuinely still alive and still starting.

Failures are classified rather than collapsed into one timeout message:

Diagnostics lastErrorKind Means
spawn-error The OS refused to launch the program (EPERM from antivirus, ENOENT from a broken shim). Nothing ran, so there is no log.
exited It ran and died during boot. Exit code + captured output are the evidence.
timeout Still alive and still silent at the cap. Almost always a very slow first import.
not-installed The backend or uv isn't on disk; re-run the installer.

After a failed start the whole process tree is killed (taskkill /F /T on Windows, process-group signal elsewhere), so a retry never collides with a leftover python.exe holding the port. If something else still holds it, the diagnostics name the PID.

Finding that PID on Windows means parsing netstat -ano, where the state column is both translated and variable in length (ABHÖREN on German, IN ASCOLTO on Italian, and a two-word state shifts every column after it). The lookup reads none of it: a listening socket is the only TCP row with an all-zero foreign address, and the PID is always the last column.

macOS Gatekeeper blocks unsigned app

# Dev only
xattr -cr "/Applications/MindsHub Cowork.app"

Tech Stack

Layer Tech
Framework Electron 45
Renderer React 19 + TypeScript + Vite 6
Backend FastAPI (Python, cowork-server via PyPI)
Markdown marked 17
Packaging electron-builder 25
Styling Tailwind CSS + custom theme

Built by MindsDB.

Diagnostics

See structured logging for defaults, troubleshooting overrides, retained evidence streams and rollout requirements.

About

Minds-cowork frontend app - Desktop & Web

Resources

Stars

13 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages