Connect your first agent

With ordo-agent installed on the machine you want to manage (see Install), create an agent.yaml. The defaults are sensible — the file is mostly a place to opt into the remote terminal later:

/etc/ordo/agent.yaml

# Ordo agent configuration — example.
#
# Every option is shown with its default value, all commented out: the defaults
# are sensible, so an agent runs with no configuration at all. Uncomment only
# what you want to change. The agent hot-reloads this file when started with
# `--config`, so changes apply without a restart.
#
# The orchestrator address is NOT set here — it is passed to the `connect`
# subcommand (e.g. `ordo-agent connect 192.168.40.243:4747`).
#
# Schema (editor autocompletion / CI validation):
#   https://getordo.dev/schemas/agent-config/v1.json

# ── Remote terminal (defaults shown) ────────────────────────────────────────
# Lets operators open interactive PTY sessions on this machine through the
# orchestrator. Disabled by default.
# remote_terminal:
#   enabled: false
#   shell: ""                          # empty = platform default (/bin/bash, powershell.exe)
#   allow_operator_shell_override: false   # let the operator choose the shell per session
#   max_sessions: 100                  # max concurrent terminal sessions

# ── Metrics (defaults shown) ────────────────────────────────────────────────
# System health reporting (disk, memory, CPU) to the orchestrator.
# metrics:
#   enabled: true
#   collection_interval: 30            # seconds between samples

Install the agent unit, replacing ORCHESTRATOR_HOST with your orchestrator’s address:

/etc/systemd/system/ordo-agent.service

[Unit]
Description=Ordo agent
Documentation=https://docs.getordo.dev
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
# Top-level options (--config, --data-dir) come BEFORE the `connect` subcommand;
# replace the address with your orchestrator's host:agent_port.
ExecStart=/usr/local/bin/ordo-agent --config /etc/ordo/agent.yaml --data-dir /var/lib/ordo-agent connect ORCHESTRATOR_HOST:4747
Restart=on-failure
RestartSec=5

# The agent manages this machine — it writes files and controls services as
# declared state requires — so it runs as root WITHOUT the filesystem sandboxing
# used for the orchestrator. ProtectSystem/ProtectHome/DynamicUser would stop it
# doing its job. StateDirectory persists the agent's identity and pinned
# orchestrator key.
User=root
StateDirectory=ordo-agent

[Install]
WantedBy=multi-user.target

Caution

The agent manages the machine — it writes files and controls services as your declared state requires — so it runs as root with no filesystem sandbox.

sudo systemctl daemon-reload
sudo systemctl enable --now ordo-agent
journalctl -u ordo-agent -f

On first connection the agent pins the orchestrator’s key and enters the Pending state on the orchestrator, awaiting your approval.

Approve and tag the agent

Back on your workstation, list agents, approve the pending one, and tag it so state can target it later:

ordo agents
ordo agents approve <node-id> --name client-01
ordo agents tag client-01 group=home

Tip

You can also approve and tag the agent from the web UI once it is open, below.

Open the web UI

Create a connection profile pointing at the orchestrator. The first profile you create automatically becomes the default, so the CLI uses it with no further configuration:

ordo profile create home --host <orchestrator-host>

Then mint a web UI session and open the printed URL:

ordo web-login

It prints a login token and a https://<orchestrator-host>:4748/ui/auth/callback?token=… URL — open it in a browser to reach the UI authenticated as your operator.