Install on macOS

On a Mac, Tatolab is an app. Opening it starts the runtime if it isn’t running, the way Docker Desktop does, and registers it as a login item so it comes back after a restart.

Requirements

• A Mac with Apple silicon (M1 or later). Intel Macs aren’t supported.
• macOS 15 Sequoia or later.
• An administrator password, once, for the first launch.

You don’t need a Vulkan SDK or any GPU drivers: the app carries everything the runtime needs.

Install with Homebrew

brew install --cask tatolab/tap/tatolab
open -a Tatolab

The first command puts Tatolab in Applications, and the second opens it for the first launch.

Or download the app

1. Download the .dmg from the latest release.
2. Open it and drag Tatolab into Applications.
3. Open Tatolab from Applications.

The first launch

1. The app is signed and notarized by Apple. macOS asks you to confirm opening an app downloaded from the internet the first time; click Open.

2. Enter your administrator password when asked. This happens once, and does two things:

   • links tatolab into /usr/local/bin, so you can use it in Terminal;
   • creates /Library/Application Support/Tatolab/, which the runtime uses to make sure only one runtime runs on the Mac.

   If you cancel, the menu shows Setup unfinished, and Set Up Tatolab… in the same menu asks again.

3. The app starts the runtime and adds it to your login items. If macOS wants you to approve the login item, the app opens System Settings → General → Login Items & Extensions; switch Tatolab on there.

Tatolab now lives in your menu bar. Its menu has a status line, such as Runtime running · 2 streams, the Run Tatolab switch, and Quit Tatolab.

Check that it works

Open a new Terminal window and run:

tatolab streams

Output

No streams in this runtime.

You’re ready for the quickstart. If you don’t have uv yet, set up Python first.

Camera and microphone access

The first time a stream uses the camera or the microphone, macOS asks whether Tatolab may use it. The prompt names Tatolab, and macOS remembers your answer across updates. The stream starts either way: frames or audio begin as soon as you click Allow.

If you clicked Don’t Allow, turn access back on in System Settings → Privacy & Security → Camera (or Microphone), and switch on Tatolab.

Starting and stopping the runtime

• The runtime starts when you log in, and starts again by itself if it crashes. Streams you keep with tatolab run -d come back with it.
• Quit Tatolab closes the menu bar app. The runtime keeps running, and so do your streams.
• To stop the runtime, switch off Run Tatolab in the app’s menu. It stays off until you switch it back on, even if you reopen the app or restart the Mac.

Update

• Homebrew: brew upgrade --cask tatolab
• Download: download the new .dmg and drag Tatolab into Applications, replacing the old copy.

After updating, open Tatolab. A Homebrew upgrade stops the runtime until the app opens again, and a copy dragged over the old one leaves the old runtime running until you switch Run Tatolab off and on. The new version then loads the streams you kept. If one can’t load under the new version, tatolab streams lists it as failed and says why; running tatolab run -d in its project loads it fresh.

Uninstall

Homebrew: brew uninstall --cask tatolab stops the runtime, quits the app, and removes both the app and the tatolab command. Add --zap to also delete the app’s settings and the record of the streams the runtime kept.

Download:

1. Switch off Run Tatolab, which stops the runtime, then choose Quit Tatolab.
2. Drag Tatolab from Applications to the Trash.
3. Remove the command-line link: sudo rm /usr/local/bin/tatolab.
4. To forget the streams the runtime kept, delete ~/Library/Application Support/Tatolab/.

Either way, the lock folder stays until you remove it: sudo rm -r "/Library/Application Support/Tatolab". Your stream projects aren’t touched.

Troubleshooting

• tatolab: command not found. Open a new Terminal window after the first launch. If it still isn’t found, check that /usr/local/bin is on your PATH (echo $PATH), and that the first launch’s administrator prompt completed.
• no runtime is running on this machine. Open Tatolab and check that Run Tatolab is on.
• The menu says Needs approval in Login Items. macOS is waiting for you to allow the runtime. Switch Tatolab on in System Settings → General → Login Items & Extensions; the app opens that page for you once each time it starts.
• The menu says Setup unfinished. The administrator prompt was cancelled or failed. Choose Set Up Tatolab… in the menu to try again.
• The window opens but stays black. Check camera access in System Settings → Privacy & Security → Camera. A stream with no camera to use can still run with TestPatternSource; try tatolab new test-bars --test-pattern.

More fixes are in Troubleshooting.