Installation

Latch 0.3.4 supports Linux, Windows, and Apple Silicon macOS. Official precompiled releases target x86_64 Linux, ARM64 Linux, x86_64 Windows, and ARM64 macOS. Windows ARM64, Intel macOS, and musl/Alpine binaries are not provided. The binary is named latch on Linux/macOS and latch.exe on Windows. See macOS qualification for the tested runtime and deployment baseline.

Install a binary¶

The installers download the latest stable GitHub Release, require its SHA256SUMS, and verify the archive before replacing an existing installation. Latest-release lookup follows GitHub's public release redirect, without using the GitHub API or requiring a token. The one-line commands work without pinning a version, including on networks that have exhausted the unauthenticated API quota. No root or administrator access is required. Review the scripts by downloading install.sh or install.ps1 first if you prefer to inspect them before running.

Linux or Apple Silicon macOS, from Bash:

curl -fsSL https://jinshuo-li.github.io/latch/install.sh | bash

Windows, from Windows PowerShell 5.1+ or PowerShell 7:

& { $ErrorActionPreference='Stop'; [Net.ServicePointManager]::SecurityProtocol=[Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12; irm -DisableKeepAlive https://jinshuo-li.github.io/latch/install.ps1 | iex; $env:Path="$env:LOCALAPPDATA\Programs\Latch\bin;$env:Path"; latch --version }

Linux automatically selects the x86_64 or ARM64 archive and installs to ~/.local/bin. Windows installs to %LOCALAPPDATA%\Programs\Latch\bin. The Windows one-liner enables TLS 1.2, adds the default install directory to the current terminal PATH and checks the installed version. The scripts do not change shell profiles or the persistent Windows PATH. On Linux, add export PATH="$HOME/.local/bin:$PATH" to your shell profile. On Windows, add the install directory to your user Path in Environment Variables and reopen your terminal. Close Latch before upgrading on Windows.

The current release provides all four platform archives listed below. The Unix installer also supports checksum-listed older versioned Linux archives. The glibc 2.35 baseline applies to new workflow builds; older Linux archives may require the builder’s newer glibc.

Pin a version or choose a directory¶

For a published release such as v0.3.4 (replace with an actual release tag):

curl -fsSL https://jinshuo-li.github.io/latch/install.sh | bash -s -- --version v0.3.4 --install-dir "$HOME/.local/bin"

Download the Windows script and pass its parameters:

Invoke-WebRequest https://jinshuo-li.github.io/latch/install.ps1 -OutFile install.ps1
./install.ps1 -Version v0.3.4 -InstallDir "$env:LOCALAPPDATA\Programs\Latch\bin"

Both scripts also accept LATCH_VERSION and LATCH_INSTALL_DIR environment variables. Omit the version or use latest for the latest stable release; prereleases must be pinned explicitly. Running the installer again upgrades the binary and preserves configuration and sessions in ~/.latch/.

Manual download¶

Download the archive for your platform and SHA256SUMS from the same release:

Verify the archive hash against its exact filename in SHA256SUMS, using sha256sum on Linux or Get-FileHash -Algorithm SHA256 on Windows, then extract latch / latch.exe to a directory on PATH. Archives also contain the MIT license, an example configuration, and build provenance in BUILD_INFO. Checksums detect corrupt or mismatched downloads; they are not a separate signature authenticating the publisher.

Runtime prerequisites¶

Linux requires Git, ripgrep (rg), and Bubblewrap (bwrap) on PATH, with unprivileged user namespaces enabled. Debian / Ubuntu:

sudo apt update && sudo apt install bubblewrap ripgrep git

Apple Silicon macOS requires /usr/bin/sandbox-exec, Git and ripgrep (brew install ripgrep). Source builds need Xcode Command Line Tools (xcode-select --install). No unsandboxed fallback is available.

Windows requires Git for Windows and ripgrep on PATH; for example with winget:

winget install --id Git.Git -e
winget install --id BurntSushi.ripgrep.MSVC -e

Reopen the terminal after installing these packages. The AppContainer sandbox runner and compatibility helper are embedded in latch.exe, with a statically linked C runtime. There is no unsandboxed fallback on either platform.

On Windows, use a focused NTFS checkout readable/modifiable by your account. Ordinary source reads and writes use scoped file mediation without changing source ACLs or requiring WRITE_DAC. Sensitive objects with broad/package read grants still require temporary journaled sealing; inability to seal fails closed. Outside-root hardlinks remain denied; use git clone --no-hardlinks for local clones. Scoped localhost networking requires explicit Network capability. An entire live home directory, physical power-loss recovery and hostile host races remain unqualified. See Windows boundary status.

First run¶

Open a terminal in your project and run latch. Use /setup to select a provider, credential source, and model. You supply your own model-provider credential. Then run:

latch doctor

This read-only preflight checks the sandbox, Git, ripgrep, configuration, state directory, profile, and credential without contacting the provider. It returns 0 when all checks pass, 1 for a runtime prerequisite failure, or 2 for a configuration/CLI error. Resume saved work with latch --resume --latest. See the README for interactive and machine CLI usage.

Build from source¶

Install stable Rust and a C toolchain. Linux also needs its runtime packages; Debian / Ubuntu builders can install build-essential. Windows builders need the x64 MSVC C++ Build Tools and Windows SDK in addition to Git and ripgrep. These compiler requirements apply to source builds, not binary installs.

git clone https://github.com/JinShuo-Li/latch.git
cd latch
cargo install --path crates/latch-cli --locked

Cargo installs to its configured bin directory (normally ~/.cargo/bin). For a local release build without installing, run cargo build --release --locked; the executable is in target/release/.

Uninstall¶

Close other Latch sessions, then run:

latch uninstall

The English menu offers:

1. Remove the program only (default)
2. Remove the program, data, and configuration (Warning: This cannot be undone.)
3. Cancel

Press Enter for option 1. It keeps configuration, credentials, and session history. Option 2 lists the data/configuration paths and requires typing DELETE before permanent removal. Entering anything else at that confirmation cancels. EOF also cancels, so a closed stdin never accepts the default automatically.

The program removes its running executable and byte-identical copies in standard installer/Cargo bin locations. Other versions, PATH entries, package-manager records, environment API keys, and workspace files are not modified. Windows uses the built-in Windows PowerShell to finish program removal after Latch exits; its completion message reports scheduling rather than claiming immediate removal. The installation directory must be writable by the current user.

Full removal covers ~/.latch, the platform's legacy Latch config/state/cache locations, and configured custom storage. --config <PATH> additionally selects that configuration and its custom storage. Custom storage with unrecognized files or shared home/workspace roots is refused before deletion; use option 1 and clean those locations manually. Programs installed inside their data directories also require program-only removal followed by manual storage cleanup. Symbolic links/junctions are removed without erasing their external targets. Protected Windows boundary recovery journals outside Latch storage are retained. Deletion errors can leave a partial cleanup and are reported before removing the program.

Regression tests use unique disposable executables. Native Windows CI checks deferred self-removal, and macOS CI checks a uniquely ad-hoc signed copy. Linux additionally exercises permanent removal of isolated new/legacy/custom storage.

Troubleshooting¶

• Download returns 404 / latest cannot be found: inspect the Releases page. The chosen tag must have both the platform asset and SHA256SUMS. Older releases may not use the new format. Pin a suitable release or build from source.
• Checksum is missing or mismatched: nothing is installed. Retry from the official release; report a persistent mismatch rather than bypassing validation.
• latch is not found: add the installation directory to PATH as described above. latch --version confirms which binary the shell resolves.
• GLIBC_2.xx not found: use a glibc 2.35+ distribution or compile from source on your host. The GNU archive is not compatible with Alpine's musl runtime.
• Bubblewrap / namespaces unavailable: run latch doctor; check your distro's user-namespace and AppArmor policy with your administrator. Latch refuses execution rather than weakening the sandbox.
• Windows replacement fails: close running Latch processes and check write permissions on the install directory, then rerun the installer.
• Windows script execution is restricted: the one-liner runs in the current PowerShell session. For downloaded files, inspect them and follow your organization's execution policy; no machine-wide policy change is required by Latch.