Open an interactive remote terminal
cmdop connect <machine> opens a live shell on a machine running a Cmdop agent,
with no SSH daemon on either side. Check one thing before you try: a machine on
another host is attachable only if its relay is public or on your own domain, so
a LAN- or loopback-only target refuses regardless of which credential you offer.
You authenticate at the target’s door, with the target’s credentials.
The target needs a running agent and, for a cross-machine attach, a reachable door — nothing more.
Before you connect
A machine on another host is remotely attachable only if it exposes a public
or own-domain relay. A machine whose relay is LAN- or loopback-only has no
internet-facing door, and cmdop connect reports that it is not remotely
attachable. Make it reachable by creating its relay in public mode on that
machine, or attach from that host directly.
cmdop server create --mode publicThis is the most common reason an attach fails, and it is a property of the target, not of your credentials. See Run Cmdop on a headless server for the full reachability decision.
List the machines in your active relay:
cmdop connect --list
cmdop connect --list --onlinecmdop machines shows machines across all of your relay contexts, while
cmdop connect --list shows only the active one. The roster and terminal
admission are separate checks: knowing about a machine does not mean it
currently accepts a terminal connection.
Connect
cmdop connect <machine>The name argument accepts a hostname, a display name, a unique prefix, or the machine UUID. If a partial name matches more than one machine, use the full display name or the UUID.
Run cmdop connect with no name to use the interactive picker. The picker
deliberately shows only other online machines: it hides this machine,
offline machines, and coordinator members, because none of those is an
attachable terminal. Add --all to include offline machines and this machine;
coordinators stay hidden in every mode. If your machine “isn’t in the list”,
this filtering is almost always why.
What you are asked for
Attaching to your own machine and attaching to another machine are different flows:
| Target | What happens |
|---|---|
| Your own machine | Attaches immediately. No prompt, and an armed connection PIN is bypassed — a local operator is already trusted. |
| Another machine | Reached at that machine’s door, so Cmdop prompts for that machine’s console password, and for its connection PIN if one is armed. |
Your own sign-in or join credential is not accepted by another machine’s door. Each machine admits attachers on its own terms.
The console password is never stored for a remote attach — you type it each time. The connection PIN can be saved per machine so future attaches stop prompting for it:
cmdop connect password set <machine>
cmdop connect password status <machine>
cmdop connect password list
cmdop connect password clear <machine>Saved PINs are held in the operating system’s credential store, keyed by the machine’s immutable ID. A PIN is not the console password, the fleet join key, or an SDK token — see credential boundaries.
Do not put terminal credentials in shell history or scripts. cmdop start is a
different operation: it starts the agent on the machine where you run it.
Watch output as it runs
An interactive terminal is the right surface when a person needs to watch output and respond while a command runs. It is live terminal output, not an event log — do not treat a reconnect as a guarantee that every byte produced during the disconnect is replayed.
Choose the surface by outcome:
| Need | Use |
|---|---|
| Watch and interact with a shell | cmdop connect <machine> |
| Capture one command on this host | cmdop connect exec <machine> -- <command> |
| Consume typed AI-agent progress | SDK streaming |
If the terminal disconnects during a state-changing operation, inspect the target before retrying. The command may still have taken effect even though the client did not receive its final output.
When the connection fails
| Symptom | What to check |
|---|---|
| “not remotely attachable: no public door” | The target’s relay is LAN- or loopback-only. Run cmdop server create --mode public on it. |
| “machine not found” | Run cmdop connect --list; confirm spelling and that it has joined the active relay. |
| Ambiguous match | Use the full display name or the machine UUID. |
| No machines offered by the picker | It hides self, offline machines, and coordinators. Try cmdop connect --all, or cmdop start to make this machine reachable. |
| Wrong password or PIN | The credential must belong to the target, not to your machine. |
Run cmdop status on the target and cmdop logs -f there for operational
detail.
For a bounded command on this host rather than a shell, see one-shot execution. It is not a cross-host replacement for the interactive path.
Common questions
How do I open a remote terminal without SSH?
Use cmdop connect <machine> against a joined machine running the Cmdop agent.
For a cross-machine attach, the target must have a public or own-domain relay
door, and you authenticate at that target’s door.
Why is a machine not remotely attachable?
The target’s relay is usually LAN- or loopback-only. That machine can still be online and reachable through the console or fleet tools, but interactive terminal attach needs the target’s own public or own-domain relay door.
Which credentials does terminal attach use?
Attaching to another machine uses that target relay door’s console password and the target machine’s connection PIN when one is armed. Your local join key or your own machine’s credential is not accepted at another machine’s door.
Cmdop