Session Recording

Record and replay remote session operations for auditing and training.

Overview

Session recording captures commands executed on remote hosts and their output in asciinema v2 format. Recordings are stored compressed and can be replayed later in the terminal.

How Recording Works

Commands executed during a session are automatically recorded:

A .cast.gz file is created when the session starts
Each command execution and its output are recorded with timestamps
Includes prompt lines, stdout, stderr (in red), and exit codes
A .meta.json metadata file is generated when the session ends

Configuration

Session recording can be enabled with the default settings:

yaml

defaults:
  recording:
    enabled: true

CLI Commands

List Recordings

bash

nefia recording list
nefia recording list --limit 10

Displays metadata (session ID, host ID, user, command count, duration, size).

Replay a Recording

bash

nefia recording replay <session-id>

Flag	Description	Default
`--speed`	Playback speed	`1` (real-time)

Speed Value	Behavior
`0`	Instant playback (no timing)
`1`	Real-time playback
`5`	5x speed playback

Playback can be canceled with Ctrl+C.

Export a Recording

bash

nefia recording export <session-id>
nefia recording export <session-id> --out recording.cast

Decompresses the .cast.gz file and outputs it as a .cast file. Can be used with asciinema players and other tools.

Delete a Recording

bash

nefia recording delete <session-id>

Deletes the recording file after a confirmation prompt.

Storage Format

.cast.gz File

asciinema v2 format (gzip compressed):

jsonl

{"version": 2, "width": 120, "height": 40, "timestamp": 1709000000, "title": "session-abc123"}
[0.0, "o", "$ whoami\r\n"]
[0.1, "o", "root\r\n"]
[0.5, "o", "$ systemctl status nginx\r\n"]
[0.8, "o", "● nginx.service - A high performance web server\r\n"]

.meta.json File

json

{
  "session_id": "abc123...",
  "host_id": "web-01",
  "user": "admin",
  "shell": "/bin/bash",
  "start_time": "2026-03-10T10:00:00Z",
  "end_time": "2026-03-10T10:15:00Z",
  "command_count": 12,
  "duration_ms": 900000,
  "size_bytes": 45678,
  "payload_bytes": 123456,
  "truncated": false
}

Field	Description
`session_id`	Unique session identifier
`host_id`	Target host ID
`user`	SSH user
`shell`	Remote shell path
`start_time`	Session start time (RFC 3339)
`end_time`	Session end time (RFC 3339)
`command_count`	Number of commands executed
`duration_ms`	Session duration in milliseconds
`size_bytes`	Compressed `.cast.gz` file size
`payload_bytes`	Uncompressed payload size (omitted if zero)
`truncated`	Whether the recording was truncated due to the size limit (omitted if false)

Storage and Retention

Item	Value
Storage location	`<state-dir>/recordings/`
File naming	`<session-id>.cast.gz` + `<session-id>.meta.json`
File permissions	`0o600` (owner read/write only)
Default retention period	90 days
Uncompressed size limit	50 MB
Export decompression limit	512 MB (zip bomb protection)

Recordings that exceed the retention period are automatically deleted during cleanup.

Recorded Output Contents

Element	Representation
Prompt	`$ <command>\r\n`
Standard output	Recorded as-is
Standard error	With ANSI red color codes (`\x1b[31m...\x1b[0m`)
Non-zero exit code	`[exit <code>]`

MCP Tools

Session recordings can be managed by AI agents via MCP:

Tool	Description
`nefia.recording.list`	List all session recordings with metadata.
`nefia.recording.show`	Show detailed metadata for a specific recording.
`nefia.recording.delete`	Delete a recording (subject to retention policy).
`nefia.recording.export`	Export a recording in a specified format.