Session Recording

Overview

Session Recording captures every command, output, and timing detail from your terminal sessions. Whether you need an audit trail for compliance, a playback of a late-night troubleshooting session, or training material for your team, recordings give you a complete, time-accurate replay of exactly what happened on a device.

Key Capabilities

• Full session capture -- all terminal input and output with precise timing, including terminal dimensions at each point
• Command indexing -- every command executed during a session is indexed for fast searching across recordings
• Local and Controller storage -- store recordings on your local machine or upload them to a Controller for centralized access
• Playback with variable speed -- replay sessions at 0.25x to 8x speed with full player controls
• Export formats -- export recordings as asciicast (.cast), plain text logs, self-contained HTML, or animated GIF

Use Cases

• Compliance and audit -- maintain a tamper-proof record of all privileged access to production network devices
• Troubleshooting review -- replay a session to trace the exact sequence of commands that led to an outage or recovery
• Training and onboarding -- record procedures for new engineers to follow step by step
• Incident response -- capture every action taken during a network incident for post-mortem analysis
• Change documentation -- record maintenance windows as proof of work and rollback reference

How It Works

The recording engine sits between the SSH transport layer and the terminal renderer. Every byte of data flowing in and out of the terminal is captured with a microsecond-resolution timestamp, producing a frame-by-frame record of the entire session.

Capture Pipeline

1. Stream interception -- the recording module taps into the terminal data stream without affecting session performance or latency
2. Frame encoding -- output is encoded into time-stamped frames in asciicast v2 format, preserving ANSI escape sequences, colors, and cursor positioning
3. Command indexing -- a parser identifies command boundaries by detecting prompt patterns, then indexes each command with its timestamp and output range
4. Storage -- completed recordings are compressed and written to the configured storage location (local disk or Controller)

Storage Modes

Retention Policies

Recordings can be automatically purged after a configurable retention period. In standalone mode the default is 30 days. In Controller mode, administrators set organization-wide retention policies that override local settings. Typical enterprise retention ranges from 90 days to 1 year depending on compliance requirements.

Metadata and Indexing

Every recording stores structured metadata including session host, username, timestamps, duration, terminal dimensions, and the complete command index. The command index allows you to search across all recordings for specific commands like show running-config or reload and jump directly to the point in the recording where that command was executed.

Step-by-Step Guide

Workflow 1: Manually Recording a Session

1. Connect to a device via SSH
2. Click the record button (circle icon) in the status bar, or press Cmd/Ctrl+Shift+R
3. Optionally enter a description for the recording (e.g., "BGP maintenance on core-rtr01")
4. The status bar displays a red recording indicator with elapsed time
5. Perform your work -- all commands and output are captured automatically
6. Click the record button again or press Cmd/Ctrl+Shift+R to stop
7. The recording is saved and appears in your recording library

Workflow 2: Configuring Auto-Record for All Sessions

1. Open Settings (Cmd/Ctrl+,)
2. Navigate to Recording
3. Enable Auto-record sessions
4. Configure the storage location (local, Controller, or both)
5. Set the retention period (e.g., 30 days, 90 days, or unlimited)
6. Optionally set a maximum recording size to prevent runaway captures (default: 100 MB)
7. Every new SSH connection will now be recorded automatically

Workflow 3: Playing Back and Searching a Recording

1. Go to File → Recordings to open the recording library
2. Browse recordings by date, host, or use the search bar
3. Double-click a recording to open the playback player
4. Use playback controls: Space to play/pause, ←/→ to adjust speed, Shift+←/Shift+→ to skip 10 seconds
5. Press Cmd/Ctrl+F to search within the recording -- results show timestamps you can click to jump directly to that point
6. Use the command index panel to see all commands executed during the session and click any command to jump to its execution point

Code Examples

Recording Configuration

# Recording settings (Settings > Recording)

Auto-record:           Enabled
Storage mode:          Both (Local + Controller)
Local path:            ~/NetStacks/recordings
Max recording size:    100 MB
Retention (local):     30 days
Retention (Controller): Set by administrator

Recorded Session Metadata

Each recording stores structured metadata that enables searching and filtering across your recording library.

{
  "id": "rec_2026-03-10_143022_core-rtr01",
  "host": "core-rtr01.dc-east.example.com",
  "username": "netadmin",
  "protocol": "ssh",
  "port": 22,
  "started_at": "2026-03-10T14:30:22Z",
  "ended_at": "2026-03-10T14:47:15Z",
  "duration_secs": 1013,
  "terminal_cols": 120,
  "terminal_rows": 40,
  "file_size_bytes": 245760,
  "description": "BGP maintenance - add new peer AS 65200",
  "command_count": 18,
  "storage": "both",
  "tags": ["maintenance", "bgp", "dc-east"]
}

Command Index

The command index captures every command with its timestamp, allowing you to search across recordings and jump to specific points.

# Command index for recording rec_2026-03-10_143022_core-rtr01
# Timestamp        Command
# ─────────────────────────────────────────────────────
  00:00:05         show ip bgp summary
  00:00:18         show running-config | section router bgp
  00:01:02         configure terminal
  00:01:05         router bgp 65100
  00:01:12         neighbor 10.0.0.5 remote-as 65200
  00:01:18         neighbor 10.0.0.5 description PEER-TO-BRANCH-02
  00:01:25         neighbor 10.0.0.5 update-source Loopback0
  00:01:33         address-family ipv4 unicast
  00:01:38         neighbor 10.0.0.5 activate
  00:01:42         neighbor 10.0.0.5 route-map BRANCH-IN in
  00:01:49         neighbor 10.0.0.5 route-map BRANCH-OUT out
  00:01:55         end
  00:02:00         show ip bgp summary
  00:02:15         show ip bgp neighbors 10.0.0.5
  00:02:42         ping 10.0.0.5 source Loopback0
  00:03:10         show ip route bgp
  00:15:30         write memory
  00:16:50         show ip bgp summary

Storage Path Structure

~/NetStacks/recordings/
├── 2026-03-10/
│   ├── rec_143022_core-rtr01.cast        # Asciicast recording
│   ├── rec_143022_core-rtr01.meta.json   # Metadata
│   ├── rec_143022_core-rtr01.idx         # Command index
│   ├── rec_091500_dist-sw01.cast
│   ├── rec_091500_dist-sw01.meta.json
│   └── rec_091500_dist-sw01.idx
├── 2026-03-09/
│   └── ...
└── 2026-03-08/
    └── ...

Q&A

Q: How do I start recording a session?

A: Click the record button (circle icon) in the status bar or press Cmd/Ctrl+Shift+R. You can optionally add a description before recording starts. To stop, press the same shortcut or click the button again.

Q: Where are recordings stored?

A: By default, recordings are saved locally to ~/NetStacks/recordings organized by date. When connected to a Controller, recordings can also be uploaded to centralized storage. You can configure the storage mode in Settings → Recording.

Q: Can I automatically record all sessions?

A: Yes. Enable Auto-record sessions in Settings → Recording. Every new SSH connection will be recorded automatically. In Controller mode, administrators can enforce mandatory recording for specific device types, users, or roles.

Q: How long are recordings kept?

A: The default local retention is 30 days, after which recordings are automatically purged. You can change this in Settings → Recording → Retention. In Controller mode, administrators set organization-wide retention policies (commonly 90 days to 1 year for compliance).

Q: Can I search within recordings?

A: Yes, in two ways. During playback, press Cmd/Ctrl+F to search for text within the recording -- results show timestamps you can click to jump to. Additionally, the command index lets you search across all recordings for specific commands (e.g., find every session where reload was executed).

Q: How do I export a recording?

A: Open the recording in the player, then use File → Export. Formats include asciicast (.cast) for asciinema-compatible playback, plain text log (.log) for text-only transcript, self-contained HTML (.html) for browser playback, and animated GIF (.gif) for sharing.

Q: What is command indexing and how does it work?

A: Command indexing automatically identifies and catalogs every command executed during a recorded session. The parser detects command boundaries by recognizing prompt patterns, then stores each command with its timestamp and output range. This enables searching across recordings by command text and jumping directly to the execution point in playback.

Q: Does recording affect terminal performance?

A: No. The recording engine captures data asynchronously from the terminal render pipeline. It adds negligible CPU overhead and does not introduce any visible latency to your session.

Troubleshooting

Recording Not Starting

• Verify you have an active SSH connection -- recording requires a connected session
• Check that the storage location is writable (Settings → Recording → Local path)
• If using Controller storage, confirm the Controller is reachable and your account has recording permissions
• Check disk space -- recordings cannot start if the storage volume is full

Storage Full or Recording Stopped Unexpectedly

• Recordings automatically stop when they reach the configured maximum size (default 100 MB)
• Free up disk space or increase the max recording size in settings
• Enable auto-purge to automatically delete recordings older than the retention period
• For long-running sessions, consider splitting recordings by starting and stopping manually at logical breakpoints

Playback Not Working

• Ensure the recording file (.cast) and its metadata (.meta.json) are both present in the recordings directory
• If the recording was transferred from another machine, verify the file was not truncated during transfer
• Try exporting to HTML format and opening in a browser as an alternative playback method

Command Index Missing Entries

• The command indexer relies on detecting prompt patterns. Non-standard or custom prompts may not be recognized
• Ensure the device type is correctly detected -- the indexer uses device-specific prompt patterns for Cisco IOS, JunOS, Arista EOS, and Linux
• Commands executed in configuration mode or subshells may use different prompt patterns that the indexer handles separately

Controller Upload Failures

• Check network connectivity to the Controller server
• Verify your account has the required permissions for recording upload
• If uploads fail, recordings are retained locally and re-queued for upload when connectivity is restored
• Large recordings may time out during upload on slow connections -- check Controller upload timeout settings

Related Features

• Terminal Overview -- understand the terminal interface where recordings originate
• Connecting to Devices -- set up the SSH connections that you record
• Audit Logs -- enterprise recordings integrate with audit logs for compliance reporting and SIEM integration
• AI Chat -- recorded sessions can provide context for AI-assisted troubleshooting and analysis
• Multi-Send Broadcast -- record multi-send sessions to capture bulk operations across multiple devices