Skip to content

Project Configuration

Archi edited this page Oct 18, 2026 · 1 revision

Project Configuration

A DemoFlow project is a directory with a demoflow.config.json at its root and scenarios under demoflow/. The config is data, never code. It says where the app runs, which origins a scenario may visit, how to start the app, where runs go, and how the video is rendered.

Overview

File Scope Read by
demoflow.config.json one project run, record, mcp; validated against the project-config schema
<config dir>/demoflow/config.json your user account only its artifactsDir key

The smallest valid config:

{
  "baseUrl": "http://localhost:3680"
}

How it works

flowchart TD
    A["--out flag"] -->|unset| B["DEMOFLOW_HOME"]
    B -->|unset| C["project artifactsDir"]
    C -->|unset| D["global config artifactsDir"]
    D -->|unset| E["OS data directory"]
    A & B & C & D & E --> R["home/runs/runId/"]
Loading
  1. Finding the project root. run walks up from the scenario file, and record walks up from the current directory, to the first directory with demoflow.config.json. With no such directory the command fails with no-project-config. A config that fails the schema fails with invalid-config.
  2. Defaults. Any key you leave out takes its default. allowedOrigins defaults to the origin of baseUrl.
  3. Starting the app. If devCommand is set and readyUrl does not already answer, the command is started in the project root and readyUrl is polled until it answers.
  4. Finding the artifacts home. The first source that is set wins, in the order shown in the diagram. Runs go in <home>/runs/<runId>/.

Using it

A fuller example:

{
  "baseUrl": "http://localhost:5173",
  "allowedOrigins": ["http://localhost:5173", "https://auth.example.com"],
  "devCommand": {
    "command": "npm",
    "args": ["run", "dev"],
    "readyUrl": "http://localhost:5173",
    "timeoutMs": 90000
  },
  "artifactsDir": ".demoflow",
  "render": {
    "width": 1920,
    "height": 1080,
    "fps": 30,
    "idle": { "thresholdMs": 1000, "compressToMs": 400 },
    "frame": { "enabled": true, "marginRatio": 0.06, "radius": 12, "shadow": true },
    "background": { "preset": "ocean" }
  }
}

Editor support. $schema is accepted at the top level, so an editor can validate and complete the file. The generated JSON Schema is packages/core/schemas/project-config.schema.json in the repository.

Settings

Project keys

Key Type / default Meaning
$schema string, optional JSON Schema reference for editors
baseUrl http(s) URL, required where relative navigate paths resolve
allowedOrigins array of origins, default the origin of baseUrl origins the browser may navigate to. Each must be a bare origin such as https://example.com, with no path
devCommand.command non-empty string the program that starts your app
devCommand.args array of strings, optional its arguments
devCommand.readyUrl http(s) URL polled until the app answers
devCommand.timeoutMs positive integer, default 60000 how long to wait for readyUrl
artifactsDir non-empty string, optional the artifacts home, relative to the project root
render.width / render.height positive integers, default 1920 / 1080 output size
render.fps positive integer, default 30 output frame rate
render.idle.thresholdMs integer ≥ 0, default 1000 a frozen stretch at least this long is compressed
render.idle.compressToMs integer ≥ 0, default 400 the length it is compressed to
render.frame.enabled boolean, default true the page in a rounded window on a background. false renders full-bleed
render.frame.marginRatio number, 0 or more and below 0.25, default 0.06 margin on every side, as a share of the output height
render.frame.radius number ≥ 0, default 12 corner radius in output pixels at 1080p, scaled with the output height
render.frame.shadow boolean, default true soft shadow under the window
render.background one of the forms below, default { "preset": "ocean" } what is drawn behind the window

Unknown keys are rejected at every level.

devCommand behaviour

  • Start: the command runs with no shell, with the project root as its working directory. The command and its arguments are data.
  • Ready: any HTTP answer below 500 counts, so a redirect or a 404 does too. readyUrl is polled every 250 ms.
  • Already running: if readyUrl already answers, nothing is started and your running app is used.
  • Failure: if the app exits early or never answers in time, the run fails at readiness and shows the app's last output.
  • Stopping: DemoFlow stops only an app it started.
    • It sends SIGTERM to the process group, or uses taskkill /T /F on Windows.
    • It waits up to 5 s before it forces the stop.

Backgrounds

Form Example
a preset { "preset": "dusk" }
a solid colour { "color": "#1e3a5f" }
a two-stop gradient { "gradient": { "from": "#0b2e4f", "to": "#2b86c5", "angle": 135 } }
  • Colours are #rrggbb.
  • angle is 0–360 degrees and works as in CSS linear-gradient: 0 runs towards the top, and angles go clockwise (90 runs towards the right).
  • Images are not supported as backgrounds.
Preset From To
ocean #0b2e4f #2b86c5
sunset #f7a35c #d6457a
forest #0d3b2e #3a9a68
dusk #28215a #a24e8e
graphite #1c1f24 #4a515c
paper #f4f0e8 #d8d2c5

Every preset runs at 135° (top left to bottom right).

Global config and the artifacts home

The global config holds one key, artifactsDir. A relative value is resolved against the file's own directory. A file that is malformed fails with invalid-global-config.

OS Global config Default artifacts home
Linux $XDG_CONFIG_HOME/demoflow/config.json, else ~/.config/demoflow/config.json $XDG_DATA_HOME/demoflow, else ~/.local/share/demoflow
macOS ~/Library/Application Support/demoflow/config.json ~/Library/Application Support/demoflow
Windows %APPDATA%\demoflow\config.json %LOCALAPPDATA%\demoflow

Home resolution order:

  1. --out, relative to the current directory
  2. DEMOFLOW_HOME, relative to the current directory
  3. the project's artifactsDir, relative to the project root
  4. the global artifactsDir
  5. the OS data directory

The MCP server also stages inline scenarios in <home>/mcp/.

Limits / what it never does

  • No code in the config. It is never executed, has no environment interpolation, and devCommand runs with no shell (ADR-0003 §6).
  • No secrets in the config. Secrets come from environment variables named in the scenario; see Secrets and Masking.
  • No stopping your app. An app that was already running is never stopped.
  • Published 0.1.0 is older:
    • devCommand is accepted by its schema, but 0.1.0 does not start the app.
    • render.frame and render.background are on develop, after 0.1.0.

See also

Clone this wiki locally