Install the BTS Agent

The BTS 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 BTS 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://test.buildingswell.com/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://test.buildingswell.com/install.sh | sh -s -- --version 0.1.0

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

# Audit first
curl -fsSL https://test.buildingswell.com/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://test.buildingswell.com/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://test.buildingswell.com/downloads/agent/latest.json | \
  sed -n 's/.*"version"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -n1)

curl -fsSL "https://test.buildingswell.com/downloads/agent/$VERSION/nexos-agent_${VERSION}_linux_amd64" \
  -o nexos-agent
curl -fsSL "https://test.buildingswell.com/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 start within 24 hours of generating the command: a join command that is still unused by then is refused, and the agent logs join token expired. Delete that node in the dashboard, add a new one, run its join command (it overwrites the configuration) and restart the agent, which otherwise keeps the identity it started with. Once the agent has connected, the token is the node's credential and does not expire.

Run as a systemd service

An agent started by hand stops when you log out or the machine reboots. Production nodes should run it as a systemd service instead. Stop the agent you started above first, so only one copy connects as this node. Then run this from the folder you joined in:

cd ~/nexos-node   # the folder that holds nexos-agent.yaml

sudo tee /etc/systemd/system/nexos-agent.service >/dev/null <<EOF
[Unit]
Description=BTS node agent
After=network-online.target docker.service containerd.service
Wants=network-online.target

[Service]
Type=simple
User=root
WorkingDirectory=$PWD
ExecStart=$(command -v nexos-agent) start --config $PWD/nexos-agent.yaml
Restart=always
RestartSec=5s

[Install]
WantedBy=multi-user.target
EOF

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

Your shell fills in the folder and the binary path as it writes the file, so the service picks up the config you already have.

• It runs as root. Auto-update replaces the binary in /usr/local/bin, and builds run docker and systemd-run (for per-build CPU and memory limits). A non-root user can do none of that without extra setup.
• WorkingDirectory must be the folder you joined in. The config stores data_dir relative to it. Started from anywhere else, the agent loses its build cache and git mirrors.
• Restart=always brings the agent back after any exit, not just a crash, and enable starts it at boot.

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 root service above can always replace the binary. If you run the agent as another user, that user 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://test.buildingswell.com/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/BuildingSwell/bswl-test
cd bswl-test/agent
go build -trimpath -o nexos-agent ./cmd/agent

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