First Connection

TL;DR

Run cmdop terminal my-server to open an interactive shell on any remote machine. Sessions persist after disconnect — close your laptop, reopen later, and pick up where you left off. Multiple clients can attach to the same session simultaneously, including read-only observer mode. Full PTY support: colors, resize, signals, and interactive programs.

How do I connect to a remote machine?


# Open interactive terminal to your server
cmdop terminal my-server

You’re now in an interactive shell on the remote machine:


Connected to my-server
Session: a1b2c3d4-e5f6-7890-abcd-ef1234567890

deploy@my-server:~$ _

What basic operations can I run?

Run Commands


# Check current working directory on remote machine
pwd
# /home/deploy
 
# List all files including hidden ones
ls -la
 
# Check OS and kernel info
uname -a
hostnamectl

Navigate


# Change to log directory on remote machine
cd /var/log
 
# Environment state is preserved between commands
echo $PWD
# /var/log

Long-Running Commands


# Start a long build process — output streams in real-time
./build.sh
 
# Even multi-hour processes stream output continuously

How do sessions persist after disconnect?

Disconnect and Reconnect

Try this experiment:


# Start a long-running command
ping google.com

Now close your terminal window (Cmd+W or Ctrl+D).

Reconnect:


# Reattach to the same persistent session
cmdop terminal my-server

The ping is still running! You see the continued output.

This is the key difference from SSH — the session persists independently of your connection.

Open two terminal windows:

Window 1:


cmdop terminal my-server
echo "Hello from window 1"

Window 2:


# Both windows attach to the same session
cmdop terminal my-server
# You see "Hello from window 1" appear!
echo "Hello from window 2"

Both windows are attached to the same session. You see each other’s output in real-time.

What is observer mode?

Watch without the ability to interfere:


# Read-only mode — see everything, keystrokes blocked
cmdop terminal my-server --observe

What terminal features are supported?

Signals

Send signals to running processes:


# Start a process
sleep 1000
 
# Press Ctrl+C — SIGINT is forwarded correctly to remote process

Resize

Resize your terminal window. The remote PTY adjusts automatically.

Colors and Special Characters

Full ANSI support:


# Color output works natively
ls --color=auto
 
# Interactive TUI programs work: htop, vim, tmux
htop
vim file.txt
tmux

How do I check session status?

Check Status


# From CLI (not inside session) — shows session details
cmdop session info
 
# Output:
# Session ID:    a1b2c3d4-e5f6-7890-abcd-ef1234567890
# Machine:       my-server
# Status:        CONNECTED
# Created:       2026-02-14 10:30:00
# Attached:      2 clients (1 operator, 1 observer)

List Sessions


# Show all active sessions across machines
cmdop sessions
 
# MACHINE       SESSION ID    STATUS      CLIENTS
# my-server     a1b2c3d4...   connected   2
# staging       e5f6a7b8...   connected   1

How do I transfer files during a session?

While connected, you can also use file commands:


# List remote files (from your laptop, not inside session)
cmdop files ls my-server:/var/log
 
# Download a remote file to local machine
cmdop files get my-server:/var/log/app.log ./
 
# Upload a local file to remote machine
cmdop files put ./config.yaml my-server:/app/

What are the key session features?

Feature	What It Does
Session persistence	Commands keep running after disconnect
Multi-client	Multiple people/devices on same session
Observer mode	Watch without interfering
Full PTY	Colors, resize, signals all work
Real-time streaming	Output appears instantly

What are the key takeaways?

Sessions are objects, not connections — They persist in the database
Disconnect ≠ terminate — Your processes keep running
Multiple clients welcome — Collaborate or switch devices
No port forwarding needed — Outbound-only connections

Troubleshooting

Session Not Found


# Check if agent is running on remote machine
cmdop machines
# Shows 'connected' or 'offline'
 
# If offline, restart agent on the server
cmdop connect

Lag or Delay


# Check network connectivity to Control Plane
ping grpc.cmdop.com
 
# Check session health and attached clients
cmdop session info

Wrong Machine


# List all machines in your workspace
cmdop machines
 
# Connect to the correct hostname
cmdop terminal correct-hostname

First Automation — Write Python scripts with the SDK
Sessions — Deep dive into session architecture
Multi-Client — Collaboration patterns