Quickstart
Get from zero to a running WeftOS kernel in a project directory.
WeftOS Quickstart
This guide gets you from zero to a running WeftOS kernel in a project directory.
Install
curl -fsSL https://raw.githubusercontent.com/WeftOS/weftos/master/scripts/install.sh | shThis installs weft, weaver and weftos. Homebrew, Docker, crates.io and source builds are covered in the installation guide.
Verify:
weft --version
weaver --versionInitialize a Project
Navigate to any project directory and run weftos init:
cd ~/my-project
weftos initThis creates two things:
-
weave.toml-- project configuration (tick rate, sources, embedding, governance, mesh settings). See the configuration reference for all fields. -
.weftos/-- runtime state directory containing:chain/-- local chain checkpointstree/-- resource tree statelogs/-- kernel logsartifacts/-- build/analysis artifacts
The .weftos/ directory is automatically added to .gitignore if one exists.
If the project is already initialized, use --force to reinitialize:
weftos init --forceBoot the Kernel
weftos bootOutput:
Booting WeftOS in /home/user/my-project...
WeftOS running
State: Running
Services: 3
Processes: 0
Press Ctrl+C to stop.The kernel runs in the foreground. Press Ctrl+C for graceful shutdown.
Check Status
weftos statusOutput when initialized:
WeftOS initialized in current directory
Config: weave.toml
Runtime: .weftos/Kernel Management with weaver
weaver is the operator CLI for the node daemon. It manages the daemon and everything running under it:
Run these from the project directory: weaver kernel start then starts a daemon for that project. The per-user daemon that hosts many project kernels is weaver kernel start --profile user (see Deployment).
# Start kernel as a background daemon
weaver kernel start
# Start in foreground (blocking)
weaver kernel start --foreground
# Check kernel state, uptime, process/service counts
weaver kernel status
# List registered services
weaver kernel services
# List process table entries
weaver kernel ps
# Stream logs in real time
weaver kernel attach
# Show recent log entries
weaver kernel logs -n 50
# Stop the daemon
weaver kernel stop
# Restart the daemon
weaver kernel restartBuild with More Features
The weftos binary in the release archives is built with the default native feature (process table, agent supervision, IPC). To enable more subsystems, build from source:
# Single-node production: cognitive substrate + audit trail + self-healing
scripts/build.sh native --features ecc,exochain,os-patterns
# Multi-node: add mesh networking and clustering
scripts/build.sh native --features ecc,exochain,os-patterns,mesh,cluster
# Everything
scripts/build.sh native --features ecc,exochain,os-patterns,mesh,cluster,onnx-embeddings,wasm-sandboxSee the feature flags guide for the complete reference.
Project Structure After Init
my-project/
weave.toml # WeftOS configuration
.weftos/ # Runtime state (gitignored)
chain/ # Chain checkpoints
tree/ # Resource tree
logs/ # Kernel logs
artifacts/ # Analysis output
.gitignore # Updated with .weftos/ entry
... your code ...Local LLM Setup
clawft can talk to any OpenAI-compatible inference server, so no cloud API key is needed. Two prefixes cover local servers:
| Prefix | Default endpoint | Notes |
|---|---|---|
local/ | http://127.0.0.1:8090/v1 | The Hermes serve recipe (hermes-4.3-36b by default). Override the base URL in your config. |
ollama/ | http://localhost:11434/v1 | Ollama's default port. |
Both read an optional key from LOCAL_LLM_API_KEY; local servers usually need none.
Ollama
ollama pull llama3.1
weft agent --model ollama/llama3.1 -m "hello"To make it the default, set it in ~/.clawft/config.json:
{ "agents": { "defaults": { "model": "ollama/llama3.1" } } }Other servers (vLLM, llama.cpp, LM Studio) work the same way: point a provider's api_base at the server's /v1 URL. See the providers page for the provider list and override syntax.
What Next
- Configuration Reference -- every
weave.tomlfield with types, defaults, and examples - Feature Flags -- compile-time feature flags across all crates
- Installation -- detailed installation (Docker, ONNX embeddings, debug builds)
- First Project -- step-by-step tutorial for your first WeftOS project
- Kernel Phases -- kernel phase architecture (K0-K6)
- Kernel Modules -- kernel module descriptions
- Architecture -- system architecture overview