Installation
One-Line Installer (Recommended)
Section titled “One-Line Installer (Recommended)”Open Terminal and run:
curl -fsSL https://raw.githubusercontent.com/Mallen220/TurtleTracer/main/install.sh | bashThe 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.
Manual Installation
Section titled “Manual Installation”- Download the latest
.dmgfrom Releases. - Mount the DMG and drag the app to your Applications folder.
- 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" - Launch the application.
Troubleshooting
Section titled “Troubleshooting”- "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".
Windows
Section titled “Windows”Microsoft Store (Recommended)
Section titled “Microsoft Store (Recommended)”Download from the Microsoft Store to receive automatic updates for stable releases.
PowerShell Installer
Section titled “PowerShell Installer”Open PowerShell and run:
irm https://raw.githubusercontent.com/Mallen220/TurtleTracer/main/install.ps1 | iexThis downloads the .exe, checks it against the published checksum, and installs it. Windows asks for administrator approval, because the installer is per-machine.
Manual Installation
Section titled “Manual Installation”- Download the latest
.exefrom Releases. - Run the installer.
- Note: If SmartScreen appears, click "More info" > "Run anyway".
One-Line Installer (Recommended)
Section titled “One-Line Installer (Recommended)”Open Terminal and run:
curl -fsSL https://raw.githubusercontent.com/Mallen220/TurtleTracer/main/install.sh | bashThe 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.
Manual Installation
Section titled “Manual Installation”- Download the
.deb(Debian/Ubuntu) or.AppImagefrom Releases. - For
.AppImage, make it executable:Terminal window chmod +x TurtleTracer*.AppImage./TurtleTracer*.AppImage - Ensure you have
libfuse2installed if using AppImage. If you can't install it, run withAPPIMAGE_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.
Installer Options
Section titled “Installer Options”Add options after bash -s --. For example, to install a specific version without being asked anything:
curl -fsSL https://raw.githubusercontent.com/Mallen220/TurtleTracer/main/install.sh | bash -s -- --version 2.4.0 --yes| Option | What it does |
|---|---|
--version X.Y.Z | Install that exact version (stable or pre-release). |
--stable / --prerelease | Install the newest stable release or the newest pre-release. |
--yes | Don't ask questions; use your options and the defaults. |
--dry-run | Show the plan and change nothing. |
--user | macOS: install into ~/Applications, no password. |
--format deb|appimage | Linux: choose the package type. |
--require-checksum | Refuse to install if the download can't be verified. |
--uninstall | Remove 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:
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/Mallen220/TurtleTracer/main/install.ps1))) -Version 2.4.0 -YesInstaller Troubleshooting
Section titled “Installer Troubleshooting”- Every download is verified. Releases publish a
SHA256SUMSfile, 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 setGITHUB_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.logon macOS and Linux,%TEMP%\turtle-tracer-install.logon Windows. Attach it to an issue.
Development Setup
Section titled “Development Setup”To build from source:
Prerequisites
Section titled “Prerequisites”- Node.js 18+
- Git
# Clone the repositorygit clone https://github.com/Mallen220/TurtleTracer.gitcd TurtleTracer
# Install dependenciesnpm install
# Start development servernpm run devBuilding
Section titled “Building”# Build for your current platformnpm run dist