SSH relay and tunnels

How the relay works

Both participants, your laptop running nyx-operator (or a host agent) and the target machine, already maintain outbound WebSocket connections to the control server. The relay uses them:

ssh -p 2222 127.0.0.1        nx.3fe.ru              machine B
┌────────────────┐  WS (out) ┌──────────┐  WS (out) ┌────────────┐
│ nyx-operator   │──────────>│  relay   │<──────────│ agent → :22│
│ listens :2222  │  binary   │ registry │  binary   │ (loopback) │
└────────────────┘           └──────────┘           └────────────┘

1. The initiator asks the control plane to open a stream to a port on machine B.
2. The control plane checks that both sides belong to the same organization, B is online, and Relay is enabled. Each opening is audited.
3. The agent on B connects only to 127.0.0.1:port. The relay cannot be used to scan B’s network.
4. The server then switches binary frames between the two connections without interpreting them.

What the control plane sees: SSH is encrypted between your client and the machine’s sshd, so the control server carries only ciphertext. It knows who opened a stream, when, and to which machine and port, but not the session contents. Authentication is also end to end, using your regular SSH keys and passwords. The control plane does not issue or store private keys.

Target machine requirements

• Relay enabled in Admin → Agents, or an enrollment token with With relay selected. Relay is disabled by default.
• sshd running on 127.0.0.1:22, or another service on the required port. On Windows, the installer can install OpenSSH Server; no inbound firewall port needs to be opened.

You need your own SSH keys or password for the machine; the relay does not replace them. If your key is not installed yet, an administrator can send your public key through the agent without logging into the machine. The control plane forwards one authorized_keys line, and the agent writes it where local sshd reads it: the specified user’s ~/.ssh/authorized_keys on Linux, or administrators_authorized_keys with the required permissions on Windows. Installing the same key again changes nothing. The machine must be online. The action is audited, recording only the key type and comment.

Caution

Only the public key passes through the agent. The private key never leaves your machine, and the control plane never asks for it.

A tunnel from your laptop: nyx-operator

If nyx-operator is not installed, install it with one command; see Operator workstation.

1. In Settings → API tokens, click Create token, give it a name such as laptop, and copy its value. It is shown only once.
2. Save it in the CLI:

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

Configuration is written to ~/.config/nythronix/operator.json. The NYX_SERVER and NYX_TOKEN environment variables take precedence.

3. Find the machine. The list matches the dashboard: name, hostname, status, OS, version, relay, and tags.

nyx-operator agents                           # entire fleet
nyx-operator agents --online --tag env:prod   # filtered selection

4. Open a tunnel and connect. Identify the machine by name, hostname, login, or ID; a unique substring is enough. If several records match and exactly one is online, it is selected.

nyx-operator tunnel web-01 --port 22 --listen 127.0.0.1:2222

ssh -p 2222 user@127.0.0.1
scp -P 2222 ./backup.tgz user@127.0.0.1:/tmp/
rsync -e 'ssh -p 2222' -av ./dist/ user@127.0.0.1:/srv/app/

--port is the machine’s loopback port (default 22); --listen is the local address (default 127.0.0.1:2222). Each accepted connection becomes a separate relay stream. Ctrl-C closes everything. Any TCP port works: --port 3389 for RDP or --port 5432 for Postgres. Tunnels and Admin → Agents provide Copy nyx-operator command with the selected machine filled in.

Claude Code can open the same tunnels through MCP for operators.

Revoke the API token in the same settings page to immediately disable CLI access with it.

A tunnel on an agent: the Tunnels page

To connect one managed machine to another, for example for rsync between servers behind different NATs, open Tunnels in the dashboard:

• Host agent (A): the machine that opens the local port.
• Target agent (B): the machine whose loopback port it leads to.
• Remote port and Listen address.

After Open tunnel, the table shows the Local address on A and the Connections count. Tunnels are ephemeral: they live in agent A’s memory and disappear on restart. Stop closes the tunnel and all its connections.

The same operation from machine A’s command line (root is needed to read /etc/nythronix/agent.json):

sudo nythronix-agent tunnel <agent-id-B> --port 22 --listen 127.0.0.1:2222

SSH in the browser

In New session, SSH to another agent runs ssh on the host agent through the same relay, showing it as a normal dashboard terminal. See Terminal and sessions.

A direct browser SSH terminal without a host agent is not available yet.

Port console and web proxy

Port console opens a raw TCP stream to a machine’s port in the dashboard terminal. Use it for text protocols and debugging ports; use SSH for a shell.

Open as web page opens a new tab at:

https://app.nx.3fe.ru/proxy/<agent-id>/<port>/

The control plane proxies HTTP requests to the service on the machine’s loopback interface, such as a router admin page, Grafana, or an internal dashboard. Access checks match the relay: you need a dashboard session and a machine in your organization.

Current proxy limits: each request uses a separate relay stream; responses are limited to 16 MiB and 30 seconds; WebSocket is not proxied. Relative HTML links are rewritten, absolute links are not. For complex web apps, a nyx-operator tunnel and ordinary http://127.0.0.1:<local-port>/ are more reliable.