Skip to content

Installation

Open Terminal and run:

Terminal window
curl -fsSL https://raw.githubusercontent.com/Mallen220/TurtleTracer/main/install.sh | bash

The installer asks which version you want and shows a plan before it changes anything. It checks the download against the published checksum, and installs into /Applications (it asks for your password), or into ~/Applications if you add --user. See Installer Options for the full list.

  1. Download the latest .dmg from Releases.
  2. Mount the DMG and drag the app to your Applications folder.
  3. Important: Run the following command in Terminal to clear the quarantine attribute (prevents "App is damaged" errors):
    Terminal window
    sudo xattr -rd com.apple.quarantine "/Applications/TurtleTracer.app"
  4. Launch the application.
  • "App is damaged" / Can't Open: Run the quarantine fix command mentioned above.
  • Gatekeeper: If the app is blocked, go to System Settings > Privacy & Security and click "Open Anyway".

Download from the Microsoft Store to receive automatic updates for stable releases.

Open PowerShell and run:

Terminal window
irm https://raw.githubusercontent.com/Mallen220/TurtleTracer/main/install.ps1 | iex

This downloads the .exe, checks it against the published checksum, and installs it. Windows asks for administrator approval, because the installer is per-machine.

  1. Download the latest .exe from Releases.
  2. Run the installer.
  3. Note: If SmartScreen appears, click "More info" > "Run anyway".

Open Terminal and run:

Terminal window
curl -fsSL https://raw.githubusercontent.com/Mallen220/TurtleTracer/main/install.sh | bash

The installer detects your distribution and CPU. On Debian and Ubuntu it installs the .deb with apt (this needs sudo). On other distributions, or if you don't have sudo, it installs the AppImage into ~/Applications and adds a menu entry. If libfuse2 is missing, it sets the launcher to unpack the AppImage on start instead of failing.

  1. Download the .deb (Debian/Ubuntu) or .AppImage from Releases.
  2. For .AppImage, make it executable:
    Terminal window
    chmod +x TurtleTracer*.AppImage
    ./TurtleTracer*.AppImage
  3. Ensure you have libfuse2 installed if using AppImage. If you can't install it, run with APPIMAGE_EXTRACT_AND_RUN=1 ./TurtleTracer*.AppImage.

If the app won't start on Linux with a sandbox error, run it with --no-sandbox. Turtle Tracer turns Chromium's sandbox off by itself when your system can't support it, such as AppImages on Ubuntu 23.10 and newer.

Add options after bash -s --. For example, to install a specific version without being asked anything:

Terminal window
curl -fsSL https://raw.githubusercontent.com/Mallen220/TurtleTracer/main/install.sh | bash -s -- --version 2.4.0 --yes
OptionWhat it does
--version X.Y.ZInstall that exact version (stable or pre-release).
--stable / --prereleaseInstall the newest stable release or the newest pre-release.
--yesDon't ask questions; use your options and the defaults.
--dry-runShow the plan and change nothing.
--usermacOS: install into ~/Applications, no password.
--format deb|appimageLinux: choose the package type.
--require-checksumRefuse to install if the download can't be verified.
--uninstallRemove Turtle Tracer. Your projects and settings are kept.

On Windows, set $env:TT_VERSION = '2.4.0' before running the command. You can also run the script as a script block with the parameters -Version, -Stable, -Prerelease, -Yes, -DryRun, -RequireChecksum, and -Uninstall:

Terminal window
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/Mallen220/TurtleTracer/main/install.ps1))) -Version 2.4.0 -Yes
  • Every download is verified. Releases publish a SHA256SUMS file, and the installers refuse a file that doesn't match. Releases from before checksums existed install with a warning instead.
  • "GitHub's rate limit was reached." GitHub limits anonymous lookups per network. The installer falls back to lookups that aren't limited and tells you what it couldn't check. You can also name a version with --version, or set GITHUB_TOKEN.
  • It can't find a file for your system. The message lists what the release does contain. Builds exist for 64-bit Intel/AMD and ARM on macOS and Linux (glibc distributions, so not Alpine) and for 64-bit Windows.
  • Something failed. The installer saves a log: ~/turtle-tracer-install.log on macOS and Linux, %TEMP%\turtle-tracer-install.log on Windows. Attach it to an issue.

To build from source:

  • Node.js 18+
  • Git
Terminal window
# Clone the repository
git clone https://github.com/Mallen220/TurtleTracer.git
cd TurtleTracer
# Install dependencies
npm install
# Start development server
npm run dev
Terminal window
# Build for your current platform
npm run dist