Native install (no Docker)

If you'd rather run nexo-rs directly on a Linux / macOS host — development loop, single-machine deploy, restricted container environment — this page walks through every step and names the bootstrap script that automates it.

Fast path

git clone git@github.com:lordmacu/nexo-rs.git
cd nexo-rs
./scripts/bootstrap.sh

scripts/bootstrap.sh verifies prerequisites, installs a local NATS, creates the runtime directories, stages example configs, and builds the agent binary. Re-runnable — each step is idempotent.

Keep reading for what it actually does (and what to do when a step needs manual intervention).

Prerequisites

On Ubuntu / Debian:

sudo apt update
sudo apt install -y build-essential pkg-config libsqlite3-dev git curl

On macOS:

xcode-select --install
brew install sqlite git

Install Rust

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"
rustup component add rustfmt clippy

The repo's rust-toolchain.toml pins the channel; no manual version pick is needed.

Install NATS

Pick one path:

Option A — native NATS server

# Linux x86_64
curl -L -o /tmp/nats.tar.gz \
  https://github.com/nats-io/nats-server/releases/download/v2.10.20/nats-server-v2.10.20-linux-amd64.tar.gz
tar -xzf /tmp/nats.tar.gz -C /tmp
sudo mv /tmp/nats-server-*/nats-server /usr/local/bin/

For macOS: brew install nats-server.

Start it:

nats-server -js                      # foreground
nats-server -js -D                   # foreground with debug
# or, as a systemd service: see below

Option B — dev throwaway via Docker

Even on a "no-Docker" box, a single short-lived container for the broker is often fine:

docker run -d --name nexo-nats --restart unless-stopped \
  -p 4222:4222 -p 8222:8222 nats:2.10-alpine

This is the same broker the compose stack would use; only the broker itself runs in a container.

Systemd unit (Linux, production)

/etc/systemd/system/nats-server.service:

[Unit]
Description=NATS Server
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/nats-server -js
Restart=on-failure
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now nats-server

Build nexo-rs

git clone git@github.com:lordmacu/nexo-rs.git
cd nexo-rs
cargo build --release

The output is ./target/release/agent. Symlink it into $PATH if you want:

sudo ln -sf "$(pwd)/target/release/agent" /usr/local/bin/agent

Prepare runtime directories

mkdir -p ./data/{queue,workspace,media,transcripts}
mkdir -p ./secrets          # gitignored; holds API keys, nkey files, etc.
chmod 700 ./secrets         # restrictive — the credential gauntlet checks this

Stage config

The repo ships config/*.yaml with safe defaults. Override whatever you need:

# Optional: copy the ana sales agent template into the gitignored dir
cp config/agents.d/ana.example.yaml config/agents.d/ana.yaml

# Add an API key:
export MINIMAX_API_KEY=...
export MINIMAX_GROUP_ID=...
# or write to secrets/ files referenced from config/llm.yaml via ${file:...}

See Configuration — layout for the full reference.

Pair channels and set secrets

./target/release/agent setup

The wizard pairs WhatsApp / Telegram / Google / LLM credentials interactively. See Setup wizard.

First run

./target/release/agent --config ./config

Watch the startup summary — it tells you exactly which plugins loaded, which extensions were skipped and why, and whether the broker is reachable. If anything's missing, the log line names the specific file or env var to fix.

Run as a systemd service

/etc/systemd/system/nexo-rs.service:

[Unit]
Description=nexo-rs agent
Requires=nats-server.service
After=nats-server.service

[Service]
Type=simple
User=nexo
Group=nexo
WorkingDirectory=/srv/nexo-rs
Environment=RUST_LOG=info
Environment=AGENT_ENV=production
ExecStart=/usr/local/bin/agent --config /srv/nexo-rs/config
Restart=on-failure
RestartSec=5
# Optional: restrict where the agent can write
ReadWritePaths=/srv/nexo-rs/data /srv/nexo-rs/secrets

[Install]
WantedBy=multi-user.target

sudo useradd -r -s /bin/false -d /srv/nexo-rs nexo
sudo chown -R nexo:nexo /srv/nexo-rs
sudo systemctl daemon-reload
sudo systemctl enable --now nexo-rs

Logs:

journalctl -u nexo-rs -f

macOS launchd

~/Library/LaunchAgents/dev.nexo-rs.agent.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>          <string>dev.nexo-rs.agent</string>
  <key>WorkingDirectory</key><string>/Users/you/nexo-rs</string>
  <key>ProgramArguments</key>
  <array>
    <string>/Users/you/nexo-rs/target/release/agent</string>
    <string>--config</string><string>/Users/you/nexo-rs/config</string>
  </array>
  <key>EnvironmentVariables</key>
  <dict>
    <key>RUST_LOG</key><string>info</string>
  </dict>
  <key>RunAtLoad</key>      <true/>
  <key>KeepAlive</key>      <true/>
</dict>
</plist>

launchctl load -w ~/Library/LaunchAgents/dev.nexo-rs.agent.plist
launchctl start dev.nexo-rs.agent

Verify

agent status                    # lists running agents
curl localhost:8080/ready       # readiness
curl localhost:9090/metrics     # Prometheus metrics

See Metrics + health.

Upgrading

cd nexo-rs
git pull
cargo build --release
sudo systemctl restart nexo-rs      # Linux
# or: launchctl kickstart -k gui/$UID/dev.nexo-rs.agent   # macOS

The graceful shutdown sequence drains in-flight work and persists the disk queue before exit.

Uninstalling

sudo systemctl disable --now nexo-rs nats-server
sudo rm /etc/systemd/system/{nexo-rs,nats-server}.service
sudo rm /usr/local/bin/{agent,nats-server}
sudo userdel nexo
rm -rf /srv/nexo-rs

See also

• Quick start — the five-minute dev loop
• Docker — container path for comparison
• Setup wizard
• Configuration