Install the master
Unzip a folder and run it. There is no installer, no service to register, and nothing to install first — not Python, not FFmpeg, not a database.
The master is the machine that holds the queue and serves the web interface. Put it on a computer that stays on. It does not need to be your fastest machine, because it coordinates rather than encodes — though it can encode too if you also run a worker on it.
What is in the bundle#
The download unzips to a self-contained folder. Nothing outside it is touched.
| Item | What it is |
|---|---|
master.exe | The whole service in one file — API, web interface, scheduler, database driver. On macOS and Linux this is master. |
start.bat / start.sh | The launcher. Loads your settings, runs database migrations, then starts the service. |
bin/ | Tested ffmpeg and ffprobe builds, plus oiiotool and ociobakelut for EXR work. Put on PATH ahead of anything installed on the host. |
master.env.example | Configuration template. Copy to master.env, or let the setup dialog write one. |
share/ocio/ | ACES studio config used by the colour-managed EXR paths. |
THIRD_PARTY_LICENSES/ | FFmpeg redistribution paperwork. Keep it with the bundle. |
Run it#
A local disk, an external drive, a USB stick. It is a portable install — the folder holds the program, its settings and its database together, so moving the folder moves the installation.
Avoid a path that a sync client controls, such as OneDrive or Dropbox. The database is written continuously while the master runs, and a sync client fighting it will corrupt it.
On Windows, double-click start.bat. On macOS or Linux, run the launcher from a terminal in that folder.
$ bash start.shThe first time you run it, with no master.env present, a setup window opens and asks for an administrator password, the ports to listen on, and generates the signing secret for you. It writes master.env and the launcher continues.
Pick a real password here. This account can see and control every job on the fleet.
Once the console reports the service is listening, open a browser on the same machine and sign in with the administrator account you just set.
http://localhost:7443The master is running. It has no workers yet, so it cannot encode anything — that is the next page. If you want to encode on this same machine, you still need to run a worker on it.
Ports#
The master listens on three. You need to know these to let workers reach it and to open the right holes in a firewall.
| Port | Protocol | Used for | Who connects |
|---|---|---|---|
7443 | TCP | Web interface, REST API, live progress | Your browser |
50051 | TCP | Worker control channel | Every worker |
5353 | UDP | Automatic discovery on the LAN | Workers looking for the master |
Let workers through the firewall#
On Windows, the first time something tries to reach the master from another machine it will be blocked silently. The master ships a command that adds the rules for you. It prompts for elevation and is safe to run more than once.
> master.exe firewall-installOn macOS and Linux, open TCP 7443 and 50051, and UDP 5353 if you want automatic discovery, using whatever firewall the host runs.
Configuring by hand instead#
If you would rather not use the dialog — you are setting up over SSH, or scripting a deployment — copy the template before the first run and edit it.
$ cp master.env.example master.env
$ openssl rand -hex 32 # paste into TRNSCODE_JWT_SECRETAt minimum, set these three:
Signs the session tokens the web interface issues. Use 32 or more random bytes. Anyone who knows this value can mint a valid administrator session.
The bootstrap administrator password, used only to create the account on first run. Change it from the shipped default.
A shared secret every worker must present to join. Leave it empty and any machine that can reach the port may register — acceptable on an isolated lab network, not on a shared office LAN.
Master settings use a bare TRNSCODE_ prefix. Worker settings use TRNSCODE_WORKER_. The difference is deliberate, and mixing them up is the most common configuration mistake — a worker setting placed in master.env is ignored without warning.
Where your data lives#
Everything stays inside the bundle folder. There is no hidden application-support directory and no registry state.
| Path | Contents |
|---|---|
master.env | Your settings, including the signing secret. Treat it as a credential. |
data/trnscode.db | Jobs, chunks, workers, presets, users, audit history. This is the thing to back up. |
To back the database up while the master is running, use the built-in command rather than copying the file — a live SQLite database copied with a file manager can be captured mid-write.
$ master backup --out ./backups/2026-07-25.dbIf you lose the admin password#
Stop the master and reset it from the same folder. You do not need to delete the database or lose your job history.
$ master reset-admin-password "a new password"