Installation

Install Weave

macOS and Linux

Run the POSIX installer:

curl -fsSL https://weave.4kshat.dev/install.sh | sh

The script detects your operating system and CPU architecture, then installs the matching binary from the latest GitHub release as weave. Fresh installations default to ~/.local/bin, a user-owned location that does not require administrator access.

Rerun the same command to upgrade. The installer checks the existing binary at the target path (or on PATH when using the default location), compares its version with the latest release, and only downloads a binary when an upgrade is available. Current and newer versions are left unchanged. Development or malformed versions must be replaced manually so the installer cannot accidentally downgrade them.

Interactive terminals show an in-place progress loader while release metadata, binaries, and installation stages are processed. Piped, redirected, or CI output uses stable line-by-line messages without terminal control characters.

Verify the installation:

weave --help

Custom install directory

Set WEAVE_INSTALL_DIR to install somewhere other than ~/.local/bin:

curl -fsSL https://weave.4kshat.dev/install.sh | WEAVE_INSTALL_DIR="$HOME/bin" sh

Windows

Run the native installer from PowerShell:

irm https://weave.4kshat.dev/install.ps1 | iex

The installer downloads and verifies weave.exe, installs it under %LOCALAPPDATA%\Weave\bin, and adds that directory to your user PATH. It also discovers an existing QEMU installation or installs QEMU through WinGet, verifies the required system emulator, and persists its path for Weave. Open a new PowerShell, Command Prompt, or Windows Terminal session after installation.

Windows prerequisites are configured automatically

Windows Package Manager (winget) is required only when QEMU is not already installed. WinGet may show an elevation prompt while installing QEMU. It is provided by Microsoft's App Installer on supported Windows 10 and Windows 11 systems.

To choose a different installation directory, set a Windows path before running the installer:

$env:WEAVE_INSTALL_DIR = "$HOME\bin"
irm https://weave.4kshat.dev/install.ps1 | iex

Host requirements

Weave uses Lima's native virtualization backend:

Platform	Backend	Notes
macOS	Virtualization.framework (`vz`)	Nested virtualization requires Apple M3 or later and macOS 15 or later.
Linux	QEMU	Install the QEMU packages provided by your distribution.
Windows	QEMU	The PowerShell installer installs and configures QEMU automatically through WinGet when needed.

Advanced Windows installations can point Weave to QEMU explicitly with QEMU_SYSTEM_X86_64 or QEMU_SYSTEM_AARCH64.

Install a specific release

Set WEAVE_VERSION to a GitHub release tag:

curl -fsSL https://weave.4kshat.dev/install.sh | WEAVE_VERSION=v0.1.0 sh

On Windows:

$env:WEAVE_VERSION = "v0.1.0"
irm https://weave.4kshat.dev/install.ps1 | iex

The installer will not replace an existing installation with an older release.

Upgrade or uninstall

Upgrade an installed binary in place:

weave upgrade

The command selects the newest stable release, including newer minor or major versions. It preserves the existing executable if checking, downloading, or atomically replacing the release fails. On Windows, a detached helper waits for the current process to exit before replacing the executable.

Remove the CLI:

weave uninstall

Uninstall first stops all running Weave-managed VMs. A never-used installation skips Lima initialization, and Windows defers executable deletion until the CLI exits. It removes only the CLI binary and retains the runtime, configuration, VM disks, and guest user data in ~/weave on macOS and Linux or %APPDATA%\weave on Windows. Persistent data is never deleted automatically; remove that directory manually only after confirming that you no longer need it.

Continue to the quick start to create your first VM.