Installation
Install WeftOS from the release installer, Homebrew, Docker, crates.io, or source, and keep it updated.
Installing WeftOS
WeftOS ships three command-line binaries and one optional GUI:
| Binary | Purpose | cargo-dist package |
|---|---|---|
weft | Agent CLI: chat, gateway, tools, memory, chief of staff | clawft-cli |
weaver | Operator CLI: the node daemon, projects, mesh, cogs, updates | clawft-weave |
weftos | Standalone kernel daemon binary | weftos |
clawft-gui-egui | Native egui desktop shell (optional) | clawft-gui-egui |
The current release is v0.8.4. Each release publishes archives for Linux (glibc and musl, x86_64 and aarch64), macOS (Intel and Apple Silicon) and Windows x86_64.
Release installer (recommended)
The repository's scripts/install.sh installs weft, weaver and weftos into /usr/local/bin and is safe to re-run:
curl -fsSL https://raw.githubusercontent.com/WeftOS/weftos/master/scripts/install.sh | shIf the GitHub CLI (gh) is installed, the script verifies each archive's sigstore attestation before installing. Pass --verify to refuse to install without it, or --no-verify to skip it. Set WEFTOS_INSTALL_DIR to install somewhere else. The details are in the repository install guide.
Each release also carries a per-package cargo-dist installer if you want only one binary:
# weft only
curl --proto '=https' --tlsv1.2 -LsSf \
https://github.com/WeftOS/weftos/releases/latest/download/clawft-cli-installer.sh | sh
# weaver only
curl --proto '=https' --tlsv1.2 -LsSf \
https://github.com/WeftOS/weftos/releases/latest/download/clawft-weave-installer.sh | shOn Windows, use the matching PowerShell installer:
irm https://github.com/WeftOS/weftos/releases/latest/download/clawft-cli-installer.ps1 | iexThe installers are clawft-cli-installer, clawft-weave-installer, weftos-installer and clawft-gui-egui-installer, each with an .sh and .ps1 form. You can also download an archive such as clawft-cli-aarch64-apple-darwin.tar.gz from the Releases page; every archive has a .sha256 file beside it.
Homebrew (macOS and Linux)
The tap is weave-logic-ai/homebrew-tap, with one formula per cargo-dist package:
brew install weave-logic-ai/tap/clawft-cli # weft
brew install weave-logic-ai/tap/clawft-weave # weaver
brew install weave-logic-ai/tap/weftos # kernel daemonDocker
Each stable release publishes a multi-arch (linux/amd64 and linux/arm64) image to ghcr.io/weftos/weftos, tagged with the version and latest. The image contains weft and weaver. Its entrypoint passes its arguments to weft, and the default command is gateway, which starts a kernel daemon beside the gateway.
docker pull ghcr.io/weftos/weftos:latest
docker run --rm ghcr.io/weftos/weftos --versionFor a long-running gateway (REST and WebSocket API on port 8080, bound to loopback on the host):
docker run -d --name weftos \
-v weftos-clawft:/home/weft/.clawft \
-v weftos-state:/home/weft/.weftos \
-p 127.0.0.1:8080:8080 \
ghcr.io/weftos/weftosSee the Docker deployment guide for production setup.
crates.io
Forty library and daemon crates are published to crates.io at 0.8.4, including weftos, clawft-core, clawft-kernel and clawft-types. Publishing happens on stable tags only; release candidates are not published.
cargo install weftos # the kernel daemon binary[dependencies]
weftos = "0.8"
clawft-core = "0.8"
clawft-kernel = "0.8"
clawft-types = "0.8"The weft and weaver CLI packages (clawft-cli, clawft-weave) are marked publish = false, so cargo install clawft-cli and cargo binstall clawft-cli do not work. Install them from a release, Homebrew, Docker or source.
From source
Source builds need Rust 1.95 or newer (rust-toolchain.toml pins 1.95). Use the build script rather than raw cargo:
git clone https://github.com/WeftOS/weftos.git
cd weftos
scripts/build.sh native # release build of weft, weaver, weftos
scripts/build.sh native-debug # faster, for development
scripts/build.sh native --features ecc,exochain,os-patterns,mesh,cluster,onnx-embeddings,wasm-sandboxscripts/build.sh gate runs the full pre-commit check set. See the feature flags guide for the flags.
For optional ONNX embeddings, run scripts/download-model.sh first, then build with --features onnx-embeddings.
Verify
weft --version
weaver --version
weft status
weft tools listBoth version commands print the release you installed (for example 0.8.4).
Updating
A release installed with the installer updates itself:
weaver update --check # report only
weaver update # verify the signed release, replace weft, weaver and weftos, offer a daemon restartweaver update checks the release's Ed25519 signature against a key compiled into the binary, then each archive against the signed checksum list, and replaces all binaries together with rollback. It refuses to touch Homebrew, cargo install and source builds, and prints their own update command instead. weft update is also available. See the repository install guide for the flags, the signature rules and the no-downgrade guarantee.
weaver doctor install lists every copy of the binaries on the machine and which install channel owns each.
Running the daemon
weaver runs a per-user daemon: weaver kernel start --profile user starts it and weaver kernel status --profile user checks it. To start it at login, print a launchd or systemd user unit and install it yourself; weaver service unit never runs launchctl or systemctl:
weaver service unit --kind launchd --out ~/Library/LaunchAgents/ai.weftos.weaver.plist
weaver service unit --kind systemdThe command prints the install commands to run after writing a unit. For how the daemon relates to projects, see Deployment.
Troubleshooting
| Problem | Fix |
|---|---|
weft: command not found after install | Add the install directory (/usr/local/bin, or WEFTOS_INSTALL_DIR) to your PATH. For cargo install, add ~/.cargo/bin. |
weaver update refuses | The install belongs to Homebrew, cargo or a source build. Use the command it prints. |
| Homebrew formula not found | Run brew tap weave-logic-ai/tap first. |
| Docker permission denied pulling the image | The image is public. Run docker logout ghcr.io if a stale login is rejected. |
| Rust older than 1.95 | rustup update, or let rust-toolchain.toml select the toolchain. |
| ONNX model not found | Run scripts/download-model.sh first. |
Next steps
- Quickstart to get a kernel running
- Feature flags for compile-time options
- Configuration for runtime configuration
- First project