Current release / v1.1.0

Choose your runtime.

Use a signed native package, the checksum-verified Linux bootstrap, WSL2, or the npm launcher. Every path keeps browser control on a private local socket.

01 / macOS

macOS

Beginning with the next signed release, macOS bundles are universal for Apple Silicon and Intel, Developer ID signed, notarized, and stapled. The tap syncs after publication, and the cask also links headless-mcp. To build locally instead:

Requires Xcode Command Line Tools. The build checks for Swift, Apple utilities, and a compatible SDK before compiling. Local builds target the current architecture by default; set HEADLESSARCHS="arm64 x8664" to reproduce the universal release bundle.

brew install --cask LockInTime/headless/headless
headless help

./apps/headless/build.sh
./apps/headless/Headless.app/Contents/Resources/bin/headless help

02 / Linux

Linux

The release bootstrap supports Linux amd64 and arm64, downloads the matching tarball, verifies it against the release's SHA256SUMS, rejects unexpected archive contents, and delegates to the packaged runtime preflight. Install a specific release or prefix with:

To build locally instead:

curl -fsSL https://github.com/LockInTime/headless/releases/latest/download/install.sh | sh

curl -fsSL https://github.com/LockInTime/headless/releases/latest/download/install.sh \
  | HEADLESS_VERSION=1.1.0 sh -s -- --prefix /opt/headless

./apps/headless/build-linux.sh
apps/headless/build/linux/install-linux.sh

03 / Windows (WSL2)

Windows (WSL2)

There is no native Windows build; the Swift toolchain cannot currently compile the core for Windows (see architecture decision §6). Run Headless inside WSL2 instead:

Then, inside WSL2, follow the Linux install above. Chromium and FFmpeg come from apt (sudo apt install chromium ffmpeg). Alternatively, run the published GHCR image under Docker Desktop:

wsl --install -d Ubuntu

docker run --shm-size=1g ghcr.io/lockintime/headless:latest headless --version

04 / npm / npx

npm / npx

JavaScript-based agent harnesses can run the verified launcher without a global install:

The launcher selects the matching macOS or Linux release, verifies it against the release SHA256SUMS, validates its archive and embedded product version, and caches it privately for subsequent commands. Its download origin is fixed to this repository.

npx @lockintime/headless help
npx -p @lockintime/headless headless-mcp

docker pull ghcr.io/lockintime/headless:1.1.0
docker run --rm ghcr.io/lockintime/headless:1.1.0 headless capabilities

headless runtime
headless start

HEADLESS_LINUX_PLATFORM=linux/amd64 ./apps/headless/build-linux.sh