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	`false`	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"

[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

[mesh]

Peer-to-peer mesh networking between WeftOS nodes. Requires the mesh feature gate.

Field	Type	Default	Description
`enabled`	bool	`false`	Enable mesh networking
`bind_address`	string	`"0.0.0.0:9470"`	Address and port to bind the mesh listener
`seed_peers`	string[]	`[]`	Initial peer addresses for mesh discovery

[mesh]
enabled = true
bind_address = "0.0.0.0:9470"
seed_peers = ["192.168.1.10:9470"]

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