Configuration File

Full reference for the starweft.toml configuration file.

Overview

Starweft configuration is managed through config.toml. It is auto-generated by starweft init and is placed by default directly under the data directory (~/.starweft/config.toml).

bash

# Display the current configuration
starweft config show
 
# Validate the configuration
starweft config validate

[node]

Basic node settings.

Field	Type	Default	Description
`role`	string	-	The node's role. One of: principal / owner / worker / relay
`display_name`	string	`"<role>-node"`	Display name for the node
`data_dir`	string	`"~/.starweft"`	Path to the data directory. ~ is expanded to the home directory
`listen`	string[]	auto-generated	List of listen addresses (multiaddr format)
`log_level`	string	`"info"`	Log level. One of: trace / debug / info / warn / error

toml

[node]
role = "worker"
display_name = "worker-01"
data_dir = "~/.starweft-worker"
listen = ["/unix/~/.starweft-worker/mailbox.sock"]
log_level = "info"

[identity]

Specifies paths to Ed25519 key files. Automatically configured by starweft identity create.

Field	Type	Default	Description
`actor_key_path`	string \| null	null	Path to the actor key file. Used for signing
`stop_authority_key_path`	string \| null	null	Path to the stop authority key file. Used by the principal to sign stop orders

toml

[identity]
actor_key_path = "~/.starweft/identity/actor_key"
stop_authority_key_path = "~/.starweft/identity/stop_authority_key"

[discovery]

Peer discovery settings.

Field	Type	Default	Description
`seeds`	string[]	`[]`	List of initial peer multiaddresses to connect to
`auto_discovery`	bool	`true`	Enable automatic discovery from peers
`mdns`	bool	true when libp2p	mDNS local network discovery (added in v0.3.0; default when transport=libp2p)
`registry_url`	string \| null	null	URL of the registry server
`registry_ttl_sec`	u64	`300`	TTL for registry entries (seconds)
`registry_heartbeat_sec`	u64	`60`	Heartbeat interval for the registry (seconds)
`registry_shared_secret`	string \| null	null	Shared secret for registry authentication (direct value)
`registry_shared_secret_env`	string \| null	null	Name of the environment variable containing the shared secret

toml

[discovery]
seeds = ["/unix/~/.starweft-owner/mailbox.sock"]
auto_discovery = true
mdns = false
registry_url = "http://127.0.0.1:7777"
registry_ttl_sec = 300
registry_heartbeat_sec = 60

[p2p]

P2P transport settings.

Field	Type	Default	Description
`transport`	string	Unix: `"local_mailbox"` / Windows: `"libp2p"`	Transport type. local_mailbox (Unix sockets) or libp2p (TCP)
`relay_enabled`	bool	`true`	Enable communication via relay nodes
`direct_preferred`	bool	`true`	Prefer direct connections
`max_peers`	u16	`128`	Maximum number of connectable peers

toml

[p2p]
transport = "local_mailbox"
relay_enabled = true
direct_preferred = true
max_peers = 128

[ledger]

SQLite database settings for event sourcing.

Field	Type	Default	Description
`path`	string	`"<data_dir>/ledger/node.db"`	Path to the SQLite database file

toml

[ledger]
path = "~/.starweft/ledger/node.db"

[openclaw]

OpenClaw subprocess settings. Primarily used with the worker role.

Field	Type	Default	Description
`enabled`	bool	`false`	Enable OpenClaw integration
`bin`	string	`"openclaw"`	Path or command name of the OpenClaw binary
`working_dir`	string \| null	null	Working directory for the OpenClaw subprocess
`timeout_sec`	u64	`3600`	Task execution timeout (seconds)
`capability_version`	string	`"openclaw.execution.v1"`	Capability version of the OpenClaw bridge

toml

[openclaw]
enabled = true
bin = "/usr/local/bin/openclaw"
working_dir = "/home/user/workspace"
timeout_sec = 3600
capability_version = "openclaw.execution.v1"

[compatibility]

Controls protocol and schema version compatibility.

Field	Type	Default	Description
`protocol_version`	string	`"starweft/0.1"`	Message protocol version
`schema_version`	string	auto (current store version)	Store schema version
`bridge_capability_version`	string	`"openclaw.execution.v1"`	Capability version of the OpenClaw bridge. Must match openclaw.capability_version
`allow_legacy_protocols`	bool	`false`	Allow messages using legacy protocol versions

toml

[compatibility]
protocol_version = "starweft/0.1"
schema_version = "starweft-store/3"
bridge_capability_version = "openclaw.execution.v1"
allow_legacy_protocols = false

[owner]

Settings specific to the owner role. Controls the retry policy for task failures.

Field	Type	Default	Description
`max_retry_attempts`	u64	`8`	Maximum number of retry attempts
`retry_cooldown_ms`	u64	`250`	Retry interval (milliseconds)
`retry_strategy`	string	`"rule_based"`	Retry strategy. Currently only rule_based is supported
`retry_rules`	OwnerRetryRule[]	default rule set	Pattern-based retry rules (see below)

retry_rules

Each rule consists of a pattern (partial match on the error message), an action (retry behavior), and a reason (reason for logging purposes).

action values:

retry_same_worker -- Retry on the same worker
retry_different_worker -- Retry on a different worker
no_retry -- Do not retry

toml

[owner]
max_retry_attempts = 8
retry_cooldown_ms = 250
retry_strategy = "rule_based"
 
[[owner.retry_rules]]
pattern = "timeout"
action = "retry_same_worker"
reason = "transient timeout"
 
[[owner.retry_rules]]
pattern = "process failed"
action = "retry_different_worker"
reason = "transient execution failure"
 
[[owner.retry_rules]]
pattern = "capability mismatch"
action = "no_retry"
reason = "permanent task/input failure"

Default retry rules

pattern	action	reason
`timeout`	`retry_same_worker`	transient timeout
`timed out`	`retry_same_worker`	transient timeout
`process failed`	`retry_different_worker`	transient execution failure
`worker overloaded`	`retry_different_worker`	transient execution failure
`worker unavailable`	`retry_different_worker`	transient execution failure
`capability mismatch`	`no_retry`	permanent task/input failure
`invalid input`	`no_retry`	permanent task/input failure
`schema`	`no_retry`	permanent task/input failure
`unauthorized`	`no_retry`	permanent task/input failure

[worker]

Settings specific to the worker role.

Field	Type	Default	Description
`accept_join_offers`	bool	`true`	Whether to accept JoinOffers from the owner
`max_active_tasks`	u64	`1`	Maximum number of concurrently running tasks

toml

[worker]
accept_join_offers = true
max_active_tasks = 1

[observation]

Planning and evaluation settings. Used when the owner role decomposes visions into tasks.

Field	Type	Default	Description
`planner`	string	`"heuristic"`	Planning strategy. One of: heuristic / openclaw / openclaw_worker
`evaluator`	string	`"heuristic"`	Evaluation strategy. Currently only heuristic is supported
`cache_snapshots`	bool	`true`	Cache snapshots
`cache_ttl_sec`	u64	`30`	Cache TTL (seconds)
`max_planned_tasks`	usize	`6`	Maximum number of tasks generated from a single vision
`min_task_objective_chars`	usize	`48`	Minimum number of characters for task objective text
`planner_bin`	string \| null	null	OpenClaw binary for the planner (when using openclaw/openclaw_worker strategy)
`planner_working_dir`	string \| null	null	Working directory for the planner
`planner_timeout_sec`	u64	`120`	Planner timeout (seconds)
`planner_capability_version`	string	`"openclaw.plan.v1"`	Capability version for the planner
`planner_fallback_to_heuristic`	bool	`true`	Fall back to heuristic when the OpenClaw planner fails

toml

[observation]
planner = "heuristic"
evaluator = "heuristic"
cache_snapshots = true
cache_ttl_sec = 30
max_planned_tasks = 6
min_task_objective_chars = 48
planner_timeout_sec = 120
planner_capability_version = "openclaw.plan.v1"
planner_fallback_to_heuristic = true

Comparison of planner strategies

Strategy	Execution Location	Description
`heuristic`	Local (owner)	Rule-based task decomposition from vision text. No LLM required
`openclaw`	Local (owner)	Planning via a local OpenClaw subprocess
`openclaw_worker`	Remote (worker)	Delegates the planning task to a worker node

[logs]

Runtime log rotation settings.

Field	Type	Default	Description
`rotate_max_bytes`	u64	`1048576`	Maximum log file size (bytes). Default is 1 MB
`max_archives`	usize	`5`	Maximum number of archive files to retain

toml

[logs]
rotate_max_bytes = 1048576
max_archives = 5

[artifacts]

Storage settings for artifacts generated by task execution.

Field	Type	Default	Description
`dir`	string	`"<data_dir>/artifacts"`	Artifact storage directory
`max_files`	usize	`256`	Maximum number of artifact files to retain
`max_age_sec`	u64	`604800`	Maximum retention period for artifacts (seconds). Default is 7 days

toml

[artifacts]
dir = "~/.starweft/artifacts"
max_files = 256
max_age_sec = 604800

Complete Configuration Example

toml

[node]
role = "worker"
display_name = "worker-01"
data_dir = "~/.starweft-worker"
listen = ["/unix/~/.starweft-worker/mailbox.sock"]
log_level = "info"
 
[identity]
actor_key_path = "~/.starweft-worker/identity/actor_key"
 
[discovery]
seeds = ["/unix/~/.starweft-owner/mailbox.sock"]
auto_discovery = true
mdns = false
 
[p2p]
transport = "local_mailbox"
relay_enabled = true
direct_preferred = true
max_peers = 128
 
[ledger]
path = "~/.starweft-worker/ledger/node.db"
 
[openclaw]
enabled = true
bin = "openclaw"
timeout_sec = 3600
capability_version = "openclaw.execution.v1"
 
[compatibility]
protocol_version = "starweft/0.1"
bridge_capability_version = "openclaw.execution.v1"
allow_legacy_protocols = false
 
[owner]
max_retry_attempts = 8
retry_cooldown_ms = 250
retry_strategy = "rule_based"
 
[worker]
accept_join_offers = true
max_active_tasks = 1
 
[observation]
planner = "heuristic"
evaluator = "heuristic"
cache_snapshots = true
cache_ttl_sec = 30
 
[logs]
rotate_max_bytes = 1048576
max_archives = 5
 
[artifacts]
dir = "~/.starweft-worker/artifacts"
max_files = 256
max_age_sec = 604800