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.

• 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 start/pause/stop recording windows with pause removal

• Rust (stable)
• Docker daemon

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

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

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.

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

• scenarios/shell-demo.toml shell walkthrough with natural typing, screenshots, resize, and paused intervals removed
• 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 pause/resume and named output
• 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
• scenarios/stassh-demo.toml real-world Stassh installation walkthrough and first-run usage demo

Run any example:

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

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

• 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 windows exist
• ptymotion record <scenario.toml> execute scenario and require at least one recording window

[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"

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

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

[[actions]]
type = "pause"

[[actions]]
type = "start"

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

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

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

[[actions]]
type = "stop"
name = "listing_and_top"

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

Scenario string values can reference environment variables as ${VAR_NAME}. ptymotion resolves variables from process env first, then from .env files discovered from the scenario directory upward.

• PTY output is captured continuously from session start.
• start opens or resumes active capture.
• pause closes the active window and removes elapsed pause time from output timeline.
• stop finalizes the current recording session and writes one named output file.
• stop requires name.
• take_screenshot uses full-session time and works at any action timestamp.

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

• session*.mp4 rendered MP4 videos
• session*.gif GIF versions of each named recording
• 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/scenario-reference.md full config schema and action reference
• docs/recording-model.md start/pause/stop 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

Astro website lives in website/.

cd website
bun install
bun run dev

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