Skip to Content

Install Agent

TL;DR

Install the Cmdop agent with curl -sSL cmdop.com/install.sh | bash on macOS/Linux or iwr -useb cmdop.com/install.ps1 | iex on Windows. The agent uses outbound-only connections — no firewall rules or port forwarding needed. Supports Linux (x86_64, arm64), macOS (Intel + Apple Silicon), and Windows 10+. Run as a systemd/launchd service for persistence.

How do I install the agent?

macOS / Linux

curl -sSL cmdop.com/install.sh | bash

Windows (PowerShell)

iwr -useb cmdop.com/install.ps1 | iex

What files does the installer create?

/usr/local/bin/cmdop    # Binary
~/.cmdop/               # Config directory
├── config.yaml         # Configuration
└── auth.json           # OAuth token (after login)

How do I install manually without the script?

1. Download Binary

# Detect platform (linux/darwin) and architecture (amd64/arm64)
PLATFORM=$(uname -s | tr '[:upper:]' '[:lower:]')
ARCH=$(uname -m)
 
# Map uname architecture to Go naming convention
case $ARCH in
  x86_64) ARCH="amd64" ;;
  aarch64|arm64) ARCH="arm64" ;;
esac
 
# Download the latest release binary for your platform
curl -LO "https://github.com/cmdop/cmdop/releases/latest/download/cmdop-${PLATFORM}-${ARCH}"

2. Install

# Make the binary executable
chmod +x cmdop-*
 
# Move to a directory in your PATH
sudo mv cmdop-* /usr/local/bin/cmdop
 
# Verify installation succeeded
cmdop version

How do I authenticate after installation?

After installation, authenticate with your account:

# Opens browser for OAuth — creates ~/.cmdop/auth.json with your token
cmdop login

This creates ~/.cmdop/auth.json with your OAuth token.

How do I connect to the Control Plane?

Start the agent — it connects outbound to the Control Plane over gRPC/TLS:

# Run in foreground (for testing)
cmdop connect
 
# Or with debug logging to diagnose connection issues
cmdop connect --debug

You should see:

✓ Connected to Control Plane
✓ Registered as: my-hostname
✓ Session ready

How do I run the agent as a background service?

systemd (Linux)

# Create service file
sudo tee /etc/systemd/system/cmdop.service << 'EOF'
[Unit]
Description=CMDOP Agent
After=network.target
 
[Service]
Type=simple
User=deploy
ExecStart=/usr/local/bin/cmdop connect
Restart=always
RestartSec=10
 
[Install]
WantedBy=multi-user.target
EOF
 
# Enable and start
sudo systemctl daemon-reload
sudo systemctl enable cmdop
sudo systemctl start cmdop
 
# Check status
sudo systemctl status cmdop

launchd (macOS)

# Create plist
cat > ~/Library/LaunchAgents/com.cmdop.agent.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.cmdop.agent</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/cmdop</string>
        <string>connect</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
</dict>
</plist>
EOF
 
# Load
launchctl load ~/Library/LaunchAgents/com.cmdop.agent.plist

Windows Service

# Install as service (requires admin)
cmdop service install
 
# Start
cmdop service start
 
# Check status
cmdop service status

Which platforms are supported?

Linux

  • Works on any distribution with glibc 2.17+
  • Tested on Ubuntu 18.04+, Debian 10+, CentOS 7+, Alpine 3.12+
  • ARM64 supported (Raspberry Pi, AWS Graviton)

macOS

  • Requires macOS 10.15 (Catalina) or later
  • Both Intel and Apple Silicon supported
  • May need to allow in Security preferences

Windows

  • Requires Windows 10 or later
  • PowerShell support included
  • cmd.exe also works

How do I configure the agent?

Config File

Location: ~/.cmdop/config.yaml

# Server settings
server:
  address: grpc.cmdop.com:443
  tls: true
 
# Agent behavior
agent:
  heartbeat_interval: 30s
  reconnect_max_attempts: 1000
 
# Logging
log:
  level: info     # debug, info, warn, error
  format: json    # json, text

Environment Variables

# Override server address
export CMDOP_SERVER_ADDRESS=grpc.cmdop.com:443
 
# Debug logging
export CMDOP_LOG_LEVEL=debug
 
# gRPC debug
export CMDOP_GRPC_DEBUG=1

How do I verify the installation?

# Check version
cmdop version
 
# Check auth status
cmdop auth status
 
# Check connection
cmdop status

What are the security implications?

User Permissions

Agent runs as the user who installed it:

# If installed as 'deploy' user
$ whoami
deploy
 
# All commands execute as 'deploy'
# No automatic root/sudo

Workspace Binding

Agent is bound to one workspace via OAuth token:

  • Can only register to that workspace
  • Cannot access other workspaces
  • Workspace determined by token

Network Security

  • All connections are outbound HTTPS/gRPC
  • TLS 1.3 encryption
  • No listening ports on agent machine

Troubleshooting

Connection Failed

# Check network
curl -I https://grpc.cmdop.com
 
# Check firewall allows outbound HTTPS
# Check proxy settings

Authentication Error

# Re-authenticate
cmdop logout
cmdop login

Permission Denied

# Check file permissions
ls -la ~/.cmdop/
 
# Fix if needed
chmod 700 ~/.cmdop/
chmod 600 ~/.cmdop/auth.json

Next

Last updated on
Overview