Install

The first release has not been published. The download links and the brew and choco commands below work once it is. Until then, build from source.

Downloads

Assets are on the releases page. Every asset has a .sha256 file, and SHA256SUMS lists them all.

There is no Intel macOS asset. The Linux executables are built for glibc and do not run on musl systems such as Alpine. An archive holds drift (drift.exe on Windows), LICENSE and a short README.txt.

shasum -a 256 -c --ignore-missing SHA256SUMS

The .deb and .rpm packages are desktop packages. Their install script needs the standard desktop directories, so they do not install on a headless server. Make the AppImage executable with chmod +x and run it, or pass --appimage-extract-and-run where FUSE is missing.

Unsigned Apps

The macOS and Windows installers are not signed with a developer certificate, so the first launch is blocked.

• macOS: Gatekeeper rejects the app. Open System Settings, Privacy and Security, and choose Open Anyway, or run xattr -dr com.apple.quarantine /Applications/Drift.app.
• Windows: SmartScreen shows "Windows protected your PC". Choose More info, then Run anyway.
• Android: the APK is signed with a debug key. Allow installs from your browser or file manager. An update over an older sideloaded build needs adb uninstall dev.gmitch215.drift first, because each build machine signs with its own key.

Homebrew

brew install gmitch215/tap/drift
brew install --cask gmitch215/tap/drift-studio

Use the full tap path, because other taps carry a formula named drift. The cask is Apple silicon only and clears the quarantine attribute after install.

Chocolatey

choco install drift
choco install drift-studio

Install Script

curl -fsSL https://raw.githubusercontent.com/gmitch215/Drift/master/install.sh | sh

On Windows, in PowerShell:

irm https://raw.githubusercontent.com/gmitch215/Drift/master/install.ps1 | iex

Each script finds your OS and architecture, downloads the archive and its .sha256 file from the latest release, checks the digest, runs the executable's --version and hands over to drift install. Flags go after sh -s -- (install.sh --dry-run from a saved copy): --user, --global, --dir, --no-modify-path and --dry-run. DRIFT_VERSION=1.0.0 pins a release. install.ps1 takes the same options as -User, -Global, -Dir, -NoModifyPath and -DryRun when saved with irm ... -OutFile install.ps1.

Drift Install

drift install copies the executable you are running to a directory on your path and records what it changed in a receipt. drift uninstall reverses exactly that.

drift install --dry-run

By default it installs for the current user, into ~/.local/bin (%LOCALAPPDATA%\Programs\Drift on Windows), and appends a marked block to the shell profiles that exist when the directory is not on PATH. Windows edits the user Path value in the registry. --global installs into /usr/local/bin (%ProgramFiles%\Drift), never calls sudo, and prints the command to run when the directory is not writable. --no-modify-path or DRIFT_NO_MODIFY_PATH=1 skips the path edit. The JVM build cannot install itself. See the usage guide for the full behavior.

Build from Source

Clone the repository. Every target builds from the Gradle wrapper, and the build downloads the JDK 21 toolchain if one is missing. A cold build downloads toolchains and dependencies and takes minutes.

The installers are built by release.yml with ./gradlew :studio:packageDmg :studio:packagePkg on macOS, :studio:packageDeb :studio:packageRpm :studio:packageAppImage on Linux and :studio:packageMsi :studio:packageExe on Windows (WiX Toolset). drift solve also needs Docker. Everything else runs without it.

The wasmJs target builds Studio for the browser (see Studio on the Web; ./gradlew :studio:wasmJsBrowserDistribution builds the bundle without staging it) and runs the common core tests under Node.

Command Line

Executables land in cli/build/bin/<target>/releaseExecutable/. The macOS executable is drift.kexe and the Windows one is drift.exe. On Linux, link linkReleaseExecutableLinuxX64 (or LinuxArm64) and point the alias at linuxX64/releaseExecutable/drift.kexe instead.

./gradlew :cli:linkReleaseExecutableMacosArm64
alias drift=$PWD/cli/build/bin/macosArm64/releaseExecutable/drift.kexe
drift --version

drift version 1.0.0 (macos)

On the JVM, ./gradlew :cli:jvmRun --args=--version prints drift version 1.0.0 (jvm), and any other command goes in --args.

The default path runs offline: drift capture and drift diagnose complete under docker run --network none.

Studio on the Desktop

./gradlew :studio:run

A window opens on the Home tab, with the Atlas, Investigation, Upgrade, Contract and Bisect views beside it.

Studio on the Web

drift serve serves the web build from a directory, read-only, on the loopback interface. :cli:stageStudio builds the Wasm distribution and copies it to cli/build/serve/studio.

./gradlew :cli:stageStudio
drift serve --dir cli/build/serve/studio

Open http://localhost:8080/, or http://localhost:8080/#atlas to start on the Atlas tab. The page title is "Drift Studio". --port 0 takes a free port, --cert and --key (or --mkcert with an existing mkcert CA) serve HTTPS on the JVM, macOS and Linux builds, and --domain adds names such as drift.local. Any static server works too: serve studio/build/dist/wasmJs/productionExecutable after ./gradlew :studio:wasmJsBrowserDistribution. The documentation site serves the same build at https://drift.gmitch215.dev/atlas/#atlas.

Android

Android and iOS builds are off by default so that a fresh clone needs only a JDK. Pass -Pdrift.mobile=true to turn them on. The Android build is a debug APK for an emulator or a device with USB debugging.

./gradlew -Pdrift.mobile=true :androidApp:assembleDebug
adb install -r androidApp/build/outputs/apk/debug/androidApp-debug.apk
adb shell am start -n dev.gmitch215.drift/dev.gmitch215.drift.android.MainActivity

./gradlew -Pdrift.mobile=true :androidApp:packageApk writes the release APK that the release workflow attaches, androidApp/build/distributions/drift-1.0.0-android.apk. It is signed with the debug key. Nothing is published to a store.

iOS Simulator

xcodebuild -project iosApp/iosApp.xcodeproj -target iosApp -configuration Debug \
  -sdk iphonesimulator ARCHS=arm64 ONLY_ACTIVE_ARCH=YES SYMROOT=build/xcode build
xcrun simctl list devices available
xcrun simctl boot <device-udid>
xcrun simctl install <device-udid> build/xcode/Debug-iphonesimulator/iosApp.app
xcrun simctl launch <device-udid> dev.gmitch215.drift

The Xcode project calls ./gradlew -Pdrift.mobile=true :studio:embedAndSignAppleFrameworkForXcode in a build phase. Its PATH adds /opt/homebrew/opt/openjdk/bin, /opt/homebrew/bin and /usr/local/bin; a JDK installed elsewhere needs the script phase edited. No signing or provisioning is involved, and the build targets the simulator only.

On Android and iOS, Studio replays the embedded Atlas transcripts and measures the live this-device probes. It does not sample the machine. The iOS host cannot start processes, so process probes are unavailable there. See Limits for what else differs by platform.