Quickstart Tutorial¶

This tutorial walks you through installing SynthOrg, starting the platform, and configuring your first company, in about 5 minutes.

What You Will Configure¶

You will configure a Solo Builder organisation: a lean two-agent team designed for rapid prototyping.

graph TD
    CEO["CEO<br/><small>visionary_leader</small>"]
    DEV["Full-Stack Developer<br/><small>rapid_prototyper</small>"]
    CEO --> DEV

By design, the CEO handles strategy and task decomposition while the Full-Stack Developer writes code and builds features. With a configured provider the runtime drives that execution (exercised today under deterministic e2e harnesses with a scripted provider); the steps below set up the company that runs it.

Prerequisites¶

• Docker Desktop (or Docker Engine + Docker Compose): install Docker
• An LLM provider API key: any provider supported by LiteLLM (e.g. a cloud provider or a local instance like Ollama)

Step 1: Install the CLI¶

curl -sSfL https://synthorg.io/get/install.sh | bash

irm https://synthorg.io/get/install.ps1 | iex

Verify the installation:

synthorg version

See the User Guide for alternative installation methods and CLI commands.

Step 2: Initialise¶

Run the interactive setup wizard:

synthorg init

The wizard's primary screen prompts for the infrastructure choices that shape the deployment:

1. Data directory: where SynthOrg stores its data (default: platform-appropriate path).
2. Database backend: Postgres or SQLite (interactive default: Postgres).
3. Message bus backend: NATS or the in-process internal bus (interactive default: NATS).
4. Fine-tuning: enable the optional fine-tuning toolchain.

The defaults above apply to the interactive wizard, which targets a production-style multi-node deployment. The non-interactive path (synthorg init with the required flags supplied, omitting --persistence-backend / --bus-backend) instead defaults to the single-node SQLite + internal bus pair, matching the programmatic DefaultState.

An Advanced settings section (collapsed by default) holds the backend API port (default: 3001), web dashboard port (default: 3000), the agent code sandbox toggle, and secret encryption; leave it at the defaults unless you need to change a port or the sandbox. Press the expander to reveal it, then Continue.

synthorg init generates the required secrets and writes the configuration automatically: SYNTHORG_JWT_SECRET, SYNTHORG_SETTINGS_KEY, and SYNTHORG_PAGINATION_CURSOR_SECRET are always written, and SYNTHORG_MASTER_KEY is generated when secret encryption is enabled (the default). Company setup (name, LLM provider, template) happens in the web dashboard after containers start (see Step 4).

Step 3: Start¶

synthorg start

This pulls container images (with automatic cosign signature verification), starts the backend and web dashboard, and waits for health checks to pass.

Check that everything is running:

synthorg status

You should see both containers (backend and web) reporting healthy.

Step 4: Explore the Dashboard¶

Open http://localhost:3000 in your browser.

On a fresh install with no admin user yet, the setup wizard first asks you to create an admin account (email and password). After the admin account exists, you choose a setup mode: pick Guided Setup (the Quick Setup path is described below). Guided Setup then steps through:

1. Select a template: choose Solo Builder (the minimal 2-agent template).
2. Add an LLM provider: enter your provider's API key. Local providers like Ollama are auto-detected.
3. Name your company: pick any name (e.g. "My First Org").
4. Review agents: the template populates the roster; tweak personalities and models if you want, or accept defaults.
5. Choose capabilities: enable or disable the optional platform capabilities for your organisation.
6. Pick a theme: light or dark.

Quick Setup is the abbreviated path (provider, company name, done). Use it when you want to land in the dashboard fastest and configure the rest later.

Once the wizard completes, the dashboard loads and you will see:

• Agents: the CEO and Full-Stack Developer, each with their personality and model assignment
• Organisation status: health indicators for the platform
• Task board: empty, ready to accept tasks

Step 5: Submit a Task¶

curl -X POST http://localhost:3001/api/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-jwt-token>" \
  -d '{
    "title": "Write a hello world script",
    "description": "Create a simple Python script that prints hello world",
    "type": "development",
    "project": "<project-id>",
    "created_by": "<agent-name>"
  }'

With a configured provider the agent runtime picks the task up and executes it (LLM + sandboxed tools under the safety spine), exercised today by deterministic e2e harnesses with a scripted provider. If you skip provider configuration the setup wizard blocks completion, and the task board rejects submissions until a runtime is configured. See the Roadmap for current status.

The Task Execution Flow¶

This is what submitting a task does end to end with a configured provider. The runtime is wired and exercised by deterministic e2e harnesses with a scripted provider; the same flow runs against a real LLM once you configure one.

sequenceDiagram
    participant You
    participant Engine
    participant CEO
    participant Dev as Full-Stack Developer
    participant LLM as LLM Provider

    You->>Engine: Create task
    Engine->>Engine: Route to agent (role-based)
    Engine->>CEO: Assign task
    CEO->>LLM: Analyze & decompose
    LLM-->>CEO: Plan
    CEO->>Dev: Delegate subtask
    Dev->>LLM: Execute (ReAct loop)
    LLM-->>Dev: Result
    Dev-->>Engine: Task completed
    Engine-->>You: Result available

1. Task created: the engine validates the task and queues it.
2. Task routed: a routing strategy matches the task to the best-suited agent.
3. Agent executes: the assigned agent uses its configured LLM in a ReAct loop.
4. Result returned: the completed task and its artifacts appear in the dashboard and API.

With a scripted provider this runs under the e2e harness today; with a real provider configured it runs against your chosen LLM.

Stop¶

When you are done:

synthorg stop

Your data persists in the synthorg-data Docker volume and will be available next time you run synthorg start.

Next Steps¶

• Company Configuration: customise every aspect of your organisation via YAML
• Agent Roles & Hierarchy: add more agents, define departments, configure personality
• Budget & Cost Control: set spending limits and auto-downgrade policies
• Deployment (Docker): production hardening and operations
• Roadmap: what is available now versus in active development