Multi-Workspace Setup

Many CMDOP users belong to two or more workspaces — personal plus employer, or staging plus production. CMDOP keeps them fully isolated and lets you switch context per call or globally.

Why two workspaces

Common patterns:

Personal + employer — keep personal experiments off the work bill.
Staging + production — separate machines, separate API keys, separate audit.
Client A + client B — agency / consulting setups.

Workspaces are the strongest isolation boundary in CMDOP — machines, members, sessions, API keys, and audit do not bleed across.

Listing what you have


cmdop connect workspace list

Active workspace is marked with *. Each row: name, server, masked API key, last synced.

Adding a workspace via API key


cmdop connect key set <key> --workspace acme-prod

The key is stored in ~/.cmdop/ssh_workspaces.json (mode 0600). You can use the --api-key / -k flag or the CMDOP_API_KEY environment variable to override per call.

Adding workspaces via OAuth


cmdop login                        # device flow
cmdop connect workspace sync       # pull authoritative list

After OAuth, every workspace you belong to lands in ssh_workspaces.json with a RemoteID and a LastSyncedAt timestamp.

Switching active workspace


cmdop connect workspace use <name>

The daemon reconnects with the new WorkspaceID. Do not try to mutate the workspace ID manually — the auth manager owns that field. See Concepts: daemon for the connection flow.

Per-call override

Three override mechanisms, in resolver order:

--api-key=<key> flag.
CMDOP_API_KEY environment variable.
--workspace=<name> flag (uses the named workspace’s stored key).
(no flag) — active workspace from ssh_workspaces.json.
Legacy cfg.Chat.GrpcAPIKey — one-shot migration.
OAuth access token — fallback.

Useful in scripts that target multiple workspaces from one host.

Server-side workspace migration

When an OAuth user switches workspaces in the cabinet, the server auto-migrates the machine record using the live workspace_id in the token. Your client keeps doing what it does — reconnects pick up the new ID. This is invisible to scripts; it just works.

Per-workspace gRPC server override

Workspaces can pin to custom gRPC endpoints (on-prem, staging):


cmdop connect workspace add my-onprem --server grpc.cmdop.example.com:443 --api-key <key>

The Workspace.Server field overrides the default endpoint just for that workspace.

OAuth-managed workspaces and API-key workspaces coexist. The resolver prefers explicit (--api-key / env / named) over implicit (active / OAuth).

Sessions on workspace A are not visible from workspace B. Switching mid-task closes your current view — finish your work before switching, or open a second terminal with --workspace=other.

Worked example


# Start the day on personal projects
cmdop connect workspace use personal
cmdop connect --list
# laptop-mark, raspberrypi-1
 
# Switch to work
cmdop connect workspace use acme-prod
cmdop connect --list
# prod-1, prod-2, db-1, edge-{us,eu,ap}
 
# One-off command on a staging machine without switching
cmdop --workspace=acme-staging connect prod-1 exec 'uptime'

Sample `ssh_workspaces.json`


{
  "active": "acme-prod",
  "workspaces": {
    "personal": {
      "name": "personal",
      "api_key": "**REDACTED**",
      "remote_id": "wks_01HABCDEF",
      "added_at": "2026-01-12T08:00:00Z",
      "last_synced_at": "2026-04-25T09:14:22Z"
    },
    "acme-prod": {
      "name": "acme-prod",
      "api_key": "**REDACTED**",
      "server": "grpc.cmdop.com:443",
      "remote_id": "wks_01HZZZZZZ",
      "added_at": "2026-02-03T11:22:00Z",
      "last_synced_at": "2026-04-25T09:14:22Z"
    }
  }
}