Skip to main content
Prerequisites: Node.js 18+ installed. If you haven’t installed Stoneforge yet, see Installation.

​
Overview

In this quick start, you’ll:
  1. Initialize a Stoneforge workspace
  2. Start the server and web dashboard
  3. Register and start a Director agent
  4. Register Worker and Steward agents
  5. Give the Director a goal and watch agents execute tasks
This tutorial takes ~5 minutes and demonstrates the full orchestration loop.

​
Step 1: Install and Initialize

Install the CLI globally and initialize a workspace in your project: 
# Install the Stoneforge CLI
npm install -g @stoneforge/smithy

# Navigate to your project
cd your-project

# Initialize workspace
sf init
  • .stoneforge/ directory with config, database, and sync files
  • AGENTS.md context file for agents (if not already present)
  • Default operator entity (el-0000) in the database
  • Git ignore patterns for database files

​
Step 2: Start the Server

Launch the Stoneforge server and web dashboard: 
sf serve
The server starts on port 3457 and automatically opens the dashboard at: 
http://localhost:3457
Keep this terminal running. Open a new terminal for the remaining steps.
Stoneforge Dashboard

​
Step 3: Register a Director

The Director is your strategic planner. Register one via CLI or the dashboard: 
sf agent register director --role director
Output:
✓ Registered agent: director (el-abc123)
The Director’s agent ID (e.g., el-abc123) is displayed in the output. You’ll need this to start the agent.

​
Step 4: Start the Director

Start the Director agent session: 
sf agent start <director-id>
Replace <director-id> with the ID from the registration step.
The Director runs as a persistent session. It stays active and responds to messages until explicitly stopped.

​
Step 5: Register Workers

Workers execute tasks in parallel. Register multiple workers: 
# Register 3 ephemeral workers
sf agent register e-worker-1 --role worker
sf agent register e-worker-2 --role worker
sf agent register e-worker-3 --role worker
  • Ephemeral workers are auto-spawned by the dispatch daemon when tasks are ready. They execute one task and shut down.
  • Persistent workers are manually started by you for interactive work. They run sessions like the Director.
This quickstart uses ephemeral workers for automated execution.

​
Step 6: Register a Merge Steward

Stewards handle maintenance workflows. A merge steward reviews and merges completed work: 
sf agent register m-steward-1 --role steward --focus merge
The --focus merge flag tells the steward to handle merge review. Other focuses include docs (documentation) and recovery (stuck task cleanup).

​
Step 7: Start the Dispatch Daemon

The dispatch daemon watches for ready tasks and assigns them to idle workers: 
sf daemon start
Output: 
✓ Dispatch daemon started
The daemon runs in the background. Check its status with sf daemon status.

​
Step 8: Give the Director a Goal

Now communicate your goal to the Director. Use the Director Panel in the dashboard:
1

Open the Director Panel

Click the Director Panel toggle in the right sidebar (or press Ctrl+D).
2

Send a message

In the Director terminal, type your goal:
Build a new API endpoint for user authentication that supports OAuth login with Google and GitHub providers. Include unit tests.
Press Enter.
3

Watch the Director plan

The Director will:
  • Analyze your goal
  • Break it into a plan with tasks
  • Set priorities and dependencies
  • Report the plan back to you
Director Panel

​
Step 9: Watch Agents Work

As the Director creates tasks, the dispatch daemon assigns them to workers:
Go to Overview > Activity to see:
  • Live agent terminal output
  • Active sessions
  • Recent task completions

​
The Orchestration Loop in Action

​
Step 10: View Results

Once workers complete tasks and stewards merge them:
Go to Work > Merge Requests to see:
  • Completed work ready for review
  • Test results
  • Merge status (passed/failed)

​
Understanding What Happened

1

Planning

The Director received your goal and created a plan with multiple tasks, setting priorities and dependencies.
2

Dispatch

The dispatch daemon detected ready tasks (unblocked, unassigned) and assigned them to idle ephemeral workers.
3

Execution

Each worker:
  • Spawned in an isolated git worktree
  • Executed the assigned task
  • Committed and pushed changes
  • Marked the task as complete
4

Merge Review

The merge steward:
  • Ran the test command
  • Squash-merged on passing tests
  • Created fix tasks on failures
5

Loop

The daemon continued assigning remaining tasks until all were complete.

​
What’s Next?

Explore Examples

See real-world orchestration patterns

Customize Prompts

Tailor agent behavior for your workflow

Agent Roles Explained

Deep dive into Director, Worker, and Steward roles

CLI Reference

Full CLI command documentation

​
Common Operations

Stop the Director:
sf agent stop <director-id>
Stop all active agents:
sf agent list --status active | xargs -I {} sf agent stop {}

sf daemon stop
Agent logs are in .stoneforge/logs/:
tail -f .stoneforge/logs/director.log

sf agent list
Or filter by status:
sf agent list --status active
sf agent list --status idle

​
Troubleshooting

Check that:
  1. The dispatch daemon is running: sf daemon status
  2. Workers are registered: sf agent list --role worker
  3. Tasks are ready: sf task list --ready
If tasks are blocked, check dependencies:
sf task blocked
Verify the Director is running:
sf agent list --role director
Restart if needed:
sf agent stop <director-id>
sf agent start <director-id>
Check the merge steward status:
sf agent list --role steward
View failed tasks:
sf task list --status review
Manually review and fix merge conflicts, then re-run tests.

Build docs developers (and LLMs) love

Get started for freeTalk to us