Connect a Machine

You ran the Quickstart and your laptop is online. The next step is the real CMDOP move: pair a remote machine — say, a VPS called vps-audi — and reach it from the laptop without touching SSH.

What you will do

Install CMDOP on the remote.
Pair it with your account using cmdop register.
Start its daemon.
See it appear in your laptop’s Machines tab.
Run a prompt that lands on that machine.

Total time: under ten minutes if you already have shell access to the remote.

1. Install CMDOP on the remote


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

That puts the cmdop binary on PATH. Confirm:


cmdop --version

2. Pair the machine to your account


cmdop register

This opens a device-flow URL in your browser (or prints one if you are headless — copy it). Sign in with the same account you used on the laptop, pick the workspace, confirm.

cmdop register does not start a daemon — it just stores credentials. The next step does.

On a server you cannot easily reach a browser from, run cmdop register and copy the device-flow URL to your laptop’s browser. The token lands on vps-audi once you complete the flow.

3. Start the daemon


cmdop agent start
cmdop agent status

You want ONLINE. If it shows STARTING for more than a few seconds, run cmdop agent logs -f to see what is taking time — usually the relay handshake.

For a server that should stay up across reboots, install the service unit:


cmdop service install

Linux installs a systemd unit; macOS uses launchd; Windows registers a service. From now on cmdop agent start happens automatically. See headless agent install for the full options.

4. See it on your laptop

Back on the laptop:

Desktop: open the Machines tab. vps-audi is there with a green dot.
CLI: cmdop connect --list prints the same table.

If it is missing, give it a few seconds for the heartbeat. Still missing? Confirm both machines are in the same workspace:


# On laptop and on vps-audi
cmdop connect workspace list

5. Run a prompt that lands on `vps-audi`

There are three ways. Pick whichever feels right.

A. Desktop inspector chat (direct pipe)

In the desktop Machines tab, click vps-audi. The inspector pane opens with a chat that talks directly to that machine’s agent. The local LLM is bypassed; the remote agent’s reply is the reply.

“Tail the last 50 lines of /var/log/syslog and tell me if anything looks unhealthy.”

You will see streaming tokens, tool starts/ends, and the final summary. Read more: Desktop inspector chat.

B. Local chat with delegation

In the Chat tab (or cmdop chat), prompt:

“Ask the agent on vps-audi to tail /var/log/syslog and summarize anything unhealthy.”

The local agent picks ask_agent("vps-audi", ...). The remote agent runs the work and replies. Your local LLM may then add commentary. See Agent Communication.

C. One-shot exec

If you just want to run a literal command:


cmdop connect exec vps-audi -- 'tail -50 /var/log/syslog'

No LLM in the loop — just the same Connect funnel for command execution.

What just happened, security-wise

The first remote prompt against vps-audi triggered its permission gate. Because there is no permissions.yaml yet, the gate fell through to the mode default (default mode = ask). You may have seen a modal asking whether to allow read_logs(/var/log/syslog).

A reasonable starting policy on vps-audi:


cmdop permissions mode strict
cmdop permissions allow 'execute_command(uptime)'
cmdop permissions allow 'execute_command(systemctl status *)'
cmdop permissions allow 'read_logs'
cmdop permissions allow 'read_file(/var/log/**)'

mode: strict means anything not explicitly allowed is denied. Loosen as you learn the workload. Read the Agent Permissions guide.

Add a second machine

Repeat steps 1–3 on mac-studio. Now your laptop’s Machines tab lists three: itself, vps-audi, and mac-studio. You can fan out:

“Ask vps-audi and mac-studio for their uptime and disk usage. Summarize.”

The local agent picks ask_agents(["vps-audi", "mac-studio"], ...) and aggregates the results. See multi-machine prompts.

Things to know early

Workspace boundaries are real. A machine registered into acme-prod is invisible from a session whose active workspace is acme-staging. Switch with cmdop connect workspace use <name>.

The remote daemon needs outbound TLS to the relay. It does not listen on any inbound port — there is nothing to firewall.
cmdop agent stop on the remote marks it offline immediately; UIs flip within a second.
A kill -9 of the daemon leaves the machine listed as ONLINE for ~90 s until the heartbeat TTL expires.

Where to go next

Wrap recurring work in a skill or schedule.

Workspaces, machines, share links, server-to-server.

Hands-on rule writing and audit reading.

Run CMDOP as a long-lived service on servers.