Quick Start

Set up a local multi-node Starweft environment and submit your first vision.

This guide walks you through setting up a local three-node Starweft environment with a principal, owner, and worker.

Initialize Nodes

Create separate data directories for each role:

Initialize the principal node

bash

starweft init --role principal --data-dir ./demo/principal

Initialize the owner node

bash

starweft init --role owner --data-dir ./demo/owner

Initialize the worker node

bash

starweft init --role worker --data-dir ./demo/worker

The init command sets up the data directory structure and configures the default listen address based on your platform.

Create Identities

Each node needs an Ed25519 identity for message signing:

bash

starweft identity create --data-dir ./demo/principal
starweft identity create --data-dir ./demo/owner
starweft identity create --data-dir ./demo/worker

View each node's identity details:

bash

starweft identity show --data-dir ./demo/principal
starweft identity show --data-dir ./demo/owner
starweft identity show --data-dir ./demo/worker

Note the actor_id, node_id, and public_key values — you'll need them for peer registration.

Register Peers

Each node needs to know how to reach the others.

When using the local_mailbox transport (the default on Unix), register peers manually with peer add:

bash

# Register the owner with the principal
starweft peer add /unix/$(pwd)/demo/owner/mailbox.sock \
  --data-dir ./demo/principal \
  --actor-id <OWNER_ACTOR_ID> \
  --node-id <OWNER_NODE_ID> \
  --public-key <OWNER_PUBLIC_KEY>
 
# Register the worker with the owner
starweft peer add /unix/$(pwd)/demo/worker/mailbox.sock \
  --data-dir ./demo/owner \
  --actor-id <WORKER_ACTOR_ID> \
  --node-id <WORKER_NODE_ID> \
  --public-key <WORKER_PUBLIC_KEY>

Start the Nodes

Run each node in a separate terminal:

bash

# Terminal 1
starweft run --data-dir ./demo/principal
 
# Terminal 2
starweft run --data-dir ./demo/owner
 
# Terminal 3
starweft run --data-dir ./demo/worker

Submit a Vision

With all nodes running, submit a vision from the principal:

bash

starweft vision submit "Build a hello world REST API in Rust" \
  --data-dir ./demo/principal

The owner will decompose this vision into tasks and distribute them to available workers.

Monitor Progress

Check the status of your project:

bash

starweft status --data-dir ./demo/principal

View the task tree:

bash

starweft project task tree --data-dir ./demo/principal

Next Steps

Architecture

Understand how Starweft's P2P architecture works

Roles

Deep dive into the four node roles