Complete reference for every weave.toml field including kernel, tick, sources, embedding, governance, and mesh settings.

weave.toml Configuration Reference

WeftOS projects are configured via weave.toml at the project root. This file is generated by weftos init and can be edited manually.

The weave.toml file uses TOML format. The clawft CLI (weft) reads a separate ~/.clawft/config.json for agent/provider/gateway settings; this document covers only the WeftOS-specific weave.toml.

Configuration Discovery

Source	Format	Purpose
`weave.toml` (project root)	TOML	WeftOS kernel, tick, sources, embedding, governance, mesh
`~/.clawft/config.json`	JSON	clawft agent, provider, gateway, tools, channels
`CLAWFT_CONFIG` env var	JSON	Override path for the clawft config file

Both snake_case and camelCase field names are accepted in JSON config files. TOML files use snake_case only.

[domain]

Project identity metadata.

Field	Type	Default	Description
`name`	string	directory name	Project name used in logs and UI
`language`	string	auto-detected	Primary language (`rust`, `javascript`, `python`, `generic`). Auto-detected from `Cargo.toml`, `package.json`, or `pyproject.toml`
`description`	string	`"WeftOS-managed project"`	Human-readable project description

[domain]
name = "my-project"
language = "rust"
description = "Backend API service"

[kernel]

Controls the WeftOS kernel subsystem. These fields map to KernelConfig in clawft-types.

Field	Type	Default	Description
`enabled`	bool	`true`	Activate the kernel on startup. When false, kernel subsystems only run when invoked via `weave kernel` commands
`max_processes`	u32	`64`	Maximum concurrent entries in the process table. Raise for workloads that spawn many parallel agents
`health_check_interval_secs`	u64	`30`	Seconds between periodic health checks. Lower values detect failures faster but add overhead

[kernel]
max_processes = 128
health_check_interval_secs = 15

[kernel.chain]

Cryptographic audit trail configuration. Requires the exochain feature gate.

Field	Type	Default	Description
`enabled`	bool	`true`	Enable the local chain
`checkpoint_interval`	u64	`1000`	Events between automatic checkpoints. Lower values give more durable state at the cost of more I/O
`chain_id`	u32	`0`	Chain identifier. `0` means the local node chain
`checkpoint_path`	string or null	`~/.clawft/chain.json`	File path for chain persistence. Omit to use the default location

[kernel.chain]
enabled = true
checkpoint_interval = 500
checkpoint_path = ".weftos/chain.json"

[kernel.resource_tree]

Hierarchical resource model. Requires the exochain feature gate.

Field	Type	Default	Description
`enabled`	bool	`true`	Enable the resource tree
`checkpoint_path`	string or null	(in-memory)	Path to checkpoint file. Omit for in-memory only

[kernel.resource_tree]
enabled = true
checkpoint_path = ".weftos/resources.json"

[kernel.cluster]

Distributed coordination via ruvector. Requires the cluster and/or mesh feature gates.

Field	Type	Default	Description
`replication_factor`	usize	`3`	Replica copies per shard
`shard_count`	u32	`64`	Total shards in the cluster
`heartbeat_interval_secs`	u64	`5`	Seconds between heartbeat checks
`node_timeout_secs`	u64	`30`	Seconds before marking a node offline
`enable_consensus`	bool	`true`	Enable DAG-based consensus
`min_quorum_size`	usize	`2`	Minimum nodes required for quorum
`seed_nodes`	string[]	`[]`	Addresses of coordinator nodes for discovery
`node_name`	string or null	(none)	Human-readable display name for this node

[kernel.cluster]
replication_factor = 3
shard_count = 64
heartbeat_interval_secs = 5
seed_nodes = ["192.168.1.100:8080", "192.168.1.101:8080"]
node_name = "node-alpha"

[kernel.vector]

Vector search backend configuration. Requires the ecc feature gate. The diskann and hybrid backends additionally require the diskann feature.

Field	Type	Default	Description
`backend`	string	`"hnsw"`	Vector backend: `"hnsw"`, `"diskann"`, or `"hybrid"`
`dimensions`	usize	`384`	Vector dimensionality (must match your embedding provider)

[kernel.vector]
backend = "hnsw"
dimensions = 384

[kernel.vector.hnsw]

HNSW-specific tuning (used by hnsw and hybrid backends).

Field	Type	Default	Description
`ef_search`	usize	`100`	Size of the dynamic candidate list during search. Higher values improve recall at the cost of latency
`ef_construction`	usize	`200`	Size of the dynamic candidate list during index construction. Higher values produce a better graph

[kernel.vector.hnsw]
ef_search = 100
ef_construction = 200

[kernel.vector.diskann]

DiskANN-specific tuning (used by diskann and hybrid backends).

Field	Type	Default	Description
`max_points`	usize	`1_000_000`	Maximum number of vectors the index can hold
`num_neighbors`	usize	`64`	Number of neighbors per node in the Vamana graph
`search_list_size`	usize	`128`	Size of the search candidate list
`data_path`	string	`".weftos/diskann"`	Directory for SSD-backed data files
`use_pq`	bool	`false`	Enable product quantization for compression
`pq_num_chunks`	usize	`32`	Number of PQ sub-quantizer chunks

[kernel.vector.diskann]
max_points = 10_000_000
num_neighbors = 64
search_list_size = 128
data_path = ".weftos/diskann"
use_pq = true
pq_num_chunks = 32

[kernel.vector.hybrid]

Hybrid backend tuning (HNSW hot cache + DiskANN cold store).

Field	Type	Default	Description
`hot_capacity`	usize	`100_000`	Maximum vectors in the hot HNSW cache
`promotion_threshold`	u32	`3`	Access count before a cold vector is promoted to the hot cache
`eviction_batch_size`	usize	`1000`	Number of vectors evicted per batch when the hot cache is full

[kernel.vector]
backend = "hybrid"
dimensions = 384

[kernel.vector.hnsw]
ef_search = 100
ef_construction = 200

[kernel.vector.diskann]
max_points = 10_000_000
data_path = ".weftos/diskann"

[kernel.vector.hybrid]
hot_capacity = 100_000
promotion_threshold = 3
eviction_batch_size = 1000

[tick]

ECC cognitive tick loop configuration. Controls how frequently the kernel runs its cognitive cycle.

Field	Type	Default	Description
`interval_ms`	u64	`50`	Minimum tick interval in milliseconds. The calibrator may increase this if the system is slow
`budget_ratio`	f64	`0.3`	Fraction of tick budget allocated to cognitive processing (0.0-1.0)
`adaptive`	bool	`true`	Enable adaptive tick calibration based on system load

[tick]
interval_ms = 50
budget_ratio = 0.3
adaptive = true

Calibration runs during weave boot and logs the chosen tick interval. When adaptive = true, the kernel adjusts the interval based on measured latency.

[sources]

Defines where the kernel reads project artifacts for indexing and analysis.

[sources.git]

Field	Type	Default	Description
`path`	string	`"."`	Path to the git repository root
`branch`	string	`"main"`	Branch to track

[sources.files]

Field	Type	Default	Description
`root`	string	`"."`	Root directory for file scanning
`patterns`	string[]	auto-detected	Glob patterns for files to index. Auto-detected based on `language` (`*/.rs` for Rust, `*/.ts,js` for JavaScript, etc.)

[sources.git]
path = "."
branch = "main"

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

[embedding]

Embedding backend for the ECC cognitive substrate.

Field	Type	Default	Description
`provider`	string	`"mock-sha256"`	Embedding provider. `"mock-sha256"` for deterministic hash vectors, or an LLM model name for real embeddings
`dimensions`	usize	`384`	Vector dimensionality
`batch_size`	usize	`16`	Batch size for embedding requests

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

To use real neural embeddings, enable the onnx-embeddings feature and download the model:

scripts/download-model.sh
scripts/build.sh native --features onnx-embeddings

The model is stored in .weftos/models/all-MiniLM-L6-v2.onnx.

[governance]

Governance engine settings for risk assessment and environment policies.

Field	Type	Default	Description
`default_environment`	string	`"development"`	Active environment: `development`, `staging`, `production`
`risk_threshold`	f64	`0.9`	Risk score threshold (0.0-1.0). Operations above this value require explicit approval

[governance]
default_environment = "production"
risk_threshold = 0.7

[kernel.mesh]

Peer-to-peer mesh transport layer (K6). When enabled, the kernel spawns a MeshRuntime during boot that listens for peer connections and wires them into the A2A router for cross-node message delivery.

Field	Type	Default	Description
`enabled`	bool	`false`	Enable mesh transport
`transport`	string	`"tcp"`	Transport backend: `"tcp"` or `"ws"` (WebSocket)
`listen_addr`	string	`"0.0.0.0:9470"`	Address and port to bind the mesh listener
`discovery`	bool	`false`	Enable Kademlia DHT peer discovery
`seed_peers`	string[]	`[]`	Peer addresses to connect to on startup
`noise`	bool	`false`	Enable Noise Protocol encryption (XX_25519_ChaChaPoly_SHA256)
`noise_key_path`	string	(none)	Path to Ed25519 private key file for Noise. Ephemeral key generated if absent.

[kernel.mesh]
enabled = true
transport = "tcp"
listen_addr = "0.0.0.0:9470"
noise = true
discovery = true
seed_peers = ["192.168.1.10:9470", "192.168.1.11:9470"]

When noise = true, all peer connections perform a Noise XX handshake before any data flows. Both the listener (responder) and seed peer connections (initiator) use the same keypair. Traffic is encrypted with ChaCha20-Poly1305 AEAD.

The mesh listener starts in boot phase 5d (after the A2A router, before cluster service) so that cluster coordination can use mesh transport for peer discovery and message delivery.

Example Configurations

Minimal (development)

[domain]
name = "my-app"

[kernel]
max_processes = 64

[tick]
interval_ms = 50
adaptive = true

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

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

Single-node production

[domain]
name = "prod-service"
language = "rust"
description = "Production API backend"

[kernel]
max_processes = 256
health_check_interval_secs = 10

[kernel.chain]
enabled = true
checkpoint_interval = 500
checkpoint_path = "/var/lib/weftos/chain.json"

[kernel.resource_tree]
enabled = true
checkpoint_path = "/var/lib/weftos/resources.json"

[tick]
interval_ms = 50
budget_ratio = 0.4
adaptive = true

[sources.git]
path = "."
branch = "main"

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

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

[governance]
default_environment = "production"
risk_threshold = 0.7

[mesh]
enabled = false

Multi-node cluster

[domain]
name = "cluster-node-1"
description = "Cluster member"

[kernel]
max_processes = 512
health_check_interval_secs = 5

[kernel.chain]
enabled = true
checkpoint_interval = 200

[kernel.cluster]
replication_factor = 3
shard_count = 128
heartbeat_interval_secs = 3
node_timeout_secs = 15
enable_consensus = true
min_quorum_size = 2
seed_nodes = ["10.0.0.1:9470", "10.0.0.2:9470"]
node_name = "node-1"

[tick]
interval_ms = 25
budget_ratio = 0.3
adaptive = true

[sources.git]
path = "."
branch = "main"

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

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

[governance]
default_environment = "production"
risk_threshold = 0.8

[mesh]
enabled = true
bind_address = "0.0.0.0:9470"
seed_peers = ["10.0.0.1:9470", "10.0.0.2:9470"]

Configuration Reference