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 start runs on the machine 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. Run
demoflow runin the folder once. 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.
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.