Stoatworks Burrow user guide

Burrow installs, updates and removes the Stoatworks plugins, tools and Companion modules. One list, one click each, and it knows where every format goes on your machine.

Status at v0.2.4 — read this first.

Burrow has been tested thoroughly against real plugin downloads, but no plugin has yet been installed into a running Resolume, Resolve or After Effects through it. If you are about to use it before a show, don’t. Try it on a machine where a broken plugin folder would cost you nothing.

Updating Burrow itself is new in this version, and no copy has yet updated itself in the field — v0.2.3 is the first release that publishes an update for the next one to find. The download is signature-checked and refused if it does not match, and the .dmg and .pkg on this page are always there as the way that does not depend on any of it.

On Windows it can install FFGL plugins for Resolume, but not OpenFX or After Effects plugins — that part is not written yet, and it says so rather than half-working.

Applications and Companion modules are newer still, and no application has yet been installed into a real Applications folder through it, nor a module into a real Companion.

This is an AI-assisted project, directed and reviewed by a human author.

Installing Burrow

Download it from the project page, open the disk image and drag Burrow to your Applications folder. On Windows, run the installer.

Burrow is not required for anything. Every plugin can still be downloaded and installed by hand, exactly as before — Burrow only saves you doing it.

The tabs

The fleet is bigger than the video plugins now, so it is split by what a thing is for:

An effect you load into Resolume is a different errand from an application you launch, which is why the video ones are two tabs rather than one.

A number beside a tab is how many things in it need updating.

The first thing you’ll see

Burrow reads your plugin folders and shows you what you already have. It does not change anything until you tell it to.

Three headings:

• Up to date — you have it, and it’s current.
• Update available — you have it, and there’s a newer version.
• Not installed — available, and you don’t have it.

Each row shows which formats that plugin offers and what you have of each:

Beside the version, each row says how far along that project is — the same status the website gives it, in the same words:

Hover it for the same sentence. It is worth reading before a show: Field testing and In development mean what they say.

Doing a whole heading at once

Each heading carries the buttons for the plugins underneath it — Update all, Install all, Remove all — and each does exactly what the button on every row under it would do, for all of them. They appear only when there is more than one row to act on; with a single row, its own buttons are right there.

They act on what you can see. If you have typed in the search box, the count on the button is the number that survived the search, and those are the only ones that will be touched.

Install all and Remove all ask first, and say how much there is to download or what is about to be deleted. Update all does not — it only brings what you already chose up to date.

“Version unknown” is not a fault. On Windows a plugin is a bare .dll with no version in it, so Burrow genuinely cannot tell — it will offer to reinstall the current version rather than pretend to know. It also happens on macOS if you built a plugin yourself, or installed one before you had Burrow.

Keeping it current

Two buttons, above the list, because they do different jobs:

Rescan installed re-reads your plugin folders. It uses no network at all, so it works offline and is instant. Press it after installing or removing a plugin by hand — Burrow will notice without being told twice.

Check for updates fetches the plugin list. This is the one that finds new versions and new release notes, and the only one that goes anywhere.

Both say what they actually did — “2 new versions · 1 now needs updating”, or “Nothing changed” — and each shows when it last ran. If the version numbers you are looking at came from the copy that shipped with the app rather than a live check, the second button says not checked rather than a time.

Self-hosted

Some of this software is not installed at all — you run it.

Self-hosted holds two kinds of thing. The tools that ship a docker-compose.yml — flock, SRT Router, ATEM Overseer and the rest — and the browser tools that already run on the website. They are together because the question they raise is the same one: how do I run this?

A browser tool has nothing to install, so its row offers Open — the copy running on the website — and Source. Where it ships a compose file there is also Run your own, which shows you the file with Copy and Save buttons, so you can host it yourself instead of using ours.

Software you installed yourself

Burrow only manages what it installed. If you already had one of these applications or audio plugins on the machine, it will say not installed and offer you a download — because an application carries no name Burrow is looking for, so it genuinely cannot see it.

Settings → Software already on this machine → Look for it. Anything it recognises is listed with the file, the folder it is in, and the version. Press Claim and it tells you exactly what that means before you confirm: Burrow records the file as its own, will replace it when there is an update, and will delete it if you uninstall — the same as anything it installed itself.

It recognises things by the identifier inside the bundle, not by the filename, so renaming a file will not fool it and nothing that is not ours can be offered by accident. On Windows there is no identifier to read, so a claim there is your word for it, and Burrow says so on the row.

Release undoes a claim. It only makes Burrow forget the file; nothing is moved or deleted.

Updating Burrow itself

Those two buttons are about the plugins. Burrow’s own version is in Settings, under Burrow itself, with a Check for a new version button beside it.

If there is one, you get the version, the date and the release notes before anything is downloaded — and Install and restart does exactly that: it replaces this copy and reopens it. There is a Check when Burrow starts checkbox if you would rather be told at launch; it is off until you turn it on, and even then nothing is downloaded or installed without you pressing the button.

The download is checked against a signature made when the release was built. One that does not match is refused rather than installed.

Two things it will tell you instead of updating, and both are about where this copy of Burrow is:

• Running from the disk image. If you opened Burrow from inside the .dmg rather than dragging it to Applications, that disk is read-only and nothing can replace it. Drag it across and update from there.
• In a folder you cannot write to. Most likely /Applications on a machine where you are not an administrator. Burrow offers the download page instead.

Watching a plugin before you install it

Every plugin’s video is the picture at the left of its row. Click it and the video plays in the window.

The still images are part of the app rather than fetched from YouTube, so the list works offline and browsing plugins tells Google nothing. Only pressing play loads anything, and only for that one video.

It plays from the project’s own GitHub release — the same place its plugins come from — rather than being a YouTube embed. So there are no cookies, no ads, no suggested videos afterwards, and nobody outside this app and GitHub knows you watched it. There is an Open on YouTube button if you would rather watch it there.

The videos are about 11 MB each and start playing while they download. A couple of plugins have no copy in the app yet; clicking those opens YouTube in your browser instead.

Formats, and which ones you want

Most plugins come in more than one format. They are the same effect; the format is just which application loads it.

In Settings, tick the ones you use. Burrow starts with everything that needs no password ticked, and OpenFX and Adobe left off — those are the two that do.

Nothing has every format: a video plugin has no VST3 build and an audio plugin has no FFGL one, so ticking a format you never use costs nothing.

You can override this for a single plugin from its row — Formats… — if there’s one you want in Resolve but not Resolume, or the other way round. A row with its own choice shows a small custom formats label so you can see at a glance that it isn’t following your defaults.

Companion modules

A tool that has a Bitfocus Companion module shows it on the tool’s own row, below the buttons: Companion module v1.0.1, with Install beside it.

Companion has no fixed folder for modules that aren’t in its store. It reads the one you name in Settings → Developer modules path, so:

1. Install the module in Burrow. It goes to Documents/Companion Modules unless you tell Burrow otherwise, in Settings → Where things go.
2. Point Companion’s Developer modules path at that folder.
3. Restart Companion. It reads that folder once, when it starts.

Already have a modules folder? Change the path in Burrow’s Settings to yours and step 2 is done.

Applications

Applications install straight into your Applications folder — or, if you’re not an administrator on this machine, into your own ~/Applications, which Spotlight and Launchpad index just the same. Either way it never asks for a password.

On Windows they go into %LOCALAPPDATA%\Programs, and no Start-menu shortcut is created: Burrow places the program folder and doesn’t write anywhere else. Make a shortcut yourself if you want one.

Why it asks for your password

Two of the seven formats do, and the rest never do. FFGL plugins go into your own Documents folder, VST3s and Audio Units into your own ~/Library/Audio/Plug-Ins, Companion modules into a folder you chose, and applications as above — Burrow needs nothing special for any of those.

OpenFX and After Effects plugins are different. They go into folders that belong to the system:

OpenFX     macOS    /Library/OFX/Plugins
           Windows  C:\Program Files\Common Files\OFX\Plugins
Adobe      macOS    /Library/Application Support/Adobe/Common/Plug-ins/7.0/MediaCore
           Windows  C:\Program Files\Adobe\Common\Plug-ins\7.0\MediaCore

There’s no alternative: those are the only places those applications look. So Burrow asks for an administrator password — once, however many plugins are in the batch, and only when the batch actually needs it.

What happens behind that prompt is deliberately small. Burrow downloads, unpacks and checks everything first, with no special rights at all. Only then does it hand a separate helper program a list of files to move, and that helper can do nothing else: it has no way to reach the network, no way to open an archive, it will only write into the plugin folders above, and it will only delete a file it has itself just moved aside seconds earlier.

If you change your mind at the password prompt, nothing is lost. Anything in that batch that didn’t need a password is already installed, and the rest is reported as cancelled — not as an error.

/Library/OFX/Plugins is empty, and that’s normal

If you have DaVinci Resolve installed and Burrow tells you there are no OpenFX plugins, nothing is wrong. Resolve builds its own effects into the application rather than installing them as separate plugins, so that folder is usually empty — and often doesn’t exist at all — on a machine that uses Resolve every day.

Burrow will create it the first time you install an OpenFX plugin.

After installing

Restart the host. Resolume, Resolve and After Effects all read their plugin folders at startup. A plugin installed while they are running will not appear until they are restarted — in Resolume you may also need to rescan effects.

If a plugin still doesn’t appear, the likeliest cause on macOS is the quarantine flag, which makes Resolume skip a plugin silently rather than telling you. Burrow clears it on everything it installs, so this should not happen — but if it does, that’s worth reporting.

Trying a plugin before you install it

Press Try demo on any row. The plugin’s browser demo opens in a window, running the plugin’s own shaders — no installation, and nothing sent anywhere. Every demo is built into Burrow, so this works with no internet connection at all.

A few plugins have no demo: Cartridge needs an emulator core you supply yourself, and Amber and nib are too new. Those rows have no Try demo button rather than a button that does nothing.

Going back to an earlier version

If a new version misbehaves, Previous versions… on the row rolls it back. Burrow keeps the last few releases of every plugin, with a link to each one’s notes.

It only offers this for formats you already have installed — rolling back is a repair of something you have, not a way to acquire something you don’t.

Afterwards the plugin will show an update available, because it genuinely will. Restart your host to pick the change up.

Uninstalling

Uninstall on any row removes exactly what Burrow installed, and nothing else. That includes formats with an update waiting — a plugin you have not updated yet is still a plugin you have, and the button removes every format of it you have on disk. It says how many when there is more than one.

Your plugin folder almost certainly contains other things — plugins from other people, examples that came with an SDK, your own builds. Burrow does not look at them, does not list them, and cannot remove them. It only ever touches files it knows belong to a plugin in its own list.

If you installed a plugin by hand before you had Burrow, it can still remove it — but it will tell you exactly which files it is going to delete first.

What Burrow sends

There is no account, and no sign-in, because there is nothing to sign in to.

Burrow fetches one file — the plugin list from stoatworks-labs.com — and downloads plugin archives and project videos from GitHub. That is all. It sends no identifier, no list of what you have installed, and no usage data, and there is no third party involved anywhere. The demos run from inside the app and are blocked from making any network request at all.

Checking for a new Burrow is one more request, to Burrow’s own GitHub release, asking what the current version is. It happens when you press the button — and at startup as well, if you ticked that box. Nothing about your machine goes with the question.

The Send feedback button at the bottom of the window is the exception, and only when you press it: it sends what you type, plus the version of Burrow.

When it can’t reach the internet

Burrow works offline. It ships with a copy of the plugin list, so it can still show you everything and tell you what you have installed.

It will say so — a banner reading “Showing the plugin list that came with this app” — because version numbers from a list written weeks ago are not the same claim as version numbers checked a minute ago, and you should be able to tell which you are looking at. Installing still works; the downloads come from GitHub.

If something goes wrong

Errors appear on the row they belong to, with what actually failed, and stay there until you do something about them. Nothing disappears into a notification you might have looked away from.

A failed install leaves your plugin folder exactly as it was. Burrow never writes into a live plugin file: it unpacks and checks everything somewhere else first, and only swaps the finished result into place. If that swap fails partway through a plugin with more than one component, it puts back the ones it had already done.

For anything else, open an issue or use Send feedback in the app.