NetStacksNetStacks
Contact SalesDownload

Session Recording & Logging

Record terminal sessions as asciicast for replay, and capture plain/raw/HTML text logs. Play back, rename, share, and delete recordings from the Recordings library.

Overview

NetStacks captures terminal sessions two ways, for two different jobs:

  • Session recording — a time-accurate asciicast (asciinema v2) capture you can replay in a built-in player at variable speed. Best for audit trails, training, and reviewing exactly what happened on a device.
  • Session logging — a flat text transcript (plain, raw, or HTML) written to a file on disk. Best for documentation, pasting into tickets, and quick reference.

Both are started from the terminal's right-click context menu and run independently — you can record, log, or do both at once.

What gets captured

  • Recording — the byte stream the terminal renders (output) plus your input, each tagged with a time offset, in asciicast v2 format. ANSI colors, cursor movement, and timing are preserved for replay.
  • Logging — output processed into the chosen format: plain (ANSI stripped), raw (escape codes kept), or HTML (colors converted to inline styles). Per-line timestamps are optional.
Warning

Recordings and logs capture everything displayed in the terminal, including passwords, keys, or other sensitive data that may appear on screen. Treat the asciicast files and log files as sensitive and secure the directories they live in.

Note

Session recording is a local feature (capability local_session_recording) and is enabled by default in the free build. Recordings and logs are stored on your own machine — the product sends no telemetry.

How It Works

When you start a recording, a capture manager hooks the terminal's input and output streams. Each chunk is timestamped with its offset (in seconds) from the moment recording started and encoded as an asciicast v2 event. Output events are written as [time, "o", data] and input as [time, "i", data].

  1. Create — a recording row is created with a name, the terminal's current column/row dimensions, and (when available) the session id.
  2. Buffer & flush — events accumulate in a buffer and are appended to the on-disk asciicast file roughly every 2 seconds, so long sessions don't hold everything in memory.
  3. Finalize — on stop, the buffer is flushed one last time and the total duration (in milliseconds) is written to the recording record.

Where recordings are stored

Each recording is tracked as a record on the local agent and backed by an asciicast file on disk. The agent stores the file path; deleting a recording removes both the record and the file. Recordings are listed newest-first. Only the playback player parses the file — there are no separate metadata or index sidecar files.

Note

Recording adds little overhead: capture is buffered and flushed asynchronously on a timer, so it does not block terminal I/O.

Recording a Session

Start and stop

  1. Connect to a device and open the terminal session you want to capture.
  2. Right-click anywhere in the terminal to open the context menu.
  3. Choose Start Recording (the record icon). Capture begins immediately using the terminal's current dimensions.
  4. Do your work — all output and input is captured automatically.
  5. Right-click again and choose Stop Recording to finalize. The capture then appears in the Recordings library.
Note

There is no dedicated keyboard shortcut for recording, and no "auto-record all sessions" toggle — recording is started and stopped manually from the context menu. (Note: Cmd/Ctrl+Shift+R is the Reconnect Session shortcut, not a recording toggle.)

Naming and managing

New recordings are given an automatic name. Open Settings → Recordings to rename a capture to something meaningful (for example a change-ticket number) so it's easy to find later. You can rename at any time; the rename only changes the display name, not the underlying file.

Warning

Only one recording can be active per terminal at a time. Starting a second recording while one is already running returns a "Recording already in progress" error.

Playback & the Recordings Library

Open Settings → Recordings to see every recording stored on this machine, listed newest-first. Each row shows the name, creation time, duration, and the terminal dimensions it was captured at (for example 120×40). Recordings referenced from a document are also reachable from that document.

Library actions

Filter
Type in the filter box to match recordings by name or date.
Play
Opens the recording in the built-in asciicast player.
Rename
Edit the display name inline (Enter to save, Esc to cancel).
Share
Downloads the recording as a portable .cast file.
Delete
Permanently removes the recording record and its asciicast file from disk. This cannot be undone.

Player controls

The player renders the recording into a real terminal and gives you:

  • Play / Pause and Stop (stop resets to the beginning).
  • Seek — click anywhere on the progress bar to jump to that point; the player replays output up to that time.
  • Elapsed / total time readout in m:ss format.
  • Playback speed selector with discrete options: 0.5x, 1x, 1.5x, 2x, and 4x.
Note

The player replays the recorded output stream as a terminal — there is no in-recording text search or per-command index. To search the content of a session, use Session Logging (below) and search the resulting text file, or export the .cast and grep it.

Asciicast Format & Export

Recordings use the open asciicast v2 format. The first line is a JSON header (version, width, height); each following line is a JSON event array of [time, type, data], where type is "o" for output or "i" for input.

session.castjson
{"version": 2, "width": 120, "height": 40, "timestamp": 1741616400}
[0.512, "o", "core-rtr01# "]
[1.004, "i", "show ip bgp summary\r"]
[1.230, "o", "\r\nBGP router identifier 10.0.0.1, local AS number 65100\r\n"]
[1.412, "o", "Neighbor        V    AS  MsgRcvd  MsgSent  Up/Down  State\r\n"]
[1.480, "o", "10.0.0.5        4 65200      120      118  01:59:42        3\r\n"]
[4.900, "i", "configure terminal\r"]

Export / Share

In Settings → Recordings, the Share action downloads the recording as a single .cast file with the MIME type application/x-asciicast. The filename is derived from the recording's name (sanitized).

Replay anywhere

Because the file is standard asciicast v2, you can replay it with any asciinema-compatible player, embed it on a web page, or convert it with community tooling. NetStacks exports the .cast file only — there is no built-in HTML, GIF, or asciicast-to-video conversion.

work-with-cast.shbash
# Replay an exported recording with the asciinema CLI
asciinema play core-rtr01-bgp-maint.cast

# Inspect the raw events (first line is the JSON header)
head -1 core-rtr01-bgp-maint.cast | python3 -m json.tool

# Pull just the typed commands ("i" events) out of a capture
grep '"i"' core-rtr01-bgp-maint.cast

Session Logging

Session logging writes a text transcript of a terminal to a file as you work. Unlike a recording (which you replay), a log is a plain file you can open, search, or paste anywhere.

Start and stop

  1. Right-click in the terminal to open the context menu.
  2. Choose Start Session Logging. Logging starts using the plain text format by default.
  3. Right-click and choose Stop Session Logging when done.

Formats

  • Plain Text — ANSI escape codes stripped. The most readable format for documentation and sharing.
  • Raw (ANSI) — exact terminal output, including all escape and control sequences. Useful for debugging rendering issues.
  • HTML — output converted to HTML with inline styles so colors are preserved when opened in a browser.

An optional Timestamp each line toggle prefixes every line with an ISO-8601 timestamp (applied to plain and raw formats).

plain-log-with-timestamps.logtext
[2026-03-10 14:30:22.104] core-rtr01# show ip bgp summary
[2026-03-10 14:30:22.310] BGP router identifier 10.0.0.1, local AS number 65100
[2026-03-10 14:30:22.355] Neighbor        V    AS  MsgRcvd  MsgSent  State
[2026-03-10 14:30:22.402] 10.0.0.5        4 65200      120      118      3

Where logs are stored

Log files are written under the NetStacks logs directory in your home folder:

log-directorytext
~/Documents/NetStacks/logs/

For safety, the agent confines all log writes to this directory — paths outside it are rejected. Captured logs also surface in the app as documents under the Logs folder in the Docs panel and in Settings → Session Logs, where you can open or download them as .log files.

Recording vs. logging

Use a recording when you need a time-accurate, replayable capture for audit or training. Use a log when you want a text transcript that's easy to search, grep, or paste into a runbook or ticket.

Troubleshooting Sessions

Separate from recording and logging, NetStacks has a Troubleshooting Session workflow. Started from the status bar, it captures the commands and outputs of a debugging session — and, optionally, the AI conversation alongside it — then generates a structured document you can save to the Docs panel for future reference.

Settings (Settings → Troubleshooting)

Inactivity Timeout
Automatically end the session after this many minutes of inactivity (1–120).
Auto-save on Timeout
Generate and save the session document automatically when the session times out.
Capture AI Conversations
Include AI chat messages in the session log so the generated document has the reasoning context.
Note

This is the "Troubleshoot" control on the status bar — it is distinct from Start Recording and Start Session Logging in the terminal context menu.

Q&A

Q: How do I start recording a session?
A: Right-click in the terminal and choose Start Recording. Right-click again and choose Stop Recording to finalize. There is no keyboard shortcut for recording.
Q: Is there an "auto-record everything" setting?
A: No. Recording is started and stopped manually per terminal from the context menu. The Settings → Recordings tab is a library for playing back, renaming, sharing, and deleting captures — it has no auto-record, retention, or maximum-size options.
Q: Where are recordings stored?
A: Each recording is tracked by the local agent and backed by an asciicast file on disk; the agent keeps the file path. Deleting a recording removes both the record and the file. Everything stays on your machine.
Q: What playback speeds are available?
A: The player offers 0.5x, 1x, 1.5x, 2x, and 4x. You can also click the progress bar to seek to any point.
Q: Can I search inside a recording?
A: The player replays the output stream and does not provide in-recording text search or a command index. To search session content, use Session Logging and search the resulting text file, or export the .cast and grep it.
Q: How do I export or share a recording?
A: In Settings → Recordings, use the Share action to download a portable .cast (asciicast v2) file you can replay with any asciinema-compatible player. Only the .cast format is exported.
Q: What is the difference between recording and logging?
A: A recording is a time-accurate asciicast you replay in the built-in player. A log is a flat text transcript (plain, raw, or HTML) written to ~/Documents/NetStacks/logs/ that you open or search like any file. They run independently.
Q: Does recording slow down my session?
A: No noticeable impact. Captured events are buffered and flushed asynchronously every couple of seconds, so terminal I/O is not blocked.

Troubleshooting

Start Recording / Start Session Logging is missing from the menu

  • Recording menu items only appear when the local_session_recording capability is enabled (it is on by default in the free build).
  • Make sure you right-clicked inside an active terminal session, not on a detection popover or selection — detection-specific menus show a different set of items.

"Recording already in progress"

  • A terminal can have only one active recording at a time. Stop the current recording before starting a new one.

Playback shows an error or won't load

  • The player parses asciicast v2. If a file was transferred from another machine, confirm the first line is a valid JSON header with "version": 2 and that it was not truncated.
  • Empty or zero-event captures (recording stopped immediately after starting) have no output to replay.

Recording is empty or very short

  • Events are flushed to disk on a timer (about every 2 seconds) and a final flush runs on stop. If the app was force-quit before stopping, the last few seconds may not have been written.

Session log file not appearing

  • Logs are written under ~/Documents/NetStacks/logs/. The agent rejects log paths outside this directory, so custom paths must live inside it.
  • Logs also surface in Settings → Session Logs and under the Logs folder in the Docs panel — check there if the file isn't where you expect.