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.
- Already paired:
loginprints the account and machine name.--forcepairs again and revokes the old token first. demoflow logoutrevokes the token on the server, then deletes the file. If the server cannot be reached it still deletes the file, and the machine stays listed under Machines until you revoke it there.- The server is the website's origin.
--server <url>orDEMOFLOW_SERVERpicks it; the API is under/api. - The token is in
credentials.json, mode 0600, next to the globalconfig.json:~/.config/demoflow/(or$XDG_CONFIG_HOME/demoflow/),~/Library/Application Support/demoflow/, or%APPDATA%\demoflow\. It is never printed or logged. - The cloud learns the machine's name, OS and release, CLI version, and when the token was last used. Nothing else.
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.
| Command | What it does |
|---|---|
demoflow runner start | Start the runner. A second start prints the PID of the one running. |
demoflow runner stop | Stop it. logout stops it first. |
demoflow runner status | Show whether it runs, its connection, the server and whether autostart is installed. --json prints one object. |
demoflow runner logs | Print the runner's log. -f or --follow keeps printing. |
demoflow runner install | Start the runner at every login, and now. |
demoflow runner uninstall | Stop 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.
| OS | What it creates |
|---|---|
| Linux | a systemd user unit, ~/.config/systemd/user/demoflow-runner.service |
| macOS | a LaunchAgent, ~/Library/LaunchAgents/dev.demoflow.runner.plist |
| Windows | a 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
- A project can be run from the site only after this machine has reported a run
from its folder, or after you added the folder from the website (see Add a
project from the website). Run
demoflow runin the folder once, or add it there. A folder bound by hand is not enough. - The list holds every
*.demo.jsonunder the project'sdemoflow/folder, subfolders included, shown by name with its path. - The machine reads the list when the card opens or when you press Refresh, so a new file shows at once.
- Files that cannot be read as a scenario are skipped, and the card counts them. The list stops at the first 100 scenarios, sorted by path, and the card says so. Links are not followed.
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:
- The machine is offline. Run fails with a message to start the runner.
- Reporting is off on the machine:
CIis set to any non-empty value, orDEMOFLOW_NO_REPORT=1. The run's result has to reach the site, so an opt-out wins. - Another website-started run is in progress on that machine. A
demoflow runstarted in a terminal does not count.
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.
- A run still going after 15 minutes is stopped and ends Timed out.
- Cancel run shows only while the state is Running and asks for no confirmation. It stops the browser and the dev server, giving them up to 15 seconds.
- Stopping the runner (
demoflow runner stop, a signal, a shutdown) cancels a run in progress. - Lost contact means the site lost the machine's connection, or heard nothing for too long: 20 minutes after the start, 30 seconds after Cancel. The run may still finish and appear in the library.
When it ends
- When a run passes or fails, Open the run links to its page and the library shows it. If the run finished but its report did not reach the site, the card says so.
- A cancelled or timed-out run's folder is left as it was. The run is not
reported, so it never appears in the library and cannot be deleted from the
site. To remove it, delete
runs/<id>/in the DemoFlow home on the machine.
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.
- On Projects, press Add project.
- 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.
- Type the folder as an absolute path on that machine, for example
/home/you/my-app,/Users/you/my-apporC:\Users\you\my-app. After you stop typing, the machine looks at the folder. - The dialog shows what the machine found:
demoflow.config.jsonfound: the folder name, up to five scenario names with the count, and the GitHub link of theoriginremote when it is ongithub.com.- No config: press Create config. The machine writes
demoflow.config.jsonanddemoflow/first.demo.json, the same files asdemoflow init, and never overwrites a file that exists. The dialog names the files it wrote. Then setdevCommandandbaseUrlindemoflow.config.jsonin the repository: the website cannot set them. - A config that cannot be read: fix it in the repository, then type the path again.
- 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. - Press Add project. The project opens, and you can run its scenarios from the site.
When the dialog refuses
| Message | Why | Fix |
|---|---|---|
Offline next to a machine, or "This machine went offline" | The runner is not connected. | Run demoflow runner start on the machine. |
Update the CLI | The 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:
- No hidden folders. A folder whose path, below the allowed folder, has a
segment starting with
.is refused:~/.ssh,~/.config,~/.cache. Allow such a folder itself if you need it. - Real paths. The folder is resolved first; a symbolic link that leads outside the allowed folders is refused.
npx demoflow runner roots
npx demoflow runner allow ~/work
npx demoflow runner allow 'D:\Projects'
npx demoflow runner disallow ~/work
| Command | What it does |
|---|---|
demoflow runner roots | Print 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.
- Removed: the run's whole folder on the machine,
<home>/runs/<id>/, recursively. That is everything the run wrote there, not only the videos. Links inside it are removed as links. - Kept: the run's entry in the library: scenario, status, time, duration, formats, failed step, stages, files list and failure message. The library marks the run Files deleted, and the run page shows "Video files deleted" with the date.
- The machine must be online. Otherwise the button is disabled with "The machine is offline." A removed machine cannot delete.
- The machine deletes only a run it reported itself, and only a folder that is a
DemoFlow run folder:
runs/<id>/holding aresult.jsonof that run. Anything else is refused, and the page says the machine no longer has the files. - Deleting cannot be undone. The site records it only after the machine confirms. If the machine does not answer within 15 seconds, the page says so and you can try again.
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.