Repository navigation
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.
| 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"
}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/"]
-
Finding the project root.
runwalks up from the scenario file, andrecordwalks up from the current directory, to the first directory withdemoflow.config.json. With no such directory the command fails withno-project-config. A config that fails the schema fails withinvalid-config. -
Defaults. Any key you leave out takes its default.
allowedOriginsdefaults to the origin ofbaseUrl. -
Starting the app. If
devCommandis set andreadyUrldoes not already answer, the command is started in the project root andreadyUrlis polled until it answers. -
Finding the artifacts home. The first source that is set wins, in the order shown in the diagram. Runs go in
<home>/runs/<runId>/.
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.
| 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.
- 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.
readyUrlis polled every 250 ms. -
Already running: if
readyUrlalready 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 /Fon Windows. - It waits up to 5 s before it forces the stop.
- It sends SIGTERM to the process group, or uses
| 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. -
angleis 0–360 degrees and works as in CSSlinear-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).
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:
-
--out, relative to the current directory -
DEMOFLOW_HOME, relative to the current directory - the project's
artifactsDir, relative to the project root - the global
artifactsDir - the OS data directory
The MCP server also stages inline scenarios in <home>/mcp/.
-
No code in the config. It is never executed, has no environment interpolation, and
devCommandruns 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:
-
devCommandis accepted by its schema, but 0.1.0 does not start the app. -
render.frameandrender.backgroundare ondevelop, after 0.1.0.
-
DemoFlow · Issues · Decision records · Specs · MIT licensed
Start
Features
- Scenarios
- Recording Scenarios
- Running Demos
- Rendering and Effects
- Secrets and Masking
- Run Artifacts
- MCP Server
Operate
Reference