Install

1. From a release
2. From source
   1. What you need installed
   2. Clone — with submodules
   3. Build
   4. Run
   5. Release build and install
3. Always start with make
4. Permissions
5. Uninstall

There are two ways in: grab a release, or build from source. Both end up with Tailscreen.app.

From a release

Go to the Releases page, download Tailscreen-<version>-macOS.zip, unzip, drag to /Applications. Done.

The release zip is a universal binary (arm64 + x86_64), built and notarized by release.yml on a macos-15 runner. If the build secrets aren’t configured (forks, dry runs), you’ll get an unsigned .app instead — Gatekeeper will yell at you the first time you open it.

From source

The project is Swift Package Manager only. There is no Xcode project and there is no plan for one. Builds go through the top-level Makefile because that’s where PKG_CONFIG_PATH gets set so SwiftPM can find the C library it needs to link against.

What you need installed

• macOS 15.0 (Sequoia) or later.
• Swift 6.0 toolchain. Xcode 16+ ships it; alternatively swift.org has standalone installers.
• Go 1.21 or newer. This is a build-time dependency, not a runtime one. The Go compiler turns Tailscale’s source into libtailscale.a, which the Swift code then links against. Once you’ve built, you can uninstall Go and the app keeps working.

Clone — with submodules

Tailscale’s C library lives in a submodule under TailscaleKitPackage/upstream/libtailscale. If you forget the recursive clone, the build will fail with a confusing missing-headers error. So:

git clone --recurse-submodules https://github.com/middle-management/tailscreen.git

Or, if you’ve already done a regular clone:

git submodule update --init --recursive

Build

make build

This compiles libtailscale.a from the Go submodule, applies the patches under TailscaleKitPackage/Patches/ to the upstream Swift sources (more on that in Contributing), builds the TailscaleKit wrapper, and finally builds the app. First build pulls Go modules, so it needs internet.

Run

make run

Or build once and run the binary directly:

.build/debug/Tailscreen

Release build and install

make release           # → .build/release/Tailscreen
make install           # release + copy to ~/bin/Tailscreen

Always start with make

The most common first-time build failure is running bare swift build. It fails to link because libtailscale.a doesn’t exist yet — the Go toolchain hasn’t been invoked. Run make build (or at least make tailscale) once first. After that, swift build works fine for the rest of the build tree.

Permissions

The first time you hit “Start Sharing”, macOS will pop up a Screen Recording prompt. Approve it in System Settings → Privacy & Security → Screen Recording, then quit Tailscreen and relaunch. macOS will not pick up the new permission until the process restarts.

Uninstall

Quit Tailscreen, drag Tailscreen.app to the trash. If you want to nuke the ephemeral-node state too:

rm -rf ~/Library/Application\ Support/Tailscreen

That’s it. There’s no installer, no daemon, no LaunchAgent.