Access by consent code

Why it exists

A normal, managed machine belongs to an organization whose operators have permanent access. But an agent may be installed on someone else’s machine: a client’s computer, a colleague’s workstation, or a home PC, where permanent access should not exist. Use the Code only access mode and nythronix-agent share for these cases.

The model resembles TeamViewer or AnyDesk: the owner generates a single-use code when needed, gives it to an operator, and the operator enters it in the dashboard to receive exactly the access the owner allowed. Without a code, access is denied even to operators in the agent’s own organization.

An operator from any organization can redeem the code. This is intentional: you can help clients whose machines are not in your dashboard.

Machine access mode

In Admin → Agents, the Access column has two values:

Managed: the default; organization operators can connect at any time.
Code only: the control plane rejects attempts to open or join a session without a valid code bound to that session and that operator. Sessions on these machines can only be created by redeeming a code.

An administrator selects the mode during enrollment or later in the same table.

On the owner’s side

The owner is someone who can run commands on the machine. On Linux, the command reads agent credentials from /etc/nythronix/agent.json and must run as root; on Windows, use an administrator command prompt:

sudo nythronix-agent share

Access code:  4f2a-9c11-be07
  new shell · read-write · expires in 3600s · single-use
  Give this code to the operator; they enter it in the dashboard.
  (grant 6b0e…)

Running the command is the act of consent; there are no additional confirmation windows on the machine. Flags:

Flag	Effect
No flags	A new shell; the operator can type
`--session <id>`	Access an existing session instead of a new one
`--view-only`	The operator can only watch; input is ignored
`--ttl <seconds>`	Code lifetime (default: 3600, one hour)

Each code is single-use. The agent sends only its SHA-256 hash to the control plane: the server does not know the code and cannot use it.

On the operator’s side

The dashboard has an Access code field and a Connect button. Enter the code exactly as the owner received it. The control plane:

Finds a valid code by its hash: unexpired, unrevoked, and unused.
Checks that the machine is online. Otherwise, it returns a machine-offline error and leaves the code unused.
Starts a new shell or attaches you to the specified session.
Opens the terminal at /session/<id>.

Terminal permissions come from the code: --view-only allows viewing only, regardless of your dashboard role.

Expiration and revocation

Access ends when any of these conditions occurs:

--ttl expires.
The code has already been used (all codes are single-use).
The agent disconnects or restarts, invalidating all codes and access grants it issued.
The session stops, either via Stop in the dashboard or by exiting the shell.

There is no dedicated agent-side revoke command yet. The most reliable way to end access immediately is to restart the agent service (systemctl restart nythronix-agent) or stop it with nythronix-agent service stop on Windows. The planned --watch (mirror the session in the owner’s terminal) and --ssh (a code for an SSH tunnel) options are not available yet.

What the owner sees

A consent-code session is a normal shell process on the machine running as the agent user or assigned login. The owner can see it in ps, or for tmux/zellij, in the multiplexer session list as nyx-<id>. Stream opening and code issuance are recorded in the control plane’s audit log. The current version does not provide a live mirror on the owner’s screen.

Recommendations

Do not post codes in public chats. Shorten the default one-hour lifetime with --ttl 600.
Use --view-only for consultations that require no changes.
Set client machines to Code only during enrollment and, when needed, restrict sudo through local policy. See Linux installation.