Install

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

Three ways in: Homebrew, a release download, or building from source. All end up with Tailscreen.app.

Homebrew 

brew install middle-management/tap/tailscreen

The cask drops Tailscreen.app into /Applications — the same signed, notarized universal binary the release page hosts. The formula lives in middle-management/homebrew-tap and is bumped automatically on each release.

To upgrade later:

brew upgrade --cask tailscreen

To remove:

brew uninstall --cask tailscreen

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, codesigned and notarized by CI. 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 — no Xcode project, none planned. Builds go through the top-level Makefile, which sets PKG_CONFIG_PATH so SwiftPM can find the C library it links 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. Build-time only: Go compiles Tailscale’s source into libtailscale.a for the Swift code to link against. Uninstall it afterwards and the app keeps working.

Clone — with submodules

Tailscale’s C library lives in a submodule under TailscaleKitPackage/upstream/libtailscale. Forget the recursive clone and the build fails 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 failure is bare swift build: it fails to link because libtailscale.a doesn’t exist yet. Run make build (or at least make tailscale) once; after that, swift build works fine.

Permissions

The first time you hit “Start Sharing”, macOS pops a Screen Recording prompt. Approve it in System Settings → Privacy & Security → Screen Recording, then quit and relaunch — macOS only applies the new permission to a restarted process.

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.