zero/docs/INSTALL.md

Installing Zero

Zero is distributed as:

• an npm package, @gitlawb/zero
• release archives on GitHub Releases
• source builds with Go 1.25+

The npm package and install scripts download a platform-specific release archive. They require a published GitHub Release for the requested version.

npm

npm install -g @gitlawb/zero
zero

The package supports Linux, macOS, and Windows on x64 and arm64. It installs the zero command and downloads the matching release binary during postinstall.

Requirements:

• Node.js 18+
• network access to npm and GitHub Releases

Bun

Bun is "default-secure" and does not run lifecycle scripts of installed dependencies (only the installing project's own scripts), so the postinstall that fetches the Zero binary is silently skipped. The first run then fails with No native binary found next to the npm wrapper.

The simplest fix is to trust the package after installing, which runs the blocked postinstall. This works for project and global installs:

# project install
bun add @gitlawb/zero
bun pm trust @gitlawb/zero

# global install
bun add -g @gitlawb/zero
bun pm -g trust @gitlawb/zero

bun pm untrusted (or bun pm -g untrusted) lists the blocked postinstalls if you want to inspect before trusting.

Alternatively, allow the postinstall to run at install time by adding the package to your project's trustedDependencies before installing:

{
  "trustedDependencies": ["@gitlawb/zero"]
}

bun add @gitlawb/zero

On Bun versions that do not have bun pm trust, run the installer manually after installing:

node node_modules/@gitlawb/zero/scripts/postinstall.mjs

Reference: https://bun.sh/docs/pm/lifecycle

Linux And macOS Script

Install the latest release:

curl -fsSL https://raw.githubusercontent.com/Gitlawb/zero/main/scripts/install.sh | bash

From a checkout:

scripts/install.sh

Install a specific version:

ZERO_VERSION=0.1.0 scripts/install.sh
scripts/install.sh --version 0.1.0

Install somewhere else:

ZERO_INSTALL_DIR="$HOME/bin" scripts/install.sh
scripts/install.sh --install-dir "$HOME/bin"

Defaults:

• Repository: Gitlawb/zero
• Version: latest GitHub release
• Install path: ~/.local/bin/zero

Requirements: Bash, curl or wget, tar, and shasum or sha256sum.

Windows PowerShell Script

Install the latest release:

irm https://raw.githubusercontent.com/Gitlawb/zero/main/scripts/install.ps1 | iex

From a checkout:

powershell -ExecutionPolicy Bypass -File scripts/install.ps1

Install a specific version:

powershell -ExecutionPolicy Bypass -File scripts/install.ps1 -Version 0.1.0

Install somewhere else:

powershell -ExecutionPolicy Bypass -File scripts/install.ps1 -InstallDir "$env:USERPROFILE\bin"

Defaults:

• Repository: Gitlawb/zero
• Version: latest GitHub release
• Install path: %LOCALAPPDATA%\zero\bin\zero.exe

From Source

git clone https://github.com/Gitlawb/zero.git
cd zero
go run ./cmd/zero

Build a local binary:

go build -o zero ./cmd/zero

Source builds require Go 1.25+.

Sandbox Helpers For Source Builds

Release archives include the platform sandbox helpers. If you build directly from source, build the helpers you need:

Linux:

go build -o zero ./cmd/zero
go build -o zero-linux-sandbox ./cmd/zero-linux-sandbox
go build -o zero-seccomp ./cmd/zero-seccomp

Put zero and zero-linux-sandbox in the same directory on PATH, for example ~/.local/bin. zero-seccomp is kept as a compatibility wrapper; the sandbox helper applies the Unix-socket filter itself when that sandbox option is enabled. Linux native sandboxing also requires Bubblewrap to be installed.

macOS uses the system sandbox and does not need an extra helper binary.

Termux (Android)

Zero can run natively on Android via Termux. Build with GOOS=android to avoid the faccessat2 syscall that is blocked by Samsung's seccomp filter on Android:

# Install Go in Termux
pkg install golang

# Build Zero for Android
git clone https://github.com/Gitlawb/zero.git
cd zero
CGO_ENABLED=0 GOOS=android GOARCH=arm64 go build -ldflags="-s -w" -o zero ./cmd/zero

# Move into PATH
mv zero ~/.local/bin/

Why GOOS=android? Go 1.26+ detects runtime.GOOS == "android" and skips the faccessat2 syscall inside os/exec.findExecutable, falling back to permission-bit checks. Without this flag, Android's seccomp sends SIGSYS and kills the process whenever Zero looks up a binary on PATH (git, sh, etc.).

DNS. Android does not expose /etc/resolv.conf. Go's pure-Go DNS resolver needs one. Use proot to bind-mount Termux's resolver config:

pkg install proot
proot -b "$PREFIX/etc/resolv.conf:/etc/resolv.conf" zero

Create a wrapper at ~/.local/bin/zero to avoid typing proot every time:

#!/data/data/com.termux/files/usr/bin/bash
exec proot -b "$PREFIX/etc/resolv.conf:/etc/resolv.conf" ~/.local/bin/zero.bin "$@"

Scroll. On native Termux (not under PRoot), mouse scrolling works out of the box. The TUI uses Bubble Tea's AllMotion mouse mode by default. If you run Zero inside PRoot (e.g. through proot-distro), the scroll fix activates CellMotion to avoid PRoot's ptrace interference with the 1003 escape sequence.

Providers. Zero works with any OpenAI-compatible provider on Termux. For example, to use OpenCode Zen's free tier:

zero providers add opencode \
  --name opencode \
  --model deepseek-v4-flash-free \
  --base-url https://opencode.ai/zen/v1 \
  --set-active

Windows source builds can use the main zero.exe as the command runner and setup helper through Zero's built-in self-dispatch path. If you want a release-style layout anyway, build the standalone helper executables next to zero.exe:

go build -o zero.exe ./cmd/zero
go build -o zero-windows-command-runner.exe ./cmd/zero-windows-command-runner
go build -o zero-windows-sandbox-setup.exe ./cmd/zero-windows-sandbox-setup

Release Archive Format

Release archives are named:

• zero-v<version>-linux-<arch>.tar.gz
• zero-v<version>-macos-<arch>.tar.gz
• zero-v<version>-windows-<arch>.zip

Supported targets:

• linux-x64
• linux-arm64
• macos-x64
• macos-arm64
• windows-x64
• windows-arm64

Each archive must have a matching .sha256 file. The install scripts download both files, verify the checksum, and then copy the binary into the install directory.

Updating

Check for a newer release:

zero update --check

Then reinstall with npm or rerun the install script for the version you want.