clawft

Your First Project

Step-by-step tutorial for initializing, configuring, booting, and inspecting a WeftOS project.

Your First WeftOS Project

This tutorial walks through the complete workflow of creating a WeftOS-managed project from scratch: initialization, configuration, booting the kernel, and inspecting its state.

Step 1: Initialize the Project

Navigate to an existing project directory (or create a new one) and run weftos init:

mkdir ~/my-first-weftos-project
cd ~/my-first-weftos-project
git init
weftos init

This creates two artifacts:

  • weave.toml -- the project configuration file that controls tick rate, source scanning, embedding backend, governance policy, and mesh settings.
  • .weftos/ -- the runtime state directory for chain checkpoints, resource tree state, kernel logs, and analysis artifacts.

The .weftos/ directory is automatically added to .gitignore.

Step 2: Review the Configuration

Open weave.toml to see the generated defaults:

[domain]
name = "my-first-weftos-project"

[kernel]
max_processes = 64

[tick]
interval_ms = 50
adaptive = true

[sources.files]
root = "."
patterns = ["**/*.rs"]

[embedding]
provider = "mock-sha256"
dimensions = 384
batch_size = 16

Key sections:

  • [domain] -- project identity. The name is auto-detected from the directory name, and language is inferred from project files.
  • [kernel] -- process table limits and health check intervals.
  • [tick] -- cognitive tick loop timing. The adaptive flag allows the kernel to self-calibrate based on measured latency.
  • [sources] -- where the kernel scans for files to index.
  • [embedding] -- the embedding backend. mock-sha256 provides deterministic hash-based vectors for development. Switch to onnx-embeddings for real neural embeddings.

For the full field reference, see the configuration guide.

Step 3: Boot the Kernel

Start the kernel in the foreground:

weftos boot

You should see output like:

Booting WeftOS in /home/user/my-first-weftos-project...
WeftOS running
  State: Running
  Services: 3
  Processes: 0

Press Ctrl+C to stop.

The kernel is now running with the default services: health monitoring, cron scheduling, and the service registry.

Step 4: Check Status

Open a second terminal and check the kernel state:

cd ~/my-first-weftos-project
weftos status

Output:

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

For more detailed information, use the weaver CLI:

# Kernel state, uptime, process/service counts
weaver kernel status

# List registered services
weaver kernel services

# Show the process table (empty at first)
weaver kernel ps

Step 5: Use the Kernel Management CLI

The weaver CLI provides full lifecycle control. With the kernel running in another terminal (or as a daemon), try these commands:

# Start as a background daemon instead of foreground
weaver kernel start

# Stream live kernel logs
weaver kernel attach

# Show the last 50 log entries
weaver kernel logs -n 50

# Stop the daemon gracefully
weaver kernel stop

# Restart
weaver kernel restart

Step 6: Enable More Features

The release binaries use the default native feature set (process table, agent supervision, IPC). To unlock more of the kernel, build from source with additional features:

# Add cognitive substrate + audit trail + self-healing
scripts/build.sh native --features ecc,exochain,os-patterns

After rebuilding, weftos boot will start additional services:

  • ECC -- causal graph, HNSW vector memory, cognitive tick loop
  • ExoChain -- append-only hash-linked audit trail
  • OS Patterns -- self-healing, dead-letter queue, structured metrics

For multi-node deployments, add mesh networking:

scripts/build.sh native --features ecc,exochain,os-patterns,mesh,cluster

Then configure mesh settings in weave.toml:

[kernel.mesh]
enabled = true
transport = "quic"
listen_addr = "0.0.0.0:9489"
seed_peers = ["quic://seed.example.com:9489"]

The mesh listener binds to loopback (127.0.0.1:9489) unless you give it a non-loopback address. Peers on other machines need one. For the pairing flow that joins nodes into a named mesh, see weaver mesh --help.

Project Structure

After initialization and a boot cycle, your project looks like this:

my-first-weftos-project/
  weave.toml          # WeftOS configuration
  .weftos/            # Runtime state (gitignored)
    chain/            # Chain checkpoints
    tree/             # Resource tree state
    logs/             # Kernel logs
    artifacts/        # Build/analysis artifacts
  .gitignore          # Includes .weftos/ entry
  ... your code ...

Next Steps

On this page