CLI reference

nythronix-agent

The agent on a managed machine. With no subcommand, it runs as a daemon, connecting to the control server and serving sessions, relays, and worker commands. This is how systemd and the Windows service launch it.

nythronix-agent [GLOBAL FLAGS] [SUBCOMMAND]

Global flags

Flag	Environment variable	Purpose
--url <URL>	NYTHRONIX_SERVER_WS	Control server URL, such as wss://nx.3fe.ru/agent/ws; defaults to saved configuration
--login <LOGIN>	NYTHRONIX_AGENT_LOGIN	Agent login; defaults to saved configuration
--password <PASSWORD>	NYTHRONIX_AGENT_PASSWORD	Agent password; defaults to saved configuration
--hostname <NAME>	—	Name reported to the control plane; defaults to the system hostname
--config <PATH>	NYTHRONIX_AGENT_CONFIG	Configuration file path; may appear before or after the subcommand
--help, --version	—	Help and version

The default configuration path is /etc/nythronix/agent.json on Linux and %ProgramData%\Nythronix\agent.json on Windows. enroll creates it with the server URL, login, password, agent ID, and pinned update verification keys.

Linux also reads NYTHRONIX_TRUSTED_KEYS, a comma-separated list of hex Ed25519 keys, merged with the configuration keys.

enroll

Enrolls a machine with a token, exchanging it for permanent credentials and saving them in the configuration. No existing credentials are required.

nythronix-agent enroll --token nyxet_… --url wss://nx.3fe.ru/agent/ws [--hostname NAME] [--display-name NAME]

Flag	Environment variable	Purpose
--token <TOKEN>	NYTHRONIX_ENROLL_TOKEN	Enrollment token nyxet_… (required)
--url <URL>	NYTHRONIX_SERVER_WS	Server URL, accepting https://…, wss://…/agent/ws, and similar forms (required)
--hostname <NAME>	—	Hostname reported to the server; defaults to the system hostname
--display-name <NAME>	NYTHRONIX_DISPLAY_NAME	Friendly dashboard name (optional)

share

Generates a single-use access code for this machine. Running the command is the owner’s consent. See Access by consent code.

nythronix-agent share [--session <ID>] [--view-only] [--ttl <SECONDS>]

Flag	Purpose
--session <ID>	Share an existing session instead of a new shell
--view-only	Allow viewing but no typing
--ttl <SECONDS>	Code lifetime in seconds (default 3600)

tunnel

Opens a local TCP port on this machine, routed through the control plane relay to another agent’s loopback port in the same organization. The target must have Relay enabled. Uses this agent’s credentials. See SSH relay and tunnels.

nythronix-agent tunnel <TARGET_AGENT_ID> [--port <PORT>] [--listen <ADDR>]

Argument / flag	Purpose
<TARGET_AGENT_ID>	Target agent ID (required positional argument)
--port <PORT>	Target loopback port (default 22)
--listen <ADDR>	Local listening address (default 127.0.0.1:2222)

Runs until Ctrl-C.

service (Windows only)

Manages the agent as a Windows service. NythronixAgent runs as LocalSystem, starts automatically, and restarts on failure. It reads credentials saved by enroll. Requires an administrator command prompt.

nythronix-agent service install     register the service
nythronix-agent service uninstall   unregister the service
nythronix-agent service start       start the service
nythronix-agent service stop        stop the service
nythronix-agent service run         service manager entry point; do not call manually

nyx-operator

The operator CLI for your workstation. Authenticates with a dashboard API token (Settings → API tokens), lists machines, and opens relay tunnels to agents.

Install and update operator tools with one command; see Operator workstation. For Claude Code, see MCP for operators.

nyx-operator <SUBCOMMAND>

Typical workflow:

nyx-operator agents                           # all machines as a table
nyx-operator agents --online --tag env:prod   # narrow the list
nyx-operator agents checkout                  # search names, hostnames, logins, and tags
nyx-operator tunnel checkout-1 --port 22      # local port → relay → machine
ssh -p 2222 admin@127.0.0.1                   # in another terminal

Address machines by dashboard name, hostname, agent login, or ID. Matching rules are described under tunnel.

login

Checks the token with /api/me and saves the server URL and token to ~/.config/nythronix/operator.json with permissions 0600. Run once per machine.

nyx-operator login --server https://app.nx.3fe.ru --token nyxop_…

Flag	Purpose
--server <URL>	Control server URL (required)
--token <TOKEN>	Operator API token nyxop_… (required)

Create your own token in Settings → API tokens. Its value is shown once at creation. An administrator cannot issue a token for you.

The credentials file is shared by nyx-operator and the MCP server, so no second login is needed. Treat it like an SSH key.

When both NYX_SERVER and NYX_TOKEN are set, they take precedence over the file for other commands.

agents

Lists visible agents in a table with NAME, HOST, STATE, OS, VERSION, RELAY, and TAGS: dashboard name, hostname, online / offline, OS, agent version, relay status, and tags. NAME falls back to hostname if no display name is set.

nyx-operator agents [QUERY] [--online] [--os <OS>] [--tag <KEY:VALUE>]… [--ids] [--json]

Argument / flag	Purpose
[QUERY]	Substring search in name, hostname, login, and tags (optional positional argument)
--online	Only currently connected machines
--os <OS>	OS reported by the agent: linux, windows, or windows7
--tag <KEY:VALUE>	Only machines with this tag; repeat to require all tags
--ids	Add an ID column, mainly useful for scripts since commands accept names
--json	Output JSON instead of a table

Filters combine with AND and ignore case. --tag matches entire tags, like the dashboard filter; use QUERY for partial tag matches.

nyx-operator agents --online --tag client:uut --tag role:kassa
nyx-operator agents checkout --os windows7
nyx-operator agents --json

A summary such as 3 shown (2 online) of 12 total goes to stderr, keeping piped table output clean. If no machine matches, the command says so and shows the total machine count.

Each JSON row includes id, name, hostname, login, online, os, version, tags, and relay_enabled.

tunnel

Opens a local TCP port through the relay to a machine’s loopback port. Any TCP port works, including 22 for SSH, 3389 for RDP, and 5432 for PostgreSQL. See SSH relay and tunnels.

nyx-operator tunnel <AGENT> [--port <PORT>] [--listen <ADDR>]

Argument / flag	Purpose
<AGENT>	Dashboard name, hostname, agent login, or ID (required positional argument)
--port <PORT>	Machine loopback port (default 22)
--listen <ADDR>	Local listening address (default 127.0.0.1:2222); port 0, such as 127.0.0.1:0, lets the OS select a free port

nyx-operator tunnel uut_kassa_1 --port 22 --listen 127.0.0.1:2222
ssh -p 2222 <user>@127.0.0.1    # in another terminal

Machine selection:

1. Try an exact, case-insensitive match against name, hostname, login, or ID.
2. Otherwise, match a substring of name, hostname, or login, or an ID prefix. A unique substring is enough.
3. If several records match and exactly one is online, select it. This prevents stale records from reenrollment from obscuring the active machine.
4. If the match remains ambiguous, fail and list candidates so you can refine the name. If nothing matches, inspect nyx-operator agents.

Before opening the port, the command prints its selected target to stderr, for example target: uut_kassa_1 (KASSA1, online). It then prints tunnel: 127.0.0.1:2222 -> agent … :22 (Ctrl-C to stop) and runs until Ctrl-C.

Codes and prefixes

Prefix	Meaning
nyxet_…	Agent enrollment token (Admin → Agents → Enrollment tokens)
nyxop_…	Operator API token for nyx-operator (Settings → API tokens)
xxxx-xxxx-xxxx	Consent code from nythronix-agent share (12 hexadecimal characters)