DemoFlow

Runner

You can pair a machine with your DemoFlow account and keep it connected, so the website shows it online. Nothing here is needed to make videos: every other command works without an account. With the runner connected, the site can also add a project from a folder on the machine, start runs on it and delete a run's files.

Pair a machine

npx demoflow login

The command prints a code such as ABCD-1234 and opens <server>/app/device?code=ABCD-1234. Check that the code matches your terminal, then approve it while signed in with a verified email. Over SSH with no browser, open <server>/app/device yourself and type the code. The code expires after 10 minutes.

Keep it connected

npx demoflow runner start

The runner is a background process that holds one connection to the server. After login, the CLI asks whether to start it; --start and --no-start answer in advance, and with no terminal it only prints the command.

CommandWhat it does
demoflow runner startStart the runner. A second start prints the PID of the one running.
demoflow runner stopStop it. logout stops it first.
demoflow runner statusShow whether it runs, its connection, the server and whether autostart is installed. --json prints one object.
demoflow runner logsPrint the runner's log. -f or --follow keeps printing.
demoflow runner installStart the runner at every login, and now.
demoflow runner uninstallStop starting it at login. A running runner keeps running until stop.

The connection is connected, reconnecting in Ns or revoked. When it drops, the runner reconnects with a backoff from 1 second doubling to 60. It exits for good if the machine is revoked on the website. Every 30 days the server rotates the token over the connection and the runner rewrites credentials.json.

Start at login

npx demoflow runner install

This registers the runner for your user, with no admin rights, and starts it now. It needs demoflow login first. The unit runs the same node and CLI that ran install, by absolute path, so run install again if you move or upgrade the CLI.

OSWhat it creates
Linuxa systemd user unit, ~/.config/systemd/user/demoflow-runner.service
macOSa LaunchAgent, ~/Library/LaunchAgents/dev.demoflow.runner.plist
Windowsa Task Scheduler task, DemoFlowRunner, at logon for the current user

A crash is restarted by systemd and launchd. A runner stopped on purpose, or revoked on the website, stays down. Windows does not restart a crash; the next logon starts it again. Neither unit holds the token.

Runs started from the website

On a project's page, the Run a scenario card starts a scenario on the machine the project is bound to. The card makes no request when the project has no folder or its machine was removed.

Which scenarios are listed

What the site chooses

The site sends the scenario's path and, if you choose, the output formats. Nothing else. The machine starts an ordinary demoflow run of that file with the project's own demoflow.config.json, its own devCommand and the runner's environment. The run is always headless. Size, frame, background and every other render setting come from demoflow.config.json.

By default the site sends no formats and the run makes the project's formats. Choose formats on the card picks any of the nine instead. A machine with an older CLI offers no choice: the card says to update the CLI, and the run makes the project's formats. Run again repeats the formats the run rendered; if the run rendered none, or the CLI is older, it uses the project's formats.

valueFrom.env secrets come from the runner's environment, which an autostart unit may not share with your shell.

Starting

Run asks for confirmation, naming the scenario and the machine. It is refused when:

While it runs

The status row shows Starting, Running, Cancelling, Passed, Failed, Cancelled, Timed out or Lost contact.

While a run is going, the card also shows what the machine is doing: starting the app, which step of how many it is on, or rendering the video. A machine with an older demoflow shows only Running.

When it ends

Add a project from the website

A project appears on the site after a local run, or when you add its folder from the website. Adding needs a paired machine whose runner is connected and whose CLI is up to date. Nothing is cloned or downloaded: the folder must already be on that machine.

  1. On Projects, press Add project.
  2. Choose the machine. A machine that is offline or runs an older CLI is marked and cannot be chosen. The page preselects the machine that reported the latest run.
  3. Type the folder as an absolute path on that machine, for example /home/you/my-app, /Users/you/my-app or C:\Users\you\my-app. After you stop typing, the machine looks at the folder.
  4. The dialog shows what the machine found:
    • demoflow.config.json found: the folder name, up to five scenario names with the count, and the GitHub link of the origin remote when it is on github.com.
    • No config: press Create config. The machine writes demoflow.config.json and demoflow/first.demo.json, the same files as demoflow init, and never overwrites a file that exists. The dialog names the files it wrote. Then set devCommand and baseUrl in demoflow.config.json in the repository: the website cannot set them.
    • A config that cannot be read: fix it in the repository, then type the path again.
  5. Give the project a name and, if you like, its GitHub repository (https://github.com/<owner>/<repo>). The link is only shown on the site and can be edited later; nothing is fetched from it.
  6. Press Add project. The project opens, and you can run its scenarios from the site.

When the dialog refuses

MessageWhyFix
Offline next to a machine, or "This machine went offline"The runner is not connected.Run demoflow runner start on the machine.
Update the CLIThe machine's CLI is older than this feature.Update demoflow there and restart its runner.
"This folder is outside the folders this machine allows"The folder is not inside an allowed folder, or a part of its path below it starts with a dot. The same message appears for a folder that does not exist.On that machine run demoflow runner allow <dir>. See Allowed folders.
"This folder has no demoflow.config.json"The folder has no config.Press Create config, or run demoflow init in it.
"The demoflow.config.json in this folder is not valid"The config does not pass validation.Fix it in the repository, then type the path again.
"This folder is already a project"The folder is registered.Press Open the existing project.
"This machine is busy" or "did not answer in time"The machine is working on another request.Try again in a moment.

Allowed folders

The machine decides which folders the website may name, not the website. The list is kept in allowed-roots.json next to credentials.json, and only you change it, on the machine. No request from the server reads or changes it. The runner reads the file for every request, so a change needs no restart.

By default the one allowed folder is your home directory. The website may name a folder inside an allowed folder, with two limits:

npx demoflow runner roots
npx demoflow runner allow ~/work
npx demoflow runner allow 'D:\Projects'
npx demoflow runner disallow ~/work
CommandWhat it does
demoflow runner rootsPrint the allowed folders, marking the default. --json prints one object. Exits 1 when the file is invalid.
demoflow runner allow <dir>Add an existing directory, by its real path. A relative path is resolved against the current folder. The first allow replaces the default home directory; allow the home directory again to keep it. At most 32 folders.
demoflow runner disallow <dir>Remove a folder from the list. Removing the last one allows nothing: the website may name no folder. It does not bring the default back.

On Windows use a drive path such as D:\Projects; network (UNC) and device paths are refused. A file that does not parse allows nothing until you fix or delete it, and roots says so.

What the website can and cannot see

For a folder inside the allowed folders the website can learn whether it holds a valid demoflow.config.json, its scenario names and its GitHub origin. The runner reads the remote from the repository's git file and never runs git. It can write the two Create config files into a folder that has no config, and register a folder that has one.

It cannot clone or download anything, overwrite a file, read any other file, or set devCommand: that stays yours, in the repository. A folder outside the allowed folders is refused with the same answer whether or not it exists.

A folder you added from the website stops being served for website-started runs if you disallow it, until you allow it again. A folder registered by a local run is not affected.

Delete a run's files

On a run's page, Delete video files removes the run's files from the machine that recorded it. It asks for confirmation, naming the machine. The button shows only while the run has video formats and is not deleted yet.

Status on the site

Signed in, open Machines in the app. Each paired machine is listed with its name and a status dot: online while its runner is connected, otherwise offline, with when and from which address it was last seen. You can rename a machine or revoke it there.