Agents

TL;DR

A CMDOP agent is a lightweight Go binary that runs on target machines and executes operations remotely. Unlike SSH or RDP, the agent uses an outbound-only connection model — it initiates all connections over HTTPS/gRPC, requiring no open ports. Each agent registers to a single workspace via OAuth and supports terminal sessions, file operations, system telemetry, and browser automation.

The CMDOP agent is a lightweight process that runs on target machines and executes operations. Its key innovation is the outbound-only connection model.

What is the outbound-only architecture?

Unlike traditional remote access (SSH, RDP) that requires open ports, CMDOP agents initiate all connections outbound:

Traditional (SSH):

Problems:

Open port = attack surface
Firewall configuration required
CGNAT blocks inbound connections
Corporate firewalls block non-standard ports

CMDOP:

Benefits:

No open ports on target machine
Works through any firewall (HTTPS allowed)
Works through CGNAT
Works through corporate proxies

Why does outbound-only matter?

1. No Port Forwarding

Home servers behind NAT don’t need port forwarding:


# Comparison: traditional SSH vs CMDOP for NAT traversal
Without CMDOP:
  Router (NAT) ─┬─ Port 22 → Server
                └─ Port 80 → Server
  Configure each port manually

With CMDOP:
  Agent ───▶ HTTPS to relay
  No router configuration needed

2. CGNAT Compatible

Carrier-grade NAT (used by many ISPs) blocks all inbound:


# CGNAT assigns shared IPs, blocking all inbound connections
CGNAT:
  Your IP: 100.64.x.x (shared)
  SSH: ❌ Impossible
  CMDOP: ✅ Outbound works

3. Corporate Firewall Friendly

Corporate networks typically allow HTTPS:


# Corporate firewalls block most inbound/outbound, but allow HTTPS
Corporate Firewall:
  Inbound: ❌ All blocked
  Outbound SSH: ❌ Blocked
  Outbound HTTPS: ✅ Allowed
  CMDOP: ✅ Uses HTTPS/gRPC

What can agents do?

How does terminal execution work?

The agent manages PTY (pseudo-terminal) sessions:

Features:

Multiple concurrent PTY sessions
Shell detection (bash, zsh, PowerShell)
ANSI escape sequence handling
Window resize support
Signal forwarding (SIGINT, etc.)

What file operations are supported?

Direct file system access:

Operation	Description
`list`	Directory listing
`read`	File content (chunked for large files)
`write`	Create/overwrite files
`copy`	Copy files/directories
`move`	Move/rename
`delete`	Delete files/directories
`info`	File metadata
`archive`	Create zip/tar archives

What system telemetry does the agent report?

Agent reports system metrics:


# Heartbeat payload sent every 30 seconds to the Control Plane
Heartbeat:
    cpu_percent: 45.2
    memory_percent: 62.1
    disk_percent: 78.5
    battery_percent: 85  # Mobile only
    uptime_seconds: 123456
    local_ips: ["192.168.1.10"]

How does browser automation work?

Agent can control browsers (requires Camoufox):

Page navigation
Element interaction
Network capture
Screenshot capture

Which platforms are supported?

Platform	Binary	Shell	Features
macOS	`cmdop-darwin-*`	bash, zsh	Full
Linux	`cmdop-linux-*`	bash, sh	Full
Windows	`cmdop-windows-*`	PowerShell, cmd	Full
iOS	In-app	None	Files, telemetry

How does the mobile agent (iOS) differ?

iOS agents have constraints:


// iOS agent registers without shell support due to sandbox restrictions
register.hasShell_p = false      // No shell execution
register.supportedShells = []    // Empty
register.deviceType = "ios"

Capabilities:

File operations (within sandbox)
System telemetry
Push notifications
Shell execution
Browser automation

What is the agent lifecycle?

How does agent startup work?


# Startup sequence: load config, authenticate, connect, and register
1. Load configuration
   └─ ~/.cmdop/config.yaml

2. Load OAuth token
   └─ ~/.cmdop/auth.json

3. Connect to Control Plane
   └─ Outbound gRPC/TLS

4. Send RegisterRequest
   ├─ session_id (UUID)
   ├─ hostname
   ├─ platform
   ├─ supported_shells
   └─ system_info

5. Receive StartSessionCommand
   └─ Ready for operations

What does the agent do while running?


# Main agent loop: heartbeats, command execution, and auto-reconnect
┌─────────────────────────────────────────┐
│               Agent Loop                 │
├─────────────────────────────────────────┤
│                                          │
│  Every 30 seconds:                       │
│    → Send heartbeat with metrics         │
│                                          │
│  On ControlMessage:                      │
│    → Execute command                     │
│    → Stream output back                  │
│                                          │
│  On disconnect:                          │
│    → Attempt reconnect (backoff)         │
│    → Up to 1000 attempts                 │
│                                          │
└─────────────────────────────────────────┘

How does reconnection work?

Exponential backoff on disconnect:

Attempt	Delay
1	1 second
2	2 seconds
3	4 seconds
4	8 seconds
…	…
Max	30 seconds

With 10% jitter to prevent thundering herd.

How is agent security enforced?

How does privilege escalation prevention work?

Agent runs as the user who installed it:


# Agent inherits the installing user's permissions — no sudo or root
# Installed as 'deploy' user
$ whoami
deploy
 
# Commands execute as 'deploy'
# No sudo, no root, no elevation

How does PTY security work?

ANSI escape sequence filtering:


# Dangerous ANSI sequences are filtered; normal commands pass through
Input:  \x1b]0;evil\x07       # Attempt to change title
Output: [filtered]             # Blocked

Input:  ls -la                 # Normal command
Output: drwxr-xr-x ...         # Allowed

How is workspace isolation enforced?

Agent is bound to one workspace via OAuth:


# OAuth token restricts the agent to a single workspace
Token contains:
  workspace_id: "ws_abc123"
  workspace_name: "acme-corp"

Agent can only:
  - Register to this workspace
  - Accept commands from this workspace
  - Report to this workspace

How do you install the agent?

Quick Install


# One-line install script for macOS/Linux
# macOS / Linux
curl -sSL cmdop.com/install.sh | bash
 
# One-line install script for Windows via PowerShell
# Windows
iwr -useb cmdop.com/install.ps1 | iex

Manual Install


# Download the platform-specific binary from GitHub releases
curl -LO https://github.com/cmdop/cmdop/releases/latest/download/cmdop-$(uname -s)-$(uname -m)
 
# Make the binary executable
chmod +x cmdop-*
 
# Move binary to a directory in your PATH
sudo mv cmdop-* /usr/local/bin/cmdop

How do you authenticate?


# Open browser-based OAuth login flow
cmdop login
 
# Establish outbound gRPC connection to the Control Plane
cmdop connect

How do you configure the agent?

Config File

Location: ~/.cmdop/config.yaml


# Server configuration — gRPC endpoint and TLS toggle
server:
  address: grpc.cmdop.com:443
  tls: true
 
# Agent settings — heartbeat frequency and max reconnect attempts
agent:
  heartbeat_interval: 30s
  reconnect_max_attempts: 1000
 
# Logging — output level and format
log:
  level: info
  format: json

What environment variables are available?


# Override server address (useful for self-hosted or dev environments)
CMDOP_SERVER_ADDRESS=grpc.cmdop.com:443
# Set log verbosity: debug, info, warn, error
CMDOP_LOG_LEVEL=debug
# Enable low-level gRPC frame logging for troubleshooting
CMDOP_GRPC_DEBUG=1  # Enable gRPC debug logging

Troubleshooting

Agent Won’t Connect


# Verify network connectivity to the Control Plane
curl -I https://grpc.cmdop.com
 
# Start the agent with verbose debug output
cmdop connect --debug
 
# Verify OAuth token is valid and not expired
cmdop auth status

Agent Keeps Disconnecting


# Check firewall isn't blocking outbound
# Check proxy settings
# Verify stable internet connection
 
# Show current connection state and session info
cmdop status

Permission Denied


# List permissions on the CMDOP config directory
ls -la ~/.cmdop/
 
# Fix file permissions: auth.json should be user-read/write only
chmod 600 ~/.cmdop/auth.json
# Fix directory permissions: .cmdop should be user-accessible only
chmod 700 ~/.cmdop/

Sessions — Session lifecycle
How It Works — Connection flow
Security — Security model