Connecting to a Host

Connect Button (Host List)

The fastest way to open a terminal is directly from the hosts list or card view:

1. Find the host in the Hosts list or card view
2. Click the Connect button that appears inline after the hostname
3. A dropdown appears showing your allowed logins for that host (fetched from CheckAccess)
4. Select a login — the UI navigates to the host's Terminal tab and auto-connects immediately

Login names in the dropdown are already resolved from your role's templates. For example, a role template {{.email_prefix}} appears as your actual email prefix (e.g., j.yerzakov), not the raw template string.

From the Host Detail Page

1. Navigate to a host's detail page
2. Click the Terminal tab in the sidebar (under Operations)
3. Select a Linux user from the dropdown (filtered by your role's allowed logins)
4. Click Connect
5. An interactive shell appears in the terminal panel

SSO Trait Templates

When SSO trait templates are configured in a role's terminal spec, the login dropdown shows the resolved usernames derived from the user's OIDC identity — not the raw template strings. For example, a template {{.email_prefix}} resolves to the user's actual email prefix (e.g., j.yerzakov).

Session Behavior

• Resize — the terminal auto-resizes when you resize the browser window
• Idle timeout — sessions disconnect after inactivity (configurable per role, default 30m)
• Session TTL — maximum session duration enforced regardless of activity (configurable per role, default 8h)
• Concurrent sessions — each user can have up to N sessions open simultaneously (configurable, default 10)
• Keepalive — WebSocket pings every 30s keep the connection alive even when the browser tab is unfocused
• Session linger — when disconnected, the PTY stays alive for a configurable grace period (disconnect_timeout, default 30s). If you reconnect within this window, your shell state is preserved
• Auto-reconnect — if the connection drops unexpectedly (network blip, tab backgrounded), the terminal auto-reconnects within seconds. Up to 3 retries with exponential backoff
• Session recording — when enabled (default), PTY output is recorded in asciicast v2 format and uploaded to object storage. After the session ends, a Play button appears in the sessions list to replay the recording with speed controls and timeline scrubbing. Users can view their own recordings; admins can view all.

File Transfer

Upload and download files during an active terminal session.

Upload

Click Upload in the terminal header bar. Select a file (max 100MB), specify the destination path (default ~/), and click Upload. The file transfers in 512KB chunks over NATS — you can keep using the terminal during the transfer.

Download

Click Download in the terminal header bar. Enter the remote file path and click Download. The file streams to your browser and downloads automatically.

Limitations

• Single files only (no directories)
• 100MB maximum file size
• One transfer at a time per session
• Files are accessed as the session's Linux user — OS permissions apply

Disconnecting

Intentional disconnect

• Click Disconnect in the terminal panel, close the terminal tab, or navigate away
• The backend sends a stop command to the agent, which kills the PTY process immediately
• Session end reason and duration are recorded in the audit log

Unexpected disconnect (network drop)

• If the WebSocket connection drops due to a network issue, the frontend automatically retries up to 3 times with exponential backoff
• The PTY process on the agent stays alive for the disconnect_timeout grace period (default 30s)
• If the connection is restored within that window, the session resumes and your shell state is preserved
• If the grace period expires before reconnect, the agent kills the PTY and the session is recorded as ended

K8s Node Connections

Terminal sessions on Kubernetes nodes work the same as bare metal — select a node from the hosts list and click Connect. The agent automatically detects K8s mode and uses nsenter to enter the host's full namespace (PID, mount, UTS, IPC, network). You get a shell on the actual node, not inside the agent pod.

Requirements: The DaemonSet must have hostPID: true and SYS_PTRACE + SYS_ADMIN capabilities. See Node Agent K8s Deployment.

K8s Node Limitations

Minimal Kubernetes distributions (RKE2/SLE Micro, k3s, Talos, Flatcar) ship without standard user management binaries (useradd, groupadd, passwd, getent). On these nodes:

• Host user creation is automatically disabled — the agent detects missing binaries at startup and skips user management
• Connect as existing users only — typically root. Add root to your role's allow logins
• User lookup falls back to /etc/passwd — when getent is unavailable, the agent reads /etc/passwd directly (LDAP/SSSD users won't be resolved)
• Sudoers management is unavailable — visudo doesn't exist on minimal nodes

For full host user creation support on K8s nodes, install the Proxima agent directly on the host (alongside the DaemonSet agent for metrics).

Multi-Party Sessions

Observing a Live Session

Go to Admin → Terminal Sessions. Active sessions show an eye icon — click to observe. You see everything the session owner types in real-time, but cannot type yourself. Requires terminal_sessions:read permission.

Participating in a Live Session

Active sessions also show a terminal icon for users with terminal_sessions:write permission. Click to join as a participant — you can type into the shared terminal alongside the owner (like tmux attach).

Peer Visibility

The session owner sees a peer count indicator in their terminal header showing how many observers and participants are connected.

Limits

• Maximum 10 observers/participants per session
• Peers are disconnected when the session ends
• Session recordings capture all input from all participants
• No per-participant input distinction — everyone types to the same PTY

Troubleshooting

Issue	Cause	Solution
"Terminal access not available"	Your role has no terminal_spec or doesn't match the host's labels	Ask an admin to update your role's terminal configuration
"User 'X' does not exist on this host"	The Linux user doesn't exist on the target host	Choose a different login or create the user on the host
"User does not exist on this host"	Linux user not found and create_host_user_mode is off	Enable create_host_user_mode: keep or drop in the role's terminal spec
"Agent did not respond"	Agent is offline or not running; for K8s DaemonSet agents, check that hostPID: true and SYS_PTRACE/SYS_ADMIN capabilities are set	Check host status and agent logs; verify the DaemonSet security context if running on Kubernetes
"Host has no linked agent"	The host record exists in inventory but no agent has enrolled for it	Enroll an agent on the target host
"Invalid login"	The login name contains invalid characters (must match [a-z_][a-z0-9_.-]*)	Correct the login name in your role's terminal spec or template
"PTY allocation failed: unknown user"	create_host_user_mode is off and the Linux user does not exist	Set create_host_user_mode: keep or drop, or pre-create the user on the host
"Session token verification failed"	Backend/agent version mismatch (one upgraded without the other), or the token's agent_id does not match the receiving agent	Ensure backend and agent are both on v1.3+; check that the agent enrolled under the correct host ID
"Maximum concurrent sessions exceeded"	You have too many sessions open	Close existing sessions first