Run Cmdop on a headless server
This guide takes a server with no display from bare host to permanently
reachable: join it with cmdop join, decide its relay reachability, install the
background service, start it in strict permission mode, and mint a browser entry
link. The one decision that governs the rest is reachability — a LAN- or
loopback-only relay can never be attached to from elsewhere.
Use this path for a server that should remain reachable after your shell exits. You need a fleet join key and service-manager access on the target.
1. Install and join
Install Cmdop through the supported CLI installer, then join the server:
cmdop join <join-key>
cmdop statusJoining starts the agent unless --no-agent was used. If needed, start it
explicitly with cmdop start.
Point the server at the relay it belongs to with --server when it is not
already the active one:
cmdop join <join-key> --server https://relay.example.com2. Decide how the server is reachable
This is the step that decides whether you can ever open a terminal on this
server from somewhere else. A machine whose relay is LAN- or loopback-only is
not remotely attachable — cmdop connect <this-server> from your laptop
will refuse, no matter which credential you supply.
| Reachability | Reach | Use it for |
|---|---|---|
| LAN | Same host or a trusted private network | A server you will only ever administer from inside that network. |
| Public | The internet, through a Cmdop-managed subdomain | The usual choice for a headless server you administer remotely. |
| Own domain | The internet, on a domain you control, with automatic TLS | A server that must answer on your organization’s own name. |
For a server you intend to reach from elsewhere, create its relay in public mode on that server:
cmdop server create --mode public --subdomain <name> --no-prompt
cmdop server --detach
cmdop server statusLAN mode is plaintext by design — keep it on loopback or a trusted private network, and never expose its listeners directly to the internet. See self-hosted deployment for the full relay setup and Open an interactive remote terminal for the attach side of this precondition.
3. Install the background service
cmdop service install
cmdop service statusThe default is a user-level service. A system-level service requires host
administrator privileges and should be used only when your operating model
requires it. Cmdop supports the native service manager on Linux, macOS, and
Windows; inspect cmdop service install --help on the target for available
options.
4. Start with strict permissions
cmdop permissions mode strict
cmdop permissions listAdd narrow allow rules only after testing the intended task. See the permissions guide.
5. Open the workspace from another browser
On a headless host, cmdop open prints the available console URL instead of
trying to launch a browser. When you need an authenticated entry link, run:
cmdop open --linkThat link is single-use and expires in about two minutes. Mint it when you are ready to paste it into a browser, not in advance. Treat it as a credential: never put it in logs, tickets, or chat. If it lapses, run the command again.
If you skipped step 2, this is where it costs you: on a relay with no public address the command says so, and the link it prints only works in a browser on the server itself — which on a headless host is no browser at all. Give the relay a public address first, then mint the link.
6. Keep the update policy deliberate
A headless server updates itself by default. Decide whether that is what you want before you leave it unattended — see Update Cmdop for notify-only scheduling and version pinning.
7. Verify after reboot
cmdop service status
cmdop status
cmdop logs --lines 100If the server is unreachable from elsewhere after a reboot, re-check step 2 before re-checking credentials.
Common questions
How do I run Cmdop on a headless server?
Install Cmdop, join the server to the relay with cmdop join, install the
background service, set a conservative permission mode, and confirm cmdop status after reboot. Decide relay reachability before relying on remote
browser or terminal access.
Can I use Cmdop on a server without SSH?
Yes. Cmdop can keep the server reachable through its agent and relay relationship without making SSH the AI-agent workflow. For the assistant-focused path, see Run an AI agent on a server without SSH.
Why can I not open the headless server from my laptop?
Most often the relay reachability mode is wrong for that job. A LAN- or loopback-only relay can be valid for local administration, but remote terminal attach and remote browser entry need a public or own-domain relay door.
Cmdop