Linux installation

Requirements

Linux x86_64 or aarch64 with systemd.
Root access for installation. The agent service also runs as root; the reason is explained below.
Outbound HTTPS/WSS access to nx.3fe.ru. No inbound ports are needed.
An enrollment token nyxet_… from the dashboard (Admin → Agents → Enrollment tokens).
The nythronix-agent binary. The dashboard does not yet link to a Linux build; get it from the Nythronix team along with beta access.

For tmux and zellij sessions, install the corresponding program on the machine. The agent reports its availability to the control plane automatically.

Command from the dashboard

After creating a token, the dashboard provides a ready-to-run command. Run it as root after placing the binary in PATH:

sudo install -m 0755 ./nythronix-agent /usr/local/bin/
sudo nythronix-agent enroll --token nyxet_… --url wss://nx.3fe.ru/agent/ws

enroll exchanges the token for permanent credentials and writes them, along with the update verification key, to /etc/nythronix/agent.json with permissions 0600. Output looks like:

enrolled as agent-… (agent 3f1c…); 1 trusted key(s); config saved to /etc/nythronix/agent.json

Use --hostname NAME to set the name displayed in the dashboard; the system hostname is used by default.

The systemd service

Create a unit:

[Unit]
Description=Nythronix agent
After=network-online.target
Wants=network-online.target

[Service]
ExecStart=/usr/local/bin/nythronix-agent
Restart=on-failure
RestartSec=5s

[Install]
WantedBy=multi-user.target

Then enable it:

sudo systemctl daemon-reload
sudo systemctl enable --now nythronix-agent

Without a subcommand, nythronix-agent starts the daemon and reads credentials from /etc/nythronix/agent.json. Do not add DynamicUser, NoNewPrivileges, or ProtectSystem=strict to the unit: they prevent the user switching and sudoers writes described below.

Unprivileged user

The daemon runs as root but does not run worker commands as root. Create a system user:

sudo useradd --system --home-dir /var/lib/nyx-worker --create-home \
  --shell /usr/sbin/nologin nyx-worker

If the user exists, the agent switches to it with runuser for each AI worker command and reports this to the control plane. The machine shows an as nyx-worker badge in Admin → Agents. The daemon needs root for exactly three tasks: switching users, writing the sudoers file, and replacing its own binary during updates.

Operator terminals default to the user running the agent. An administrator can assign another local login to an operator (Admin → Operators → Terminal → user); their sessions then start as that user’s login shell.

On-demand sudo

By default, nyx-worker has no sudo access. When a worker needs root, an administrator opens Admin → Agents → Worker root, clicks Grant root, and selects a duration: 15 minutes, 1, 4, or 8 hours. The agent validates the policy with visudo -cf and writes /etc/sudoers.d/nyx-worker. It removes the file when the grant expires, even if the control plane connection is lost. Revoke removes access early. The list option restricts sudo to a list of commands.

The machine owner can impose local limits in /etc/nythronix/agent-policy.json, which the control plane cannot see or modify:

{
  "allow_remote_sudo": false,
  "max_sudo_policy": "list",
  "terminal_login_lock": "deploy"
}

allow_remote_sudo: false: reject all sudo grants.
max_sudo_policy: a ceiling of none < list < all.
terminal_login_lock: always open terminals as this user.

The enroll-agent.sh script writes this file using --no-remote-sudo, --max-sudo none|list|all, and --terminal-lock LOGIN.

Checking the connection

systemctl status nythronix-agent
journalctl -u nythronix-agent -f

The log should show a successful connection, and the dashboard should display the machine as Online. If the connection drops, the agent reconnects automatically with a delay that grows from 1 to 30 seconds.

Common causes of failure: an expired or already-used token (create a new one), a typo in --url, or no outbound access to nx.3fe.ru.

Updating

In Admin → Agents, set the machine’s Update policy: auto applies releases immediately, auto_idle_only waits until there are no active sessions, and manual (the default) only notifies you. The agent downloads the new binary, checks SHA-256 and the Ed25519 signature with the key received during enrollment, replaces the file, and restarts itself. tmux/zellij sessions survive and are picked up again.

Uninstalling

sudo systemctl disable --now nythronix-agent
sudo rm /etc/systemd/system/nythronix-agent.service /usr/local/bin/nythronix-agent
sudo rm -rf /etc/nythronix
sudo rm -f /etc/sudoers.d/nyx-worker

Then delete the machine record in Admin → Agents to invalidate its credentials.