clawft

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 | sh

This installs weft, weaver and weftos. Homebrew, Docker, crates.io and source builds are covered in the installation guide.

Verify:

weft --version
weaver --version

Initialize a Project

Navigate to any project directory and run weftos init:

cd ~/my-project
weftos init

This creates two things:

  1. weave.toml -- project configuration (tick rate, sources, embedding, governance, mesh settings). See the configuration reference for all fields.

  2. .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 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 restart

Build 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-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

clawft can talk to any OpenAI-compatible inference server, so no cloud API key is needed. Two prefixes cover local servers:

PrefixDefault endpointNotes
local/http://127.0.0.1:8090/v1The Hermes serve recipe (hermes-4.3-36b by default). Override the base URL in your config.
ollama/http://localhost:11434/v1Ollama'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

On this page