WeftOS Quickstart

This guide gets you from zero to a running WeftOS kernel in a project directory.

Install

The fastest way to install WeftOS:

# macOS / Linux
curl -fsSL https://github.com/weave-logic-ai/weftos/releases/latest/download/clawft-cli-installer.sh | sh

# Or via Homebrew
brew install weave-logic-ai/tap/clawft-cli

# Windows
irm https://github.com/weave-logic-ai/weftos/releases/latest/download/clawft-cli-installer.ps1 | iex

See the installation guide for Docker, cargo, npm, and source builds.

Verify:

weft --version

Initialize a Project

Navigate to any project directory and run weftos init:

cd ~/my-project
weftos init

This 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 checkpoints
- tree/ -- resource tree state
- logs/ -- kernel logs
- artifacts/ -- 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 --force

Boot the Kernel

weftos boot

Output:

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 status

Output when initialized:

WeftOS initialized in current directory
  Config: weave.toml
  Runtime: .weftos/

Kernel Management with `weave`

The weave CLI provides detailed kernel management:

# Start kernel as a background daemon
weave kernel start

# Start in foreground (blocking)
weave kernel start --foreground

# Check kernel state, uptime, process/service counts
weave kernel status

# List registered services
weave kernel services

# List process table entries
weave kernel ps

# Stream logs in real time
weave kernel attach

# Show recent log entries
weave kernel logs -n 50

# Stop the daemon
weave kernel stop

# Restart the daemon
weave kernel restart

Build with More Features

The default build includes only the native feature (process table, agent supervision, IPC). For production use, enable additional subsystems:

# 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-sandbox

See 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 (v0.2)

Starting with v0.2, clawft includes a built-in local LLM provider that works with any OpenAI-compatible inference server. No cloud API keys required.

Ollama (recommended for getting started)

Install Ollama and pull a model:

# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# Pull a model
ollama pull llama3.1

# Verify it's running
curl http://localhost:11434/api/tags

Configure clawft to use Ollama by setting the model prefix to local/:

weft agent --model local/llama3.1

Or set it in your configuration:

# In your agent config
[routing]
mode = "static"
model = "local/llama3.1"

Other Local Servers

The local provider supports any OpenAI-compatible server:

Server	Default URL	Setup
Ollama	`http://localhost:11434/v1`	`ollama serve`
vLLM	`http://localhost:8000/v1`	`vllm serve model-name`
llama.cpp	`http://localhost:8080/v1`	`llama-server -m model.gguf`
LM Studio	`http://localhost:1234/v1`	Start from LM Studio UI

No API key is required for local servers (key-optional auth). The provider auto-detects the server type from the URL and configures itself accordingly.

What Next

Configuration Reference -- every weave.toml field 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

Quickstart

On this page