Connect a machine

To bring a machine onto a relay, install the cmdop binary on it and run cmdop join <join-key> with the fleet join key from your relay administrator. The agent makes an outbound connection to its relay and keeps it open; nothing dials in. A joined machine therefore works from behind NAT or a firewall with no port forwarding and no VPN.

Start with the machine you want Cmdop to operate. Install the CLI, get the fleet join key from the relay administrator, and join.

The guided way

On a machine that has never been set up, the first launch runs a short guided setup: it asks whether this machine should connect to an existing relay (paste the join key) or create one here, and ends by handing you to your door. It runs once; re-run it any time:

cmdop onboard

You can leave the setup at any step, run the agent locally, and join later.

The scriptable way

The same thing as explicit commands — use these for automation, or if you prefer the CLI:

cmdop join <join-key>
cmdop start
cmdop status

To join a specific relay, add --server <url> (with --insecure for a self-signed self-host):

cmdop join <join-key> --server https://my.example.com

Joining a fleet is symmetric across a hosted relay and a self-hosted one. There is no browser login and no device-code flow. cmdop start makes this machine reachable — it is not the command for attaching to another one.

Open the machine workspace

cmdop open

cmdop open starts the local relay if it is not already running, then opens the browser console. Running bare cmdop does the same on a desktop computer; on a headless host it opens the terminal chat instead.

Select the machine, begin or resume a conversation, and choose a project only when the work requires one.

Attach a terminal to another machine

cmdop connect <machine-name>

This needs three things:

1. The target is online — its agent is connected.
2. The target is reachable at its own relay door. A machine on a LAN-only relay cannot be attached to remotely, even though you can still work with it through the console.
3. You authenticate at that door, and supply the target machine’s connection PIN when one is armed. Your join key is not accepted there — it joins a machine to a relay, it is not a remote-terminal credential.

cmdop connect exec is narrower: it is scoped to this host today, with a 30-second default timeout. See One-shot execution before scripting it.

If connection fails

Run cmdop status on the machine you are starting — it reports the process, the server, the state, and the reason. For an authentication rejection, join again with a current join key. For a remote terminal that will not attach, check the three requirements above in order; reachability at the target’s own door is the one most often missing.

Related

• Install the CLI
• Run a long-lived agent
• Connect
• Troubleshooting

Common questions

How do I connect a machine to Cmdop?

Install the cmdop binary on that machine, get the fleet join key from the relay administrator, run cmdop join <join-key>, then confirm with cmdop status.

Does joining require a browser login?

No. A machine joins with cmdop join and the fleet join key. There is no browser login or device-code flow for bringing a machine online.

Why does a joined machine work behind NAT?

The agent makes an outbound connection to its relay and keeps it open. Nothing dials in to the machine, so no inbound port, port forwarding, or VPN is needed for the normal joined-machine path.