Fleets & workspaces

A fleet is the boundary around a set of machines you control — and the credential boundary for cmdop connect. It holds the API key (or OAuth token) used to reach the machines in it. Most users have one fleet; teams with separate environments or relay deployments have several.

Selecting a fleet per command

Use --workspace <name> on any cmdop connect invocation to target a specific fleet without changing your active one:

# Use a named fleet for this call only
cmdop connect --workspace staging vps-audi
cmdop connect --workspace production exec prod-api-1 -- uptime
cmdop connect --list --workspace production

The same call also accepts --api-key or --server for direct overrides:

# Raw API key override
cmdop connect --api-key ck_live_xxxxx exec prod-api-1 -- uptime
 
# Point at a self-hosted relay
cmdop connect --server grpc.internal:443 --list

Local store

Fleet credentials live in ssh_workspaces.json (mode 0600) inside your cmdop config directory. The file is per-user and never synced over the network. The active fleet name and its API key are stored here.

{
  "active": "production",
  "workspaces": [
    {
      "name": "production",
      "api_key": "ck_live_***",
      "remote_id": "ws_8f23...",
      "remote_name": "Acme Production",
      "last_synced_at": "2026-04-22T11:04:31Z"
    },
    {
      "name": "staging",
      "api_key": "ck_test_***"
    }
  ]
}

Credential resolution

When cmdop connect needs a credential it walks this chain (first match wins):

1. --api-key flag
2. CMDOP_API_KEY environment variable
3. The fleet named by --workspace
4. The active fleet’s stored key
5. The OAuth access token from cmdop login

See credential resolver for the full chain.

Syncing the fleet list

After joining a new fleet in the web cabinet, pull the list locally by logging in again:

cmdop login

OAuth tokens carry your fleet membership. After a fresh login the stored fleet list is updated automatically on the next connect.

API keys per fleet

Create API keys in the web cabinet under Settings → API Keys. Each key is scoped to a fleet. To use a specific key:

# Set via environment variable (CI-friendly)
export CMDOP_API_KEY=ck_live_xxxxx
cmdop connect --list
 
# Or pass per-call
cmdop connect --api-key ck_live_xxxxx exec prod-server -- whoami

Switching the active fleet

The active fleet is stored in ssh_workspaces.json under "active". To change it, edit the file directly or use cmdop login to re-authenticate against the account that owns the fleet you want.

Related

• Credential resolver
• cmdop connect
• Authentication
• Identity & the private contour