Servers

Terminal

Open a root shell on a connected server from the browser, and record, replay and download terminal sessions. Owners only.

Last updated

The terminal gives owners a root shell on a server from the panel, like an SSH session, without opening SSH to their computer. Opening and closing a terminal is always written to the audit log, and sessions can be recorded for replay.

Who can open it

Opening a terminal needs servers.terminal, which only the Owner role has. It is never granted to admins, to an API token scope, to a plugin or to the AI assistant: a root shell goes beyond anything the allow-listed operations can do, so it is only for a person signed in to the panel in a browser.

The server's agent must be 0.11.0 or newer and allow it (allowTerminal, on by default). When panel access by address is on, the terminal is refused from addresses that are not on the list.

Open a terminal

Use Infrastructure > Terminal and pick a server, or the Terminal tab on a server's page. The shell is root's login shell, started in the server's own mount namespace, so it sees the server as an SSH session would.

  • Copy: select text, then Copy or Ctrl+Shift+C (Ctrl+C also copies while text is selected). On macOS, ⌘C.
  • Paste: Ctrl+V or right-click. Over plain HTTP, browsers only allow the keyboard shortcut or right-click paste.
  • Full screen: the toolbar button; Esc leaves it.

A badge shows whether the session is being recorded, and what is recorded.

How it works

A terminal is not an agent operation: it is a separate channel, and the operation allow-list stays unchanged.

  1. The browser asks the API for a terminal with the session cookie and CSRF token, and gets a one-time ticket valid for 30 seconds.
  2. The browser opens a WebSocket with that ticket.
  3. The panel asks the agent for a shell with an envelope signed by the panel's key, for this server, valid for a minute and used once, exactly like a job.
  4. The panel passes bytes between the browser and the agent's shell.

Each agent keeps one signed WebSocket open to the panel for this, and reconnects by itself.

A session ends when the browser closes, the person signs out or loses the owner role, or the agent restarts. Running systemctl restart vaultpanel-agent inside a terminal therefore ends that terminal.

Limits

LimitValue
Open terminals per server5
Open terminals per person10

Past either limit the panel answers TOO_MANY_TERMINALS; close a terminal first.

Recordings

The panel records sessions as the bytes pass through it, as asciicast v2 files in its data folder, readable only by the panel's own user. Infrastructure > Terminal > Sessions and recordings lists every terminal opened from the panel, newest first. Open one to replay it in the panel, or click Download to play it with asciinema.

The Recording settings on the same page:

SettingDefault
Record terminal sessionsOnWhat the shell shows on screen, with timing, so it can be replayed
Also record what is typedOffEvery key sent to the server
Keep recordings for (days)901 to 3650. Older sessions and their recordings are deleted.
Largest recording (MB)501 to 1024. A session that prints more keeps running; its recording stops there.

Only owners can watch, download and delete recordings, since they can hold secrets shown on screen. Deleting a recording removes the session and its file for good, and is written to the audit log.

Audit log

ActionWhen
server.terminal.openA terminal opens, with whether it is recorded
server.terminal.closeA terminal closes, with its duration and amount of output
terminal.recording.settingsRecording settings change
terminal.recording.deleteA recording is deleted