Terminal & Exec

PTY attachment, persistent sessions, and one-shot command execution — all over the cmdop relay, with the same OAuth-scoped auth and permission model as the rest of cmdop.

Open an interactive shell

Use cmdop connect vps-audi. You get a full PTY: colors, tab completion, vim, htop, tmux. Detach with Ctrl+D; the underlying terminal session keeps running on the target machine.

cmdop connect vps-audi
cmdop connect vps-audi   # hostname, display name, or UUID prefix all work

Example:

Connected to vps-audi
Session: 0193e2c1-7a8f-7b33-8c01

deploy@vps-audi:~$ _

The terminal verb registers under the connect tree; PTY plumbing lives in internal/connect/client/pty.go.

One-shot exec

For scripts, use cmdop exec <host> "<cmd>" (or the long form cmdop connect exec). Exit code mirrors the remote command. Useful flags: --timeout, --json, --env.

cmdop exec vps-audi "uptime"
cmdop exec prod-server "long-script.sh" --timeout 300
cmdop exec vps-bmw "uptime" --json
cmdop exec vps-audi --env DEBUG=1 --env API_KEY=xxx "./script.sh"

JSON output:

{
  "hostname": "vps-bmw",
  "command": "uptime",
  "exit_code": 0,
  "output": "14:23:01 up 42 days...",
  "duration_ms": 150
}

Persistent sessions

A session is the durable backing for an attached shell. Detaching from a cmdop connect does not kill it — the session keeps running, processes survive, and you can reattach from anywhere. Sessions live across daemon restarts.

cmdop session list
cmdop session attach 0193e2c1-7a8f-7b33-8c01   # prints metadata, marks attached
cmdop connect vps-audi                         # reattach interactively (live PTY)
cmdop session destroy 0193e2c1-7a8f-7b33-8c01

cmdop session attach currently reports session metadata; for a live interactive terminal use cmdop connect <host> (interactive takeover via session attach is planned, not yet implemented). See /cli/admin/session for the full session CLI.

Observer mode

Read-only attachment for training, audit, or live monitoring. Multiple observers can coexist with one driver; the driver sees a banner indicating observers are watching.

cmdop connect vps-audi --observe

Useful for: shadowing junior operators, compliance audit trails, monitoring long-running deployments.

Multiple drivers on one session

Two cmdop connect vps-audi invocations attach to the same session by default; both drivers see each other’s keystrokes. Useful for pair debugging:

# Operator A
cmdop connect vps-audi
$ tail -f /var/log/app.log
 
# Operator B (same session, both see each other)
cmdop connect vps-audi
$ # ...types alongside operator A

Keyboard shortcuts

Troubleshooting

• “Connection timeout” — run cmdop machines to verify the host is online; if offline, the target machine needs cmdop agent start.
• Lag / latency — traceroute to grpc.cmdop.com; tail cmdop logs -f to see relay reconnects.
• “Permission denied” — check the target machine’s permission ruleset (cmdop permissions list on that host).
• No machines listed — confirm the active fleet with cmdop connect --list (add --workspace <name> to check another) and verify the target’s daemon is up.

Related

• cmdop connect
• Sessions
• Files
• Permissions