Terminal and sessions

Opening a session

Two options:

• Launch shell on a machine card opens a terminal immediately with the shell engine, an automatic name, and the home directory.
• New session in the left menu opens a settings form. Keep Target as Remote agent (shell), choose an Agent using the same tag filters as the dashboard, and set other options if needed.

The browser renders the terminal, but the session itself is a process on the machine. Closing a tab does not end it: it stays in the left menu’s Sessions list and on the machine page, where you can rejoin with Connect. Only Stop, or exiting the shell, ends it.

Engines and recovery

The Engine field lists only programs available on the machine, as reported by the agent:

Engine	What it is	After a connection loss or agent restart
shell	A plain interactive shell ($SHELL on Linux, PowerShell on Windows)	The session is lost
tmux	A shell inside the tmux session nyx-<id>	The session survives; the agent reattaches
zellij	The same using zellij	The session survives; the agent reattaches

Only shell is available on Windows. The agent reconnects automatically after connection loss. The control plane sends the list of sessions it still expects, and any matching live nyx-* tmux/zellij sessions are recovered automatically. For long tasks that must survive an agent restart, such as an automatic update, choose tmux or zellij.

Stop also destroys the server-side multiplexer session, preventing orphaned nyx-* sessions from accumulating.

Session name

Session name is optional. If omitted, the server generates a name such as quiet-duck: an adjective and noun, like zellij, checked for uniqueness among live sessions. It appears in the terminal title, Sessions menu, and dashboard.

Working directory

Working directory accepts a path on the machine. On desktop, Tab completes the path from subfolders returned by the agent. On a phone, use Browse folders, starting at the agent user’s home directory, with Show hidden and Select this folder controls. You can navigate the entire filesystem: the operator will receive a shell anyway, so this adds no further exposure.

SSH to another agent

The same form has an SSH to another agent field. Select a target to run ordinary ssh on the host agent through the control plane’s relay, with the terminal shown in the browser. Fill in SSH user (defaults to the agent user) and SSH port. The target machine must have Relay enabled and sshd running on 127.0.0.1:22. See SSH relay and tunnels.

For older Windows machines without ConPTY, this is the only way to get a terminal. The form automatically suggests selecting a relay target.

Shared viewing

Several people can join one session simultaneously. The server buffers the latest output (1 MiB), sends it to each new viewer, and then streams live updates. Input permissions:

• operator, admin, and owner: read and write.
• viewer: view only; input and resize requests are ignored.
• Consent-code participants: as allowed by the owner (--view-only grants viewing only).

In the terminal, Live means the connection is active; Disconnected means it was lost, although the session may still be running. Fullscreen expands the terminal.

Split view

Split view in the menu shows up to four running sessions side by side in a 2×2 grid. Each pane is interactive; input goes to the focused pane. Controls: Add session…, Remove pane, and Open full terminal. The layout is not retained between visits.

Dashboard previews

Settings → Session previews offers three modes:

• Live: each running session appears as a colored mosaic on its machine card, updating as output arrives.
• Last screen: a single snapshot without live updates, lighter on slower devices and large fleets.
• Off: hide previews.

This is experimental: the mosaic conveys screen colors and structure, not readable text. Click a preview to open the full terminal.