Terminal
Open a root shell on a connected server from the browser, and record, replay and download terminal sessions. Owners only.
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.
- 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.
- The browser opens a WebSocket with that ticket.
- 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.
- 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
| Limit | Value |
|---|---|
| Open terminals per server | 5 |
| Open terminals per person | 10 |
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:
| Setting | Default | |
|---|---|---|
| Record terminal sessions | On | What the shell shows on screen, with timing, so it can be replayed |
| Also record what is typed | Off | Every key sent to the server |
| Keep recordings for (days) | 90 | 1 to 3650. Older sessions and their recordings are deleted. |
| Largest recording (MB) | 50 | 1 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
| Action | When |
|---|---|
server.terminal.open | A terminal opens, with whether it is recorded |
server.terminal.close | A terminal closes, with its duration and amount of output |
terminal.recording.settings | Recording settings change |
terminal.recording.delete | A recording is deleted |