Install on Linux

On Linux, one command installs Tatolab for your user and registers the runtime as a systemd user service, the way rootless Docker runs its daemon. You don’t need root.

Requirements

• An x86_64 machine (64-bit Intel or AMD). ARM Linux isn’t supported yet.
• glibc 2.28 or later. Ubuntu 20.04, Debian 10, RHEL 8 and their successors all qualify. Check with ldd --version.
• A GPU with a Vulkan driver. We test on NVIDIA’s proprietary driver. AMD and Intel GPUs with Mesa’s Vulkan drivers (mesa-vulkan-drivers on Debian and Ubuntu) should work, but we haven’t validated them. Check yours with vulkaninfo --summary, from the vulkan-tools package.
• systemd, for the always-on service. Most desktop and server distributions have it.

The H.264 and H.265 nodes also need a GPU and driver with Vulkan Video encode and decode support. The rest of Tatolab doesn’t.

Install

curl -fsSL https://get.tatolab.com/install.sh | sh

If you’d rather read the script before running it:

curl -fsSL https://get.tatolab.com/install.sh -o install.sh
less install.sh
sh install.sh

The script:

1. Downloads the latest runtime from get.tatolab.com and checks its SHA-256 checksum.
2. Unpacks it into ~/.local/share/tatolab/<version>/ and points ~/.local/share/tatolab/current at it.
3. Links tatolab and tatolabd into ~/.local/bin.
4. Writes a systemd user service, ~/.config/systemd/user/tatolabd.service, enables it, and starts it. A second, small unit restarts the runtime when you log in to a desktop, if it started without one; see Windows and displays.
5. Offers to turn on lingering with loginctl enable-linger, so the runtime runs even when you aren’t logged in. Say yes on a server, or on any machine you reach over ssh.

Command not found?

If your shell can’t find tatolab afterwards, first check that the install ran: ls ~/.local/bin/tatolab. If the file is there, ~/.local/bin isn’t on your PATH. Add it, then open a new terminal:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

Use ~/.zshrc instead if your shell is zsh.

Check that it works

tatolab streams

Output

No streams in this runtime.

You can also ask systemd:

systemctl --user status tatolabd

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

Living with the service

• The runtime starts when you log in (or at boot, with lingering on), and systemd restarts it if it crashes. Streams you keep with tatolab run -d come back with it.
• To see what the runtime itself printed: journalctl --user -u tatolabd -f. For a stream’s own logs, use tatolab logs --stream <name>.
• To stop, start or restart it: systemctl --user stop tatolabd, start or restart. Stopping the runtime stops every stream on it; kept streams load again when it starts.

Windows and displays

A DisplayWindow needs a desktop session to draw on. The runtime picks up your desktop’s display (DISPLAY or WAYLAND_DISPLAY) when it starts. If it started before you logged in to a desktop, at boot with lingering on for example, logging in restarts it so windows can open. A restart stops the streams on the runtime, and the kept ones load again.

A window that can’t open logs DisplayWindow: no window — running degraded with the reason, and keeps reading its input, so the rest of the stream runs. A machine with no desktop, such as a server, has nowhere to open a window: record to a file, publish over WebRTC, or look at frames with tatolab exchange instead.

Update

Run the install command again:

curl -fsSL https://get.tatolab.com/install.sh | sh

It installs the newest release, switches current to it, and restarts the service. Once the new version is running, it deletes the old one. If the new version’s service doesn’t start, it puts the old version back and says so. The runtime loads the streams you kept again when it starts. 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.

To install a particular version instead of the newest, set TATOLAB_INSTALL_VERSION to its number, in place of X.Y.Z:

curl -fsSL https://get.tatolab.com/install.sh | TATOLAB_INSTALL_VERSION=X.Y.Z sh

Uninstall

curl -fsSL https://get.tatolab.com/install.sh | sh -s -- --uninstall

This stops and removes the service and deletes the installed files. It leaves your stream projects, and the runtime’s state folder, ~/.local/state/tatolab/, with the streams you kept and the runtime’s own log. Delete the state folder yourself if you want a clean slate. If you turned lingering on and no longer want it, run loginctl disable-linger.

No systemd? Containers?

Where there’s no systemd user session, as in most containers, the script still installs tatolab and tatolabd, but can’t register a service, and says so. Run the runtime yourself: tatolabd in a terminal, or as the container’s entrypoint. It runs in the foreground until you stop it with Ctrl-C or a signal.

Troubleshooting

• No usable Vulkan driver (ICD) was found or No Vulkan loader library could be opened. Install your GPU’s Vulkan driver (the proprietary NVIDIA driver, or mesa-vulkan-drivers for AMD and Intel) and the loader (libvulkan1), then check that vulkaninfo runs.
• another runtime holds this machine. A tatolabd is already running, perhaps one you started in a terminal before installing. The message names its user, process ID and executable. Stop that one, then systemctl --user restart tatolabd.
• The service stops when you log out. Turn on lingering: loginctl enable-linger.

More fixes are in Troubleshooting.