Skip to content

Run Artifacts

Archi edited this page Oct 18, 2026 · 1 revision

Run Artifacts

Every demoflow run writes a self-contained run directory: the raw recording, the timeline of what happened, the scenario that ran, a machine-readable result and the rendered video. This page covers where that directory lives, what is in it, and how its result maps to the command's exit code.

Overview

Runs live under the home directory, at <home>/runs/<runId>/. The run id is YYYYMMDD-HHmmss-<6 lowercase base32 chars> in UTC, for example 20261018-200548-clfwzo. Recording and rendering are separate steps (ADR-0004). The engine writes the source video and the timeline, and the renderer reads them back to produce the MP4. A run directory therefore holds everything needed to render that run again.

How it works

flowchart LR
  E["Engine"] --> S["source.webm"]
  E --> T["timeline.json"]
  E --> C["scenario.json"]
  E --> R["result.json"]
  E --> P["screenshots/"]
  S --> RN["Renderer"]
  T --> RN
  R --> RN
  RN --> V["render/ffmpeg.mp4"]
  RN -. "updates rendering stage" .-> R
Loading
  1. Choose the home. The first match wins:
    1. --out <dir> (relative to the current directory)
    2. the DEMOFLOW_HOME environment variable (relative to the current directory)
    3. artifactsDir in the project's demoflow.config.json (relative to the project root)
    4. artifactsDir in the global config
    5. the OS data directory
  2. Create the run. The engine records source.webm and collects one timeline event per executed step. Each step's screenshot goes into screenshots/.
  3. Write the files. At the end of the run the capture observer writes timeline.json, scenario.json and result.json.
  4. Render. If source.webm exists, the renderer writes render/ffmpeg.mp4 and records it in result.json under renders[].
  5. Settle. The CLI closes the stages it owns and replaces result.json atomically. See Running Demos.

Using it

Default home (OS data directory):

OS Path
Linux $XDG_DATA_HOME/demoflow, else ~/.local/share/demoflow
macOS ~/Library/Application Support/demoflow
Windows %LOCALAPPDATA%\demoflow, else ~\AppData\Local\demoflow

Global config file (only artifactsDir is read from it):

OS Path
Linux $XDG_CONFIG_HOME/demoflow/config.json, else ~/.config/demoflow/config.json
macOS ~/Library/Application Support/demoflow/config.json
Windows %APPDATA%\demoflow\config.json

Run directory:

File Written by Holds
source.webm engine The raw recording at the viewport size (1×, ADR-0010).
timeline.json engine One event per executed step, plus the clock sync mark.
scenario.json engine The scenario that ran.
result.json engine, then CLI Stage statuses, run status, renders, warnings.
screenshots/ engine Files from screenshot steps.
render/ffmpeg.mp4 renderer The finished video: H.264, yuv420p, faststart.

To read a finished run from a script, use --json. It prints the final result.json with an extra runDir field.

Settings

timeline.json:

  • Top level: schemaVersion: 1, viewport, deviceScaleFactor, videoFile, events[], and optionally syncMark {colour, onMs, offMs}.
  • Per event: stepIndex, action, startMs, endMs, and where they apply:
    • target.box
    • pointer {from, to}
    • scroll {before, after, container?}
    • masked, value
    • assertion {passed, message?}
    • key (on press only)
    • screenshot
    • marker {title, kind}
    • caption
    • error {message}
    • maskVisibility (on a masked fill only)
  • Units: times are milliseconds from the video's first frame. Boxes and points are CSS pixels of the viewport.
  • Masked fills: the value is written as ***.

result.json:

Field Meaning
schemaVersion 1
runId The run directory's name.
scenarioId The scenario's path relative to the project root.
scenarioName The scenario's name.
startedAt, finishedAt ISO timestamps.
status completed, completed_with_warnings, failed or running.
stages readiness, execution, verification, recording, rendering and storage. Each has a status and optional startedAt, finishedAt and error {message, stepIndex?}.
renders[] {renderer, file, durationMs, sizeBytes, width, height, fps}. file is relative to the run directory.
warnings[] Strings.
  • Stage status is one of pending, running, passed, failed, skipped.
  • Run status is derived from the stages, never from whether a video exists:
    • any failed stage makes the run failed
    • any stage still pending or running makes it running
    • otherwise it is completed, or completed_with_warnings when there are warnings

A rendered video of a failed verification therefore belongs to a failed run.

Exit codes. The first failure in pipeline order decides:

Code When
0 The run completed, with or without warnings.
1 Execution or verification failed: a step failed, or an assertion did not hold.
2 Invalid input or readiness failed: a bad config or scenario, a disallowed origin, a missing base URL or secret, or an app that never answered.
3 Recording, rendering or storage failed, or a Chromium install or unexpected error occurred.
130 / 143 Interrupted by SIGINT / SIGTERM.

Limits / what it never does

  • Runs are never deleted or overwritten by DemoFlow. Every run gets a new directory, and an explicit --run-id that already exists is refused.
  • Nothing is uploaded. storage is always skipped, because cloud storage is not built yet.
  • A secret value is never written to timeline.json, result.json or error messages; masked values appear as ***. See Secrets and Masking.
  • The run directory has no index. To list runs, look in <home>/runs/ or use the list_demos tool of the MCP Server.

See also

Clone this wiki locally