Add a machine (headless / Linux)

A machine is a computer that runs your agents and terminals and connects them to your workspaces through the relay. It is the Cyborg daemon running on that computer, which is why the commands below say cyborg daemon. This page adds a new one: a server, a Raspberry Pi, or any headless Linux box.

There are two ways to attach a machine:

• Claim it for your account (steps 1 to 5 below). The machine is yours, and you decide who else can use it.
• Join it as a workspace machine with a setup code (next section). No login on the machine is needed. See also Connect a workspace machine.

Join with a setup code

If a workspace owner or admin gave you a setup code (it looks like CYB-XXXX-XXXX), run this on the machine instead of logging in and claiming:

cyborg daemon join --code CYB-XXXX-XXXX

It needs no account and no claim. You can also set the code in the CYBORG_SETUP_CODE environment variable. Codes are single use and expire; see Connect a workspace machine for how an admin creates one.

1. Install the CLI

On Linux the CLI ships with the headless daemon installer. It bundles its own runtime, so no system Node is required:

curl -fsSL https://raw.githubusercontent.com/Cyborg7-com/cyborg7-releases/main/cyborg-cli/install.sh | sh

Restart your shell (or re-export PATH as the installer prints), then check it:

cyborg --version

2. Log in

This authenticates you against the relay and saves your credentials to ~/.cyborg/auth.json. cyborg login asks for your email and password, so it only works for an account that has a password. An account that signs in with an email code, Google or GitHub has no password the CLI can use, and the desktop app does not hand its session to the CLI. If you don’t have a password, skip claiming and use a workspace setup code instead (see Join with a setup code).

cyborg login --email you@example.com
cyborg whoami          # confirm which account you are on

3. Claim the daemon

This step connects the machine to your workspace. It binds the daemon to your account and points it at the Cyborg7 relay:

cyborg daemon claim

It writes two files into the daemon home (~/.cyborg7 by default):

File	What it does
daemon-owner	Binds this daemon to your user id
cyborg-relay-url	Points the daemon at the Cyborg7 relay

4. Start (or restart) the daemon

The daemon resolves its relay once, at boot. If it was already running before you claimed it, restart it, or it keeps running unclaimed:

cyborg daemon start --foreground   # first start
# or, if it was already running:
cyborg daemon restart

5. Verify

cyborg daemon doctor

The output should show Status: online, Claimed: yes, and a Relay pointing at the Cyborg7 relay. The machine then appears under Settings → Machines in your workspace, and you can start agents on it.

Keep it running across reboots

cyborg daemon start --foreground is the form to run under a process supervisor. A minimal systemd user unit:

[Unit]
Description=Cyborg7 daemon
After=network-online.target

[Service]
ExecStart=%h/.local/bin/cyborg daemon start --foreground --replace
Restart=on-failure

[Install]
WantedBy=default.target

--replace lets a freshly-updated daemon take over from an already-running one instead of no-opping.

cyborg daemon pair

cyborg daemon pair is retired in the cyborg command. It prints a pointer to cyborg daemon claim and exits with status 1. To attach a headless box use cyborg daemon claim, or cyborg daemon join --code if you have a setup code.

Troubleshooting

Symptom	Cause	Fix
Machine runs but never appears in the workspace	It was started before it was claimed, so it booted with no relay	cyborg daemon claim then cyborg daemon restart
cyborg daemon pair prints is not used in Cyborg7 and exits 1	The command is retired	Run cyborg daemon claim instead
Machine stays local after a --no-relay start	daemon.relay.enabled is false in ~/.cyborg7/config.json (the --no-relay start persisted it)	Run cyborg daemon claim (it sets it back to true), then cyborg daemon restart
doctor shows an unexpected relay host	The daemon resolves its relay from CYBORG_RELAY_URL → cyborg-relay-url → config.relayEndpoint	Check cat ~/.cyborg7/cyborg-relay-url; re-run cyborg daemon claim to rewrite it
claim seems to do nothing	The relay is resolved only at boot; claiming does not affect a running daemon	cyborg daemon restart after claiming
Using default home ~/.cyborg7 but found a legacy ~/.paseo	A previous Paseo install on the same machine	Harmless. Only set PASEO_HOME if you deliberately want the old location, and then use the same home for claim and start

Next steps

• Connect a workspace machine: the setup-code route, from the app
• Connecting Agents: how agents run on your machine
• Command Line (CLI): the full command surface