Install

Tetravox ships as a desktop app for macOS, Linux and Windows.

Every release is built, smoke-tested and published by CI from a version tag. The artefacts on the Releases page are the official builds. Nothing here requires a toolchain; building from source is a developer topic.

Download

Pick the file for your machine. Names follow Tetravox-<version>-<os>-<arch>.<ext>.

Platform	File	Notes
macOS, Apple silicon	Tetravox-<version>-mac-arm64.dmg	M1 and later. Signed with a Developer ID and notarised by Apple.
macOS, Intel	Tetravox-<version>-mac-x64.dmg	Signed and notarised, as above.
Linux, x86-64	Tetravox-<version>-linux-x86_64.AppImage	Runs on any distribution; no install.
Linux, Debian / Ubuntu	Tetravox-<version>-linux-amd64.deb	Installs to /opt/Tetravox with a menu entry and file associations.
Linux, anything else	Tetravox-<version>-linux-x64.tar.gz	Unpack and run Tetravox from the folder.
Windows, x86-64	Tetravox-<version>-win-x64.exe	NSIS installer. Unsigned — see below.

macOS

1. Open the .dmg and drag Tetravox into Applications.
2. Launch it from Applications or Spotlight.

The releases are signed and notarised, so Gatekeeper opens them directly — no Terminal command is needed. If you ever see "Tetravox is damaged and can't be opened", you are running an unsigned local build (one produced by pnpm package without a certificate), not a release; clear the quarantine attribute once with xattr -dr com.apple.quarantine /Applications/Tetravox.app.

Linux

AppImage — make it executable once, then run it:

chmod +x Tetravox-*.AppImage
./Tetravox-*.AppImage

Debian / Ubuntu:

sudo apt install ./Tetravox-*-linux-amd64.deb

tar.gz — unpack anywhere and run ./Tetravox inside the folder.

If the app refuses to start with a message about chrome-sandbox, the kernel's unprivileged user namespaces are disabled on your system. Either fix the sandbox helper's ownership as the message says, or run with --no-sandbox. If the status bar reports a software renderer, the GPU was blocklisted by Chromium — Tetravox still runs, only slowly, and says so rather than pretending otherwise; chrome://gpu in any Chromium browser says why.

Windows

Run the installer. Windows SmartScreen will warn that the publisher is unknown, because the Windows build is not code-signed: choose More info → Run anyway. The installer adds a Start-menu entry and the file associations.

First launch

Drag files onto the window, press ⌘O / Ctrl+O, or name them on the command line:

Tetravox T1.nii.gz ernie.msh

Opening data adds it to what is already on screen; opening a saved scene (*.tetravox.json) replaces the scene. Tetravox registers itself for .nii, .nii.gz, .msh, .gii, .geo, .pos and .tetravox.json, so double-clicking one of those opens it too.

The Get started page walks through the window; the Guide covers every control.

Upgrading

The app checks for a new release a few seconds after launch (one small request to the Releases page — never a download) and says so with a notification; File ▸ Check for Updates… shows the release notes and installs it when you say so. On macOS, Windows and the Linux AppImage the update installs in place and the app restarts into the new version; a .deb or .tar.gz install is updated the way it was installed, so the app offers the Releases page instead. The launch check can be switched off in Settings ▸ Startup, updates are never downloaded or installed without your click, and any version can be skipped.

Installing by hand still works exactly as before — the same drag on macOS, the same installer on Windows, the same apt install on Debian. Settings (theme, capture defaults, the FreeSurfer subjects directory) are kept between versions either way; scenes are plain JSON files that any version reads. New versions are announced on the Releases page and in the changelog.

Requirements

• A GPU with WebGL2 — any machine from the last decade. The app checks for a working context at startup and says so if there is none, rather than opening a blank window.
• Memory in proportion to your data: a full SimNIBS head mesh is 100–200 MB on disk and several times that in memory. See Troubleshooting.
• No Python, no Node, no Rust. Those are only needed to build from source or to drive the app from a script.