Skip to content
stoneforge

Demo Mode

Demo mode lets you try Stoneforge without any API keys or paid subscriptions. It configures all agents to use the opencode provider with the minimax-m2.5-free model — a free-tier model that requires no authentication.

Getting started with demo mode

  1. Install the Stoneforge CLI

    Terminal window
    npm install -g @stoneforge/smithy

  2. Initialize a workspace and enable demo mode

    Terminal window
    cd your-project
    sf init

    After initialization, enable demo mode from the dashboard Settings page or by setting demo_mode: true in .stoneforge/config.yaml. This configures all default agents (director, workers, steward) to use the free opencode/minimax-m2.5-free provider.

  3. Start the server and dashboard

    Terminal window
    sf serve

    The dashboard opens at http://localhost:3457.

  4. Start orchestrating

    Follow the same steps as the Quick Start — register additional agents, start the Director, and give it a goal. All agents will use the free model automatically.

What demo mode does

When demo mode is enabled:

  • All agents are configured to use the opencode provider with the minimax-m2.5-free model
  • No API keys are required — the model is free to use
  • The demo_mode: true flag is set in .stoneforge/config.yaml
  • Previous agent configurations are saved so they can be restored when you disable demo mode

Demo mode affects the provider and model settings for every agent in the workspace. All other Stoneforge features — task planning, dependency tracking, worktree isolation, auto-dispatch, merge stewards — work exactly the same.

Enabling and disabling demo mode

Via the dashboard

Once your workspace is running, you can toggle demo mode from the Settings page in the dashboard:

  1. Open the dashboard at http://localhost:3457
  2. Navigate to Settings
  3. Find the Demo Mode toggle
  4. Toggle it on to enable or off to disable

When you toggle demo mode on, all agents switch to opencode/minimax-m2.5-free. When you toggle it off, each agent’s previous provider and model are restored.

Via the config file

You can also edit .stoneforge/config.yaml directly:

.stoneforge/config.yaml
# Enable demo mode
demo_mode: true


# Disable demo mode
demo_mode: false

Limitations of the free model

The minimax-m2.5-free model is a free-tier model suitable for trying out Stoneforge, but it has limitations compared to production-grade models:

  • Smaller context window — may struggle with large codebases or complex tasks
  • Lower capability — less accurate code generation and reasoning compared to Claude, GPT-4, etc.
  • Rate limits — free-tier models may have lower rate limits than paid providers
  • Best for exploration — ideal for learning how Stoneforge works, not for production workloads

For production use, switch to a more capable provider like Claude Code or configure multiple providers for different agent roles.

Upgrading from demo mode

When you’re ready to use a production provider:

  1. Disable demo mode via the dashboard Settings toggle (this restores previous agent configs)

  2. Install your preferred provider CLI (e.g., npm install -g @anthropic-ai/claude-code)

  3. Authenticate with the provider (e.g., run claude to set up your API key)

  4. Reconfigure agents if needed:

    Terminal window
    sf agent register director --role director --provider claude-code
    sf agent register e-worker-1 --role worker --provider claude-code

API endpoints

Demo mode status and toggling are available via the REST API:

EndpointMethodDescription
/api/settings/demo-modeGETGet current demo mode status
/api/settings/demo-mode/enablePOSTEnable demo mode
/api/settings/demo-mode/disablePOSTDisable demo mode

The status response includes:

{
  "enabled": true,
  "provider": "opencode",
  "model": "minimax-m2.5-free",
  "savedConfigCount": 4
}

Next steps

Quick Start Follow the full getting-started workflow
Multi-Provider Support Learn about all supported providers
Installation Set up production providers