Desktop runner

A desktop runner is a computer you own — your laptop, a workstation, a spare box — that renders your ReelBolt videos instead of the cloud. You pair it to a workspace by approving a short code it shows, and from then on the work that can run on it runs on it. Rendering on your own machine uses no ReelBolt credits: the machine does the work, so you pay nothing to ReelBolt for that part. This page is about pairing, approving and revoking a device, the supported platforms, the workspace setting that decides when media work goes to a paired machine, installing and running the runner, its settings, and what data a runner ever sends anywhere.

Installing and running a ReelBolt desktop runner

There is nothing to download yet. The desktop runner is still being built, so the Desktop runner download page (/runner) currently shows its "not available yet" state and carries no installer, and the signed auto-update refuses to install anything because no release key is compiled in. When signed installers are published, that page will carry the downloads and their checksums. Until then, the working path is to run the binary from the source tree (developers, and early adopters):

# Build the headless daemon (or the tray shell, which embeds it).
cd runner && go build -o reelbolt-runner ./cmd/reelbolt-runner
./reelbolt-runner pair --name "My workstation"
./reelbolt-runner run

pair starts the pairing flow described below and stores the result; run then serves that workspace's jobs until stopped. doctor is the one to run first: it checks ffmpeg, the container runtime, the pinned runtime image and the container's egress posture, and prints the exact capability document the gateway will route on. status shows the local configuration and device state, and names the reason the machine is not working if the governor has paused it.

Where the runner lives on disk. Configuration is a text file you can edit, runner.json, in your OS user config directory (for example ~/.config/ReelBolt/runner.json on Linux, %AppData%\ReelBolt\runner.json on Windows), kept 0600. The device's private key lives in your OS keyring (or a 0600 file next to the configuration, with a warning, where the keyring is unreachable). Job scratch goes to your OS user cache directory and is deleted when the job ends. Nothing else of yours is read.

The container runtime choice. A machine that renders Remotion needs a container runtime: Docker (24 or newer) or Podman (5 or newer). Which one to run on a laptop:

• Podman — no daemon, no GUI. The machine's own engine does the isolation; rootless and VM modes are both supported. For most personal machines this is the cleaner choice.
• Docker Desktop — a full GUI and a VM under the hood. On Windows it is the only choice; on Linux it is a matter of taste. Note the licensing: Docker Desktop is free for personal use and for organisations of up to 250 employees; a larger organisation needs a Docker Desktop subscription. Podman has no such licence.
• WSL2 (Windows): run the runner and Podman inside the Linux distribution; the container's no-egress network is the isolation boundary, and WSL2's own networking is outside it.
• No runtime at all — the runner still works: it then offers only the ffmpeg work (video compiles and analysis extraction), as host processes, and cannot take Remotion renders.

The runtime's sandbox network is a --internal (no-egress) network the runner creates and verifies at startup: a live probe from inside a container to the public internet must fail. If it cannot be created, the machine degrades to the ffmpeg job types and says why, rather than failing to start.

Running it unattended. The runner drains on SIGTERM (waits drainSeconds, default 5, then closes), so a service manager is the normal supervisor: a Linux user systemd unit (so the keyring is reachable) or a Windows service. Run it under one if you want the signed auto-update to complete unattended — after an install the process stops and the manager restarts it on the new binary.

The runner's settings

The settings live in runner.json, the text file described above; reelbolt-runner status prints them, and the desktop tray's settings panel writes them.

Setting	Default	What it does
slots	1	How many jobs run at once. One is the safe default for a laptop; the desktop tray raises it deliberately. Capped at 16.
limits	4 GiB memory, 2 CPUs, 512 processes, 2 ffmpeg threads, below-normal priority, 8 GiB scratch	The per-job resource caps. Values larger than the machine are clamped and the clamp is shown by status; a value outside the sane range (memory under 256 MiB, more than 64 CPUs, a process count under 16) is refused at load.
schedule	always, any power, no windows	When the machine is willing to work: mode (always, idle, ac, windows), idleMinutes (default 5), windows ({days, start, end} — an end before its start wraps past midnight), onBattery (allow or pause). A machine the schedule has stopped drops its gateway connection entirely while it is idle.
updateChannel	stable	stable or beta.
autoUpdate	on	Off stops the background check; update --check/--apply still work.
updateIntervalHours	6 (max 168)	How often the background check runs.

Pausing and resuming. reelbolt-runner pause stops the machine taking new work; resume takes it again — one command, whoever placed it, without editing a file. status names the reason the machine is not working (user-active, on-battery, outside-window, paused), and the schedule line says when it next changes ("work resumes Mon 09:00"). A pause is never persisted: restarting the runner always comes back working.

Pausing from the dashboard: not yet. Nothing in the dashboard sends a pause to a paired machine — there is no pause button on the Runners page. To stop a machine, revoke it (see "Revoking a paired machine") or pause it on the machine itself.

What runs where, and what data leaves your machine

The division is the same in every section of this page, so it is stated once and relied on:

Runs on your machine — the media work: Remotion renders, video compiles (ffmpeg), and video analysis extraction. A machine with no container runtime runs only the ffmpeg half, as host processes.

Stays on the platform, never on the runner — the model calls and all AI thinking, transcription (ASR), on-screen description (vision) generation, object tracking, the derush pre-pass, input screening, and billing. These need provider credentials, and no message the runner ever receives carries one.

What leaves the machine, in total:

• The outbound WebSocket to the ReelBolt gateway (the runner never listens on a port), carrying the work — the job spec and the operations — and carrying back the results.
• The files a job needs: project sources and voiceover WAVs are staged to you from presigned object-store URLs (a GET), and the rendered output is published to a presigned URL (a PUT) in the job's own key space. Binary data never travels over the socket.
• The machine's name, OS, architecture and runner version, advertised at pairing and in the capability document. Nothing more: there is no telemetry, no geolocation, no IP-address lookup. The approval screen shows the raw address the pairing request came from and nothing else about it.

What is checked before it is used. A runner's output is untrusted by construction — the binary is controlled by its owner. Every runner-produced artifact is verified by the platform (size, duration, frame size, codec, frame rate, checksum) before it is promoted to the project's files; a rejected output fails the step. A step that ran on your machine is tagged in the run's step details, and the run page carries a chip when at least one of its steps did. The platform also re-checks the device's revocation state, so a revoked machine stops receiving work even before its next connection.

What the platform never gets to see: your other files, your keyring, anything outside the job's scratch directory (deleted when the job ends), and the container's network is a --internal no-egress network, so a job cannot phone home. The developer view of all of this is the desktop runner architecture doc and the runner protocol.

Troubleshooting a paired machine

The full error-message catalogue is on the Troubleshooting page; the runner's own entries are there. The four situations that need no page:

• The machine is not taking work, and status says why. Read the line: user-active (you are at the keyboard — in idle mode), on-battery, outside-window, or paused. resume clears an explicit pause without editing a file; a schedule gate names when it next changes, and the same line of status says resume is a no-op against it. If nothing responds at all, kill the process: a pause is never persisted, so a restart always comes back working.
• NO_RUNNER_ONLINE in a step's error. Your workspace is set to Only my machines and no paired machine was online and able to take the step. That choice never falls back to the cloud; start (or leave on) the machine, make sure it is paired to this workspace on Runners, and rerun the step. See the Troubleshooting page for the full entry.
• The machine shows nothing in the capability document for renders. doctor names it: no container runtime (Docker or Podman), the runtime is older than the minimum (Docker 24, Podman 5), or the --internal no-egress network could not be created. An ffmpeg-only machine cannot take Remotion renders; fix the runtime and doctor again.
• You revoked the machine and want it back. Revoke removes it from the list; to use it again, pair it afresh from the machine (reelbolt-runner pair). The device's private key is unchanged; only the workspace's record of it was deleted.

Supported platforms for a ReelBolt desktop runner

A runner is available for Windows (x64) and Linux (x64 or arm64). macOS is not supported. A device on any other platform is shown with the raw values it reported, not folded into a supported-looking label.

There is nothing to download yet. The desktop runner is still being built, so the Desktop runner download page (/runner) currently shows its "not available yet" state and carries no installer. When signed installers are published, that page will carry the downloads and their checksums. Until then, pairing is the part that works: a device that already has the runner shows a pairing code, and a workspace Owner or Admin approves it. How to build and run the binary, the container runtime choice (Docker Desktop's 250-employee licence, Podman, WSL2) and running it unattended are in Installing and running a ReelBolt desktop runner below on this page.

What a runner can do, and what it cannot

A paired machine runs the media work of a run: Remotion renders, video compiles, and video analysis extraction. Everything else — the model calls, the AI thinking, transcription, captioning, billing — stays on the platform. A machine that has no container runtime (Docker or Podman) can only do the ffmpeg work (compiling and extracting); a Remotion render needs a machine that reported a container runtime. Because a machine's own claims about what it can do are taken as given and then verified, the platform checks the output before it is used.

Pairing a machine in ReelBolt

Pairing starts on the device, not in the dashboard.

1. On the machine, start the ReelBolt runner. It shows a short pairing code (eight characters, like 7HQD-4M2R) and opens a link to ReelBolt's approval screen with that code in it.
2. In the workspace, open Runners → Pair a device (or type the code on the Pair a runner screen if you followed a bare link).
3. On the approval screen, check the code matches the one on the screen character for character, choose which workspace to pair the device into, and click Approve this device (or Deny to refuse it).

You can approve a device into a workspace where you are an Owner or Admin, or into your own Personal workspace. A device is paired into the workspace you pick, and only people in that workspace will see it.

Only approve a code shown on a device you own. Approving connects a computer to the workspace and lets it receive your media and render your videos. If someone sent you a code instead of a machine showing one, deny it — they are trying to attach their machine to your workspace. The screen also shows the machine's name, platform, version, when it was requested, its expiry, and the network address the request came from. It does not claim a location for that address: ReelBolt does not look one up.

When you approve, every Owner of that workspace is emailed about it, so a mistake is visible after the fact. A pairing code is short-lived; if it has expired, ask the device to show a fresh code.

What the approval screen deliberately does not show

The approval screen shows the device's name, platform, runner version, the request time, the expiry, and the raw network address of the request. It does not claim a city or location for that address — ReelBolt has no geolocation in this product, so nothing here is ever labelled with a place. If a code is unknown, expired, already used, or denied, and a workspace you are not a member of, are all one and the same answer: there is no matching pairing request. ReelBolt does not distinguish them, so it never tells you that a code you typed is valid but in someone else's workspace.

Revoking a paired machine in ReelBolt

On Runners, each paired machine has a Revoke action. Revoking disconnects it immediately and it receives no more work; it then disappears from the list — the workspace keeps no record of a revoked device here. To use the machine again, pair it afresh from the machine itself. A machine that is revoked does not show a "Revoked" badge; it is simply gone from the list, because the list is "what can run work right now".

The compute preference in ReelBolt

On Organization → Settings, under Where your work runs, an Owner or Admin chooses how media work is routed. This is a request, not a guarantee: the platform decides whether work is routed to a runner at all. Unless the ReelBolt compute fabric is switched on for the deployment (which is off by default, and off on a self-hosted install), this setting is never consulted and every step keeps running exactly where it runs today. Only media work is ever routed this way; everything else stays on the platform.

The four choices, in display order:

• Automatic (the default) — use a paired machine when one is online and can take the step; otherwise send the step to the ReelBolt cloud pool. Until a machine is paired this behaves exactly like "Never use my machines".
• Never use my machines — steps that can run on a runner never do. Eligible media work goes to the cloud pool instead, and pairing a machine changes nothing.
• Prefer my machines — use a paired machine whenever one is online and can take the step; fall back to the cloud pool when none is. A machine that is offline or busy is not waited for.
• Only my machines — nothing ever falls back. If no paired machine is online and able to take the step, the step fails with NO_RUNNER_ONLINE and the run stops there — no part of it is quietly billed to the cloud instead. Remotion renders need a machine that reported a container runtime, so an ffmpeg-only machine cannot take them; under this choice a render fails here rather than running anywhere else. This is the only choice that turns an offline machine into a failed run instead of a queued one.

Two things this page states plainly, because a settings screen that left them out would overclaim what the setting does:

• The cloud pool is not in service yet. No pool workers are enrolled, so a step that "falls back to the cloud pool" moves to a queue that nothing currently picks up. Until it is in service, work only finishes where a paired machine (or the platform itself) can run it. Do not rely on a fallback to the pool finishing your work today.
• "Only my machines" fails rather than falling back. If you choose it and your machine is offline, the step fails with NO_RUNNER_ONLINE. There is no silent cloud billing behind it.

What a runner does not pause from the dashboard

A paired machine can be paused and resumed from the machine's own command line (its control channel), but nothing in the dashboard sends a pause to it — there is no pause button on the Runners page. If you want a machine to stop taking work, revoke it (see above) or pause it on the machine itself. reelbolt-runner status names the reason it is not working, and resume clears an explicit hold without editing a file; the full setting names and defaults are in The runner's settings above on this page.

Related pages in ReelBolt

• Workspaces and teams — who can approve a device and the workspace it is paired into.
• Plans and credits — why work on your machine costs 0 credits.
• Troubleshooting — what NO_RUNNER_ONLINE means when a step fails, and the runner's other entries.
• Desktop runner (developer) — the module layout, the pairing protocol, the governor, the signed auto-update and what a release must supply.
• Compute fabric — the deployment side: the three targets, the selector's decision table, and how the fabric is turned on.
• The runner protocol — the wire contract a runner speaks.