Skip to Content

Connect

Connect is the surface CMDOP exposes for reaching machines you’ve registered. It shows up in three places — and they all dial through the same workspace, the same machine identity, and the same permission rules.

SurfaceUse it when
CLI — cmdop connectYou live in the terminal, scripting or attaching to one machine.
Desktop — Machines tab inspectorYou want a GUI machine list with per-machine chat in one click.
Agent-to-agent — ask_agent, ask_agentsYour agent needs to ask another agent on another machine to do something.

What replaced “SSH”

cmdop ssh is gone. The transport, identity model, and tool surface moved into a package called connect — Go: internal/connect/, CLI: cmd/cmdop/cmds/connect/, agent tool: connecttool. There is no plain SSH protocol underneath; CMDOP uses an outbound-only gRPC stream multiplexed over the relay, so machines don’t open ports and you don’t manage keys.

If your muscle memory still types cmdop ssh vps-audi, run cmdop connect vps-audi instead. Same intent, real verb.

The mental model

CMDOP machines belong to workspaces. A workspace is the unit of billing, membership, and credential scope. You can be a member of several workspaces; one is active at a time.

A machine has a stable UUID, a hostname, an optional friendly display name, and an online flag (heartbeat-driven). The fuzzy resolver accepts hostname, display name, unique prefix, or full UUID — the same way for CLI, Desktop, and agent tools.

A session is what you get after attaching. Sessions can be one-shot (cmdop connect exec) or persistent (remote sessions carry a 1 MiB ring buffer for multi-command shells). Some machines are protected by an attach password; CMDOP caches the resulting session token for 24 hours.

What you can do

  • Attach interactively — pick from a TUI or address by hostname: see Interactive attach.
  • Run one-shot commands — cmdop connect exec, returns structured output for scripts: see Exec.
  • Hand out access without inviting people — time-limited share links.
  • Talk to other agents — agents on different machines call each other via ask_agent / ask_agents.
  • Chat with a specific machine from Desktop — the Machines tab opens a direct-pipe inspector chat to the agent on that machine.
  • Chat as a specific machine from CLI — cmdop chat --machine X filters tools to remote-only and seeds the prompt; see CLI machine chat.

How auth resolves

Whatever surface you call from, credential resolution walks the same chain. First hit wins:

  1. Explicit --api-key flag.
  2. CMDOP_API_KEY env var.
  3. Named workspace (--workspace=X).
  4. Active workspace’s stored API key.
  5. Legacy cfg.Chat.GrpcAPIKey (one-shot migrated to the default workspace).
  6. OAuth access token from cmdop login.

Full chain with rationales lives in Credential resolver. Multi-workspace setup is the workspaces guide.

Last updated on
What is CMDOP