# Terminal

URL: https://docs.vaultpanel.net/guides/servers/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](https://docs.vaultpanel.net/guides/security/panel-access) 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

| 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](https://docs.asciinema.org/manual/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. |

> **Warning:**
**Also record what is typed** includes passwords typed at prompts that do not show them, such as `sudo` or `mysql -p`. Keep it off unless you need a record of every key.

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 |
