Repository navigation
Security and Access
DemoFlow runs entirely on your machine: the CLI and the MCP server drive a local Chromium against your app and write files to a local directory. This page lists the guards that keep a run inside the origins you allowed and keep secrets out of files, logs and video.
| Area | What protects it |
|---|---|
| Where the browser may go | The origin allowlist (allowedOrigins), checked before the browser starts and during the run |
| Passwords and tokens |
valueFrom: { env } in fill steps, so the value never appears in the scenario, the timeline, error messages or the video |
| What starts on your machine | Only the devCommand in the project's own demoflow.config.json
|
| Who can call the MCP server | Only the local process that started it, over stdio. It opens no network port |
| What reaches the cloud | Nothing. There are no accounts and no upload yet |
Note
Accounts, the website, the Runner and cloud sync are not built. ADR-0006, ADR-0007 and ADR-0008 describe the planned design. Today every command works without an account and sends nothing anywhere.
flowchart LR
S["Scenario + demoflow.config.json"] --> R{"Readiness check"}
R -- "origin not allowed / env missing" --> X["Run fails, browser never starts"]
R -- ok --> B["Chromium"]
B -- "every top-level navigation" --> G{"Origin guard"}
G -- foreign origin --> F["Step fails: origin-not-allowed"]
G -- allowed --> A["Your app"]
B --> V["source.webm"] --> M["Renderer blurs mask boxes"] --> O["ffmpeg.mp4"]
-
Readiness. Before Chromium launches, the engine checks that the base URL and every
navigatetarget are in the allowlist and that everyvalueFrom.envvariable is set and non-empty. The first problem fails the run withorigin-not-allowed <origin>ormissing-env <NAME>, and the CLI exits 2 (readiness.ts). -
Navigation guard. During the run the engine watches every top-level navigation, however it started: a link, a redirect, a script or a popup. A navigation to an origin outside the allowlist fails the step (run.ts).
about:pages and Chromium's own error page are not treated as origins. -
Secrets. A
fillwithvalueFrom: { env: "NAME" }reads the value from the process environment when the step runs. The timeline records the step asmasked: truewithvalue: "***", and the secret's value is replaced with***in error messages. - Masking in the video. The engine records where the secret field is visible, and the renderer blurs that box in every frame of the final video. See Secrets and Masking.
-
App start.
demoflow runanddemoflow recordstart your app only fromdevCommandin the project'sdemoflow.config.jsonon disk. The command is spawned without a shell, with the project root as its working directory.
Allow an extra origin, for example a separate auth server, in demoflow.config.json:
{
"baseUrl": "http://localhost:3000",
"allowedOrigins": ["http://localhost:3000", "http://localhost:4000"]
}Without allowedOrigins, only the origin of baseUrl is allowed. Entries are bare origins (scheme, host and port), not paths.
Keep a password out of the scenario file:
{ "action": "fill", "target": { "label": "Password" }, "valueFrom": { "env": "DEMO_PASSWORD" } }DEMO_PASSWORD=… npx demoflow run demoflow/login.demo.jsondemoflow record writes password fields, and fields you mark with Secret next, as valueFrom.env steps. It never reads the typed value. The env name defaults to DEMO_PASSWORD.
demoflow mcp is a stdio server. The MCP client (for example Claude Code) starts it as a child process and talks to it over stdin and stdout. It does not listen on a network port, so only that client can reach it (command.ts).
-
projectmust be an absolute path to a directory that hasdemoflow.config.json, or to a directory below one. Otherwise the call returnsproject-not-found. -
filemust be a*.demo.jsoninside the project root. Paths are compared by their real paths, so a symlink cannot point outside the project. Anything else returnsfile-not-in-project(project.ts). - An inline
scenariois written to<home>/mcp/<taskId>.demo.jsonfor the run, and deleted before the task reaches its final status. - Every run goes through the same readiness checks and origin guard as
demoflow run.
| Key / variable | Where | Effect |
|---|---|---|
baseUrl |
demoflow.config.json |
Its origin is allowed by default |
allowedOrigins |
demoflow.config.json |
The full origin allowlist, replacing the default |
devCommand |
demoflow.config.json |
The only command DemoFlow may start |
valueFrom.env |
a fill step |
Names the environment variable that holds the secret. Must match ^[A-Z_][A-Z0-9_]*$
|
See Project Configuration for every key.
- It never writes a
valueFrom.envvalue to the scenario,timeline.json,result.jsonor error messages. It still drives the real browser, so whatever the page itself does with the value is outside DemoFlow. - Masking is applied to the rendered video only.
source.webmandscreenshotstep images in the run directory are unmasked; sharerender/ffmpeg.mp4, not the run directory. See Secrets and Masking. - Masking covers fields filled through
valueFrom.env. Other sensitive data on the page, for example a customer list, is recorded as it appears. Use test data. - It does not sandbox your app.
devCommandruns with your user's permissions. - It does not authenticate MCP callers: the MCP client is your local OS user.
- It uploads nothing. The run directory stays where the artifact home puts it.
- The origin guard watches top-level navigations, not subresource requests. A page can still load scripts, images or API calls from other origins.
Warning
Run DemoFlow only against apps and data you are allowed to record. The video shows everything on the page except the masked boxes.
The website and Runner design keeps the same boundary (ADR-0008):
- The CLI and the MCP server keep working without an account.
- A runner would send only metadata: the scenario's name and steps, stage statuses, durations and sizes, and the error message. It would never send
fillvalues, URL query strings, logs, screenshots, video or local file paths. - The website could only start a committed scenario by id, cancel a run, stream a video or delete artifacts. It could never send a scenario body, a command or a URL.
- Sign-in would use GitHub OAuth or email and password (ADR-0006).
- Runner pairing would use a device code and a device token (ADR-0007).
See Status and Roadmap.
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