Skip to main content
An HQ workspace is a Supabase project that you own. Your agents, tasks, CRM, knowledge, routines, collections, and settings all live in that one database. The HQ UI connects to it at runtime — you can point a single UI at multiple Supabase projects and switch between them.

​
What a workspace contains

Each workspace is a complete, independent HQ environment: Nothing in a workspace references or depends on any other workspace. Deleting a Supabase project deletes everything in that workspace.

​
The workspace registry

The UI stores workspace metadata in two files on the ui-config Docker volume:
  • workspaces.json — array of workspace entries: label, emoji, Supabase URL, anon key, and a default flag
  • secrets.json — encrypted service-role keys for each workspace
When the UI container starts, it reads the registry and connects to the default workspace. The browser receives the workspace’s Supabase URL and anon key — it connects directly to your Supabase project, not through the UI server.

Workspace registry

Stored on the ui-config Docker volume. Survives container restarts and image updates. Back this up.

Runtime injection

The active workspace is selected at runtime and injected into the browser — no image rebuild needed when switching.

​
Switching workspaces

Use the workspace switcher in Settings → Database. When you switch:
  1. The UI server updates the active workspace in the registry
  2. The browser reloads with the new Supabase URL and anon key
  3. You re-authenticate against the new workspace’s Supabase Auth
Each workspace has its own user accounts. Signing into workspace A doesn’t sign you into workspace B — they’re separate Supabase projects with separate auth.

​
Multi-workspace support

One UI install can manage multiple Supabase projects. This is useful for:

​
Adding a workspace

Settings → Database → Add workspace. You’ll need:
  • The Supabase project URL (https://xyz.supabase.co)
  • The anon key (public, safe for browsers)
  • The service-role key (secret, stored encrypted)
The UI validates credentials before saving. You can also add workspaces via the /api/workspaces endpoint.

​
Isolation model

HQ enforces isolation at two levels:

​
Single-tenant default

Self-hosted installs use a single default tenant ID (00000000-0000-0000-0000-000000000000). All authenticated users in a workspace see the same data. This is by design — HQ is workspace-level admin software, not a multi-user SaaS with per-user permissions. If you need per-user access control within a workspace, restrict who can sign up for your Supabase project (disable email signup, use invite-only). See Security model.
For most teams, one workspace is enough. Add a second when you genuinely need data isolation — not just organizational separation. Use streams, labels, and agent hierarchy within a workspace to organize work.