Skip to content

Security and Access

Archi edited this page Oct 18, 2026 · 1 revision

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.

Overview

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.

How it works

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"]
Loading
  1. Readiness. Before Chromium launches, the engine checks that the base URL and every navigate target are in the allowlist and that every valueFrom.env variable is set and non-empty. The first problem fails the run with origin-not-allowed <origin> or missing-env <NAME>, and the CLI exits 2 (readiness.ts).
  2. 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.
  3. Secrets. A fill with valueFrom: { env: "NAME" } reads the value from the process environment when the step runs. The timeline records the step as masked: true with value: "***", and the secret's value is replaced with *** in error messages.
  4. 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.
  5. App start. demoflow run and demoflow record start your app only from devCommand in the project's demoflow.config.json on disk. The command is spawned without a shell, with the project root as its working directory.

Using it

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.json

demoflow 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.

The MCP server

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).

  • project must be an absolute path to a directory that has demoflow.config.json, or to a directory below one. Otherwise the call returns project-not-found.
  • file must be a *.demo.json inside the project root. Paths are compared by their real paths, so a symlink cannot point outside the project. Anything else returns file-not-in-project (project.ts).
  • An inline scenario is written to <home>/mcp/<taskId>.demo.json for 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.

Settings

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.

Limits / what it never does

  • It never writes a valueFrom.env value to the scenario, timeline.json, result.json or 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.webm and screenshot step images in the run directory are unmasked; share render/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. devCommand runs 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.

Planned, not built

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 fill values, 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.

See also

Clone this wiki locally