Configuration

Customize Starweft behavior with TOML configuration files.

This guide explains the structure and key settings of Starweft's TOML configuration file.

Configuration File Location

The configuration file is config.toml inside the data directory.

Platform	Default Path
macOS / Linux	`~/.starweft/config.toml`
Windows	`%LOCALAPPDATA%\starweft\config.toml`

If you specify the data directory with the --data-dir option, the config.toml inside that directory will be used.

Viewing and Validating Configuration

`config show`

Displays the current configuration. Secret values are automatically masked.

bash

starweft config show --data-dir ~/.starweft

Output in JSON format:

bash

starweft config show --data-dir ~/.starweft --json

`config validate`

Validates the configuration file and reports errors and warnings.

bash

starweft config validate --data-dir ~/.starweft

Items validated:

Listen address format
Data directory existence
Identity key file existence and permissions
Protocol version and schema version compatibility
OpenClaw binary existence
Match between capability_version and bridge_capability_version

Configuration Sections Overview

plaintext

config.toml
├── [node]           — Basic node settings
├── [identity]       — Key file paths
├── [discovery]      — Peer discovery, mDNS, registry
├── [p2p]            — Transport settings
├── [ledger]         — SQLite database path
├── [openclaw]       — OpenClaw bridge settings
├── [compatibility]  — Protocol version
├── [owner]          — Owner role-specific settings
├── [worker]         — Worker role-specific settings
├── [observation]    — Planning and evaluation engine
├── [logs]           — Log rotation
└── [artifacts]      — Artifact storage settings

`[node]` Section

Basic node settings.

toml

[node]
role = "owner"
display_name = "owner-node"
data_dir = "~/.starweft"
listen = ["/unix//home/user/.starweft/mailbox.sock"]
log_level = "info"

Field	Type	Description
`role`	string	Node role: principal / owner / worker / relay
`display_name`	string	Display name for the node
`data_dir`	string	Data directory path
`listen`	string[]	List of listen addresses
`log_level`	string	Log level: trace / debug / info / warn / error

Listen Address Format

Transport	Format	Example
Unix socket	`/unix/<path>`	`/unix//home/user/.starweft/mailbox.sock`
TCP	`/ip4/<addr>/tcp/<port>`	`/ip4/0.0.0.0/tcp/9100`
IPv6 TCP	`/ip6/<addr>/tcp/<port>`	`/ip6/::1/tcp/9100`

`[identity]` Section

Specifies the paths to Ed25519 key files.

toml

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

Field	Type	Description
`actor_key_path`	string?	Path to the Ed25519 private key used for message signing
`stop_authority_key_path`	string?	Path to the key used for signing stop orders (principal only)

`[discovery]` Section

Settings for peer discovery and registry.

toml

[discovery]
seeds = ["/ip4/192.168.1.20/tcp/9100/p2p/12D3Koo..."]
auto_discovery = true
mdns = false
registry_url = ""
registry_ttl_sec = 300
registry_heartbeat_sec = 60

Field	Type	Description
`seeds`	string[]	Multiaddresses of seed peers to connect to at startup
`auto_discovery`	bool	Automatic exchange of CapabilityQuery/Advertisement (default: true)
`mdns`	bool	Automatic discovery on the local network via mDNS (default: false)
`registry_url`	string?	URL of the peer registry server
`registry_ttl_sec`	u64	TTL for registry registration in seconds (default: 300)
`registry_heartbeat_sec`	u64	Heartbeat interval to the registry in seconds (default: 60)
`registry_shared_secret`	string?	Shared secret for registry authentication
`registry_shared_secret_env`	string?	Environment variable name to read the shared secret from

`[p2p]` Section

Transport type and connection settings.

toml

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

Field	Type	Description
`transport`	string	local_mailbox (Unix default) or libp2p (Windows default)
`relay_enabled`	bool	Allow communication via relay nodes (default: true)
`direct_preferred`	bool	Prefer direct connections (default: true)
`max_peers`	u16	Maximum number of peers (default: 128)

`[openclaw]` Section

OpenClaw bridge settings. Used on Worker nodes.

toml

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

Field	Type	Description
`enabled`	bool	Enable the OpenClaw bridge (default: false)
`bin`	string	Path to the OpenClaw binary (default: openclaw)
`working_dir`	string?	Working directory for the subprocess
`timeout_sec`	u64	Execution timeout in seconds (default: 3600)
`capability_version`	string	Capability identifier (default: openclaw.execution.v1)

`[compatibility]` Section

Protocol version and schema version settings.

toml

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

Field	Type	Description
`protocol_version`	string	Message protocol version
`schema_version`	string	SQLite schema version
`bridge_capability_version`	string	OpenClaw bridge capability version
`allow_legacy_protocols`	bool	Allow older protocol versions (default: false)

`[owner]` Section

Owner role-specific settings. Controls retry behavior when tasks fail.

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"

Field	Type	Description
`max_retry_attempts`	u64	Maximum number of retry attempts (default: 8)
`retry_cooldown_ms`	u64	Interval between retries in milliseconds (default: 250)
`retry_strategy`	string	Retry strategy: rule_based (default: rule_based)
`retry_rules`	array	Array of rules mapping error patterns to retry actions

Retry Actions

Action	Description
`retry_same_worker`	Retry on the same Worker
`retry_different_worker`	Retry on a different Worker
`no_retry`	Do not retry

`[worker]` Section

Worker role-specific settings.

toml

[worker]
accept_join_offers = true
max_active_tasks = 1

Field	Type	Description
`accept_join_offers`	bool	Automatically accept JoinOffers (default: true)
`max_active_tasks`	u64	Number of tasks that can run concurrently (default: 1)

`[observation]` Section

Task planning and evaluation engine settings.

toml

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

Field	Type	Description
`cache_snapshots`	bool	Cache snapshots (default: true)
`cache_ttl_sec`	u64	Cache time-to-live in seconds (default: 30)
`max_planned_tasks`	usize	Maximum number of tasks generated from a single vision (default: 6)
`min_task_objective_chars`	usize	Minimum character count for task objectives (default: 48)
`planner`	string	heuristic / openclaw / openclaw_worker (default: heuristic)
`evaluator`	string	heuristic (default: heuristic)
`planner_bin`	string?	Binary path for the openclaw planner
`planner_working_dir`	string?	Working directory for the planner
`planner_timeout_sec`	u64	Planner timeout in seconds (default: 120)
`planner_capability_version`	string	Planner capability version (default: openclaw.plan.v1)
`planner_fallback_to_heuristic`	bool	Fall back to heuristic when the OpenClaw planner fails (default: true)

`[logs]` Section

Log rotation settings.

toml

[logs]
rotate_max_bytes = 1048576
max_archives = 5

Field	Type	Description
`rotate_max_bytes`	u64	Maximum log file size in bytes (default: 1048576 = 1MB)
`max_archives`	usize	Number of archive files to retain (default: 5)

`[artifacts]` Section

Task artifact storage settings.

toml

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

Field	Type	Description
`dir`	string	Directory for storing artifacts
`max_files`	usize	Maximum number of stored files (default: 256)
`max_age_sec`	u64	Maximum retention period for artifacts in seconds (default: 604800 = 7 days)

Recommended Settings by Role

Principal

toml

[node]
role = "principal"
log_level = "info"
 
[identity]
actor_key_path = "~/.starweft/identity/actor_key"
stop_authority_key_path = "~/.starweft/identity/stop_authority_key"

The principal only submits visions and issues stop orders. stop_authority_key_path is required only for the principal role.

Owner

toml

[node]
role = "owner"
 
[owner]
max_retry_attempts = 8
retry_cooldown_ms = 250
 
[observation]
planner = "heuristic"
max_planned_tasks = 6
cache_snapshots = true

The owner is responsible for task decomposition, distribution, and evaluation. Adjust max_planned_tasks based on the complexity of the vision.

Worker

toml

[node]
role = "worker"
 
[openclaw]
enabled = true
bin = "/usr/local/bin/openclaw"
timeout_sec = 3600
 
[worker]
accept_join_offers = true
max_active_tasks = 1

The worker is responsible for task execution. Adjust max_active_tasks based on available machine resources.

Relay

toml

[node]
role = "relay"
listen = ["/ip4/0.0.0.0/tcp/9300"]
 
[p2p]
transport = "libp2p"

The relay only forwards messages. Identity and OpenClaw configuration are not required.

Common Configuration Scenarios

Single-Machine Development Environment

toml

[p2p]
transport = "local_mailbox"
 
[discovery]
mdns = false

When running multiple nodes on the same machine, specify a different --data-dir for each node and use Unix sockets for communication.

Multi-Machine LAN Environment

toml

[p2p]
transport = "libp2p"
 
[discovery]
mdns = true
auto_discovery = true

Nodes on the same LAN are automatically discovered via mDNS.

Distributed Environment Over the Internet

toml

[p2p]
transport = "libp2p"
relay_enabled = true
 
[discovery]
mdns = false
seeds = ["/ip4/203.0.113.10/tcp/9300/p2p/12D3Koo..."]

Nodes behind NAT communicate through a relay. Disable mDNS in this scenario.

Security Notes

Configuration files are saved with 0600 permissions (read/write for owner only)
It is recommended to specify registry_shared_secret via an environment variable (registry_shared_secret_env)
config show automatically masks secret values as <redacted>
On Windows, files are given the hidden attribute and ACLs restrict access to the current user only

Next Steps

Multi-Machine Setup

Distributed node configuration with libp2p transport and mDNS

OpenClaw Integration

Detailed OpenClaw bridge configuration

Configuration Reference

Complete list of all configuration options