# Recording policy

URL: https://shellz.dev/docs/guides/recording-policy

> Choose what happens when recordings can't be uploaded, with fail closed, buffer or fail open.

Recordings are written to a spool on the server or in the container first, then uploaded. Usually the spool is nearly empty. If the network or shellz is unreachable for a while, it fills up. The **recording policy** decides what happens then.

## Failure modes

| Mode | When the spool reaches its limit | Use it when |
|---|---|---|
| **Fail closed** | New interactive sessions are refused. Once the spool is full, running sessions are ended. | Every session must be recorded, even at the cost of access. |
| **Buffer** | New sessions are refused. Running sessions continue, up to twice the limit, so nobody is cut off mid-task. | You want strong guarantees without interrupting work. |
| **Fail open** | Sessions continue unrecorded, with an alert. | Access matters more than the recording, for example on break-glass machines. |

In every mode, a problem is reported as an alert: `session-refused` when a login is refused, `recording-failed` when a running session can't be recorded.

### Per-account fairness

Outside fail-open, one account can use at most a quarter of the spool limit. If one account produces a huge amount of output while uploads are stalled, its new sessions are refused (and, under fail-closed, its running sessions ended) before it can fill the spool for everyone else.

### Commands without a terminal in containers

In containers, commands run without a terminal, such as health checks and probes, are never refused in any mode, so a recording problem can't restart your pods. See [Commands without a terminal](https://shellz.dev/docs/install/container-image.md#commands-without-a-terminal).

## Defaults

| | Servers | Container fleets |
|---|---|---|
| Failure mode | Buffer | Fail closed |
| Spool limit | 512 MiB | 64 MiB |
| Record consoles | On | Off |

**Record consoles** controls whether logins on physical, serial and hypervisor consoles (`tty1`, `ttyS0`, `hvc0`) are recorded. It's on by default for servers. Turning it off keeps a way in through the console if recording ever refuses logins.

## Changing the policy

### Container fleets

Open the fleet from **~/servers**, then use the **Recording policy** card: choose **Fail closed**, **Buffer** or **Fail open**, set the **Spool limit (MiB)**, and save. Owners and admins can change it, after confirming it's them. Members pick up the change on their next heartbeat, within about 30 seconds.

### Servers

Servers use the defaults above. Per-server policy changes are made by owners and admins through the shellz API; a policy editor for servers isn't in the dashboard yet.

## How a policy reaches a server

Policies are signed by your org's key and carry a revision number. A server applies a policy only if the signature is valid, it names that server (or its fleet), and its revision is higher than the one it has. In [Perfect Secrecy](https://shellz.dev/docs/security/perfect-secrecy.md) mode, policies are signed in your browser, so shellz can't change them on its own.

Every applied policy raises a `policy-updated` alert on that server, and every change made in the dashboard or API is written to the audit log. A policy can also turn recording off for a server, which restores the original login shells; like any policy, it has to be signed by your org.