ptymotion

ptymotion records scripted terminal scenarios with real PTY behavior inside isolated Docker containers.

It is designed for repeatable terminal demos: deterministic input timing, reproducible render settings, and artifact output as MP4, GIF, and screenshots.

Highlights

• Runs target apps in Docker with per-session isolation
• Uses a real PTY (docker exec -it) for full-screen/curses TUIs
• Replays captured terminal stream in a dedicated renderer container
• Exports high-quality 60 FPS MP4 + GIF automatically
• Supports multiple recording segments and checkpoints per run

Requirements

• Rust (stable)
• Docker daemon

No host Playwright/Bun/ffmpeg installation is required. Renderer dependencies live in a Docker image built automatically.

Install

cargo build --release
./target/release/ptymotion --help

Quick Start

cargo run -- validate scenarios/shell-demo.toml
cargo run -- dry-run scenarios/shell-demo.toml
cargo run -- record scenarios/shell-demo.toml

The first record run builds ptymotion-renderer:0.3.0 and can take a while.

Real-World Example Scenarios

These scenarios are production-style examples you can run directly:

• scenarios/shell-demo.toml shell walkthrough with natural typing, screenshots, resize, and segmented saves
• scenarios/top-demo.toml full-screen TUI capture (top) with clean start/stop timing
• scenarios/colors-demo.toml ANSI color rendering and theme consistency demo
• scenarios/flow-demo.toml typed command flow with checkpoints and multiple output segments
• scenarios/process-audit-demo.toml process inspection and filtering workflow demo
• scenarios/log-pipeline-demo.toml log slicing and pipeline walkthrough demo
• scenarios/file-audit-demo.toml filesystem triage and audit command sequence demo
• scenarios/system-check-demo.toml host/environment diagnostics and sanity checks demo

Run any example:

cargo run -- record scenarios/colors-demo.toml

Website demo media generated from real runs is stored in website/public/demo/.

CLI

• ptymotion validate <scenario.toml> validate scenario config
• ptymotion dry-run <scenario.toml> print ordered action execution only
• ptymotion run <scenario.toml> execute scenario; renders if recording segments exist
• ptymotion record <scenario.toml> execute scenario and require at least one recording segment

Minimal Scenario

[app]
image = "ubuntu:24.04"
workdir = "/workspace"
hostname = "demo"
prompt_user = "alice"
prompt_host = "lab"

[[app.env]]
key = "TERM"
value = "xterm-256color"

[terminal]
cols = 120
rows = 36
font_family = "JetBrains Mono"
font_size = 18
line_height = 1.2
padding = 10

[docker]
network_disabled = true
memory_limit = "512m"
cpus = 1.0
pids_limit = 256

[[actions]]
type = "start_recording"

[[actions]]
type = "type_text"
text = "ls --color=always"
interval_millis = 60

[[actions]]
type = "send_key"
key = "Enter"

[[actions]]
type = "save_recording"
name = "listing"

[[actions]]
type = "run"
command = "top"

[[actions]]
type = "wait"
seconds = 2.0

[[actions]]
type = "send_key"
key = "q"

[[actions]]
type = "stop_recording"

[output]
dir = "./artifacts"
save_event_log = true

Recording Model

• PTY output is captured continuously from session start.
• start_recording opens a segment window.
• save_recording writes a segment checkpoint and keeps recording active.
• stop_recording closes the active segment.
• Multiple segments per run are supported.

Output Artifacts

Each run creates artifacts/run-*/ (or your configured output dir).

• session*.mp4 rendered MP4 videos
• session*.gif GIF versions of each segment
• screenshots/*.png timeline screenshots from take_screenshot
• events.json raw PTY chunks (save_event_log = true)
• recording_payload.json renderer payload
• render_meta.json renderer metadata

Docs

• docs/scenario-reference.md full config schema and action reference
• docs/recording-model.md segment/checkpoint behavior and naming
• docs/architecture.md runtime architecture and module boundaries
• docs/hardening.md container restrictions and threat tradeoffs
• docs/faq.md common issues and fixes

Website

Astro website lives in website/.

cd website
bun install
bun run dev

Demo assets used by the site are in website/public/demo/.