Install the Nexos Agent

The Nexos agent is a single static Go binary. Drop it on any Linux or macOS machine, point it at a join token, and the box becomes part of your Nexos compute network.

One-line install

The fastest path: pipe the installer to sh. It detects your OS / architecture, downloads the matching binary from this site, verifies its SHA-256 against the published manifest, and installs it as /usr/local/bin/nexos-agent.

curl -fsSL https://nexos.rs/install.sh | sh

Then check it's on your $PATH:

nexos-agent version

Installer options

Pass flags after -- when piping. Or download the script first if you'd rather audit it before running.

# Pin to a specific version
curl -fsSL https://nexos.rs/install.sh | sh -s -- --version 0.1.0

# Install somewhere other than /usr/local/bin
curl -fsSL https://nexos.rs/install.sh | NEXOS_INSTALL_DIR=$HOME/.local/bin sh

# Audit first
curl -fsSL https://nexos.rs/install.sh -o install.sh
less install.sh
sh install.sh --version 0.1.0

Manual download

If you'd rather not pipe to a shell, grab the binary directly. All four supported platforms are served from https://nexos.rs/downloads/agent/<version>/.

The version + per-asset checksums are published at /downloads/agent/latest.json. Every release directory also ships a plaintext checksums.txt for sha256sum -c.

# Example for Linux amd64
VERSION=$(curl -fsSL https://nexos.rs/downloads/agent/latest.json | \
  sed -n 's/.*"version"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -n1)

curl -fsSL "https://nexos.rs/downloads/agent/$VERSION/nexos-agent_${VERSION}_linux_amd64" \
  -o nexos-agent
curl -fsSL "https://nexos.rs/downloads/agent/$VERSION/checksums.txt" -o checksums.txt
sha256sum -c checksums.txt --ignore-missing
chmod +x nexos-agent
sudo mv nexos-agent /usr/local/bin/

Join the network

With the binary on $PATH, grab a join token from the dashboard (Nodes → Add Node) and run:

# Run from a fresh directory — each agent persists its
# config and cache in the working directory.
mkdir -p ~/nexos-node && cd ~/nexos-node

nexos-agent join --token <NODE_ID>:<SECRET>
nexos-agent start

Self-hosted control plane? The dashboard's copy-paste command already includes the --api and --grpc flags pointing at your endpoints.

Run as a systemd service

Production nodes should run the agent under a supervisor so it restarts on failure and survives reboots. Minimal unit file:

# /etc/systemd/system/nexos-agent.service
[Unit]
Description=Nexos node agent
After=network-online.target containerd.service
Wants=network-online.target

[Service]
Type=simple
User=nexos
Group=nexos
WorkingDirectory=/var/lib/nexos
ExecStart=/usr/local/bin/nexos-agent start --config /var/lib/nexos/nexos-agent.yaml
Restart=on-failure
RestartSec=5s

[Install]
WantedBy=multi-user.target

sudo useradd --system --home /var/lib/nexos --create-home nexos
sudo -u nexos nexos-agent join --token <NODE_ID>:<SECRET> \
  --config /var/lib/nexos/nexos-agent.yaml \
  --data-dir /var/lib/nexos/data
sudo systemctl daemon-reload
sudo systemctl enable --now nexos-agent
sudo journalctl -u nexos-agent -f

Upgrading

You usually don't have to. Auto-update is on by default: a running agent periodically checks latest.json, and when a newer release is published it downloads the matching binary, verifies its SHA-256, swaps it over its own executable, and re-execs onto the new version — keeping the same PID, so systemd keeps tracking it. Your config and data directory are untouched. The agent's user just needs write access to the install directory (the same place install.sh wrote it).

Want it now instead of waiting for the next poll? Run nexos-agent update. To pin a node to its installed binary, set update.enabled: false in the config (or start with --no-update) and upgrade manually by re-running the installer:

# Manual upgrade (only needed when auto-update is disabled)
curl -fsSL https://nexos.rs/install.sh | sh
sudo systemctl restart nexos-agent

Agents built from source (version …-dev) never auto-update, so a hand-compiled binary is never replaced.

Build from source

Prefer to build it yourself? Clone the repo and use Go 1.24+.

git clone https://github.com/bjelicaluka/nexos
cd nexos/agent
go build -trimpath -o nexos-agent ./cmd/agent

See Nodes & Providers for what to do next — capacity reporting, drain mode, dashboards, and how the scheduler picks your box.