Skip to content

User Guide

How to run SynthOrg.

Prerequisites

Quick Start (CLI)

The recommended way to run SynthOrg is via the CLI:

# Install CLI (Linux/macOS)
curl -sSfL https://synthorg.io/get/install.sh | bash

# Set up and start
synthorg init     # Interactive setup wizard
synthorg start    # Verify + pull images + start containers
synthorg status   # Show container health and versions

synthorg start (and synthorg update) automatically verifies container image cosign signatures and SLSA provenance before pulling. If verification fails (e.g. in an air-gapped environment without access to Sigstore infrastructure), pass --skip-verify or set SYNTHORG_SKIP_VERIFY=1.

The web dashboard is at http://localhost:3000 (default port).

Other CLI commands: synthorg stop, synthorg logs, synthorg update, synthorg doctor, synthorg uninstall, synthorg backup, synthorg wipe, synthorg cleanup, synthorg config, synthorg version. When updating, the CLI re-launches itself after binary replacement so the remaining steps (compose refresh, image pull) use the new version. If the compose template has structural changes (new environment variables, hardening tweaks), the diff is shown for approval before applying; version comment and image reference updates are applied automatically.

To automatically clean up old container images after updates (keeping only the current and previous version), run synthorg config set auto_cleanup true. Use synthorg config get <key> to retrieve a single configuration value (e.g., synthorg config get channel).

To opt in to pre-release builds (dev channel), run synthorg config set channel dev. Dev channel builds are created on every push to main between stable releases and include Docker images, CLI binaries, cosign signatures, and SLSA provenance. To switch back: synthorg config set channel stable.

Quick Start (Docker Compose -- manual)

For development or if you prefer manual Docker Compose:

git clone https://github.com/Aureliolo/synthorg
cd synthorg
cp docker/.env.example docker/.env
docker compose -f docker/compose.yml up -d

Containers

Container Image Description
backend ghcr.io/aureliolo/synthorg-backend Python API server (Litestar). 3-stage build, Chainguard distroless runtime (no shell), runs as non-root (UID 65532).
web ghcr.io/aureliolo/synthorg-web Nginx + React 19 dashboard (shadcn/ui + Tailwind CSS). SPA routing, proxies API and WebSocket requests to backend, serves embedded MkDocs documentation at /docs/.

Environment Variables

Configuration is in docker/.env (copy from docker/.env.example):

Variable Default Description
SYNTHORG_JWT_SECRET (required) JWT signing secret. Generated by synthorg init. Must be >= 32 characters.
SYNTHORG_SETTINGS_KEY (required) Fernet encryption key for sensitive settings at rest. Generated by synthorg init. Must be a valid Fernet key (32 bytes, URL-safe base64).
SYNTHORG_DB_PATH /data/synthorg.db SQLite database path (inside container).
SYNTHORG_MEMORY_DIR /data/memory Agent memory storage directory (inside container).
SYNTHORG_PERSISTENCE_BACKEND sqlite Persistence backend for operational data.
SYNTHORG_MEMORY_BACKEND mem0 Memory backend for agent memory.
BACKEND_PORT 3001 Host port for the backend API.
WEB_PORT 3000 Host port for the web dashboard.
DOCKER_HOST (unset) Docker socket for agent code execution sandbox (optional).

First-Run Setup

After the containers are running, open the web dashboard at http://localhost:3000. On a fresh install, the setup wizard will appear automatically. You first choose a setup mode:

  • Guided Setup (recommended) -- walks through every configuration step.
  • Quick Setup -- sets a company name, adds a provider, and completes. Everything else can be configured later in Settings.

Guided Setup steps:

  1. Account (conditional) -- create the first admin user. This step only appears when no admin account exists yet.
  2. Template -- choose a company template. Templates are displayed in a searchable grid with category and size filters, grouped into Recommended and Other sections. Each card shows structural metadata (agent count, departments, autonomy level, workflow). Side-by-side comparison is available.
  3. Company -- name your synthetic organization, set a description, choose a display currency, and select a model tier profile (Economy, Balanced, or Premium).
  4. Providers -- configure LLM providers. Local providers (e.g. Ollama) are auto-detected with a re-scan button; additional providers can be added via the full provider form supporting API key, subscription, and custom configurations. Model discovery runs automatically after adding a provider.
  5. Agents -- customize agent names, personality presets, and model assignments. Agents are pre-populated from the selected template with models matched to configured providers.
  6. Theme -- set UI preferences including color palette, typography, layout density, animation level, and sidebar position.
  7. Complete -- review a summary of your configuration and launch the organization.

The backend validates that a company and at least one provider exist before allowing setup to finish. Agents are optional (Quick Setup skips agent configuration). Steps are completed sequentially -- a later step only appears done if all prior steps are also complete. Completed steps show a summary and can be revisited via the step indicator. After completing the wizard, the dashboard appears and the setup wizard is not shown again.

To start fresh, use synthorg wipe (offers an interactive backup, wipes all data, and optionally restarts with a clean slate to re-open the setup wizard) or delete the api.setup_complete setting via the settings API.

Active Development

SynthOrg is under active development. The web dashboard is available for monitoring and managing the organization. Templates and some features described here may evolve. Check the GitHub repository for current status.

Templates

Choose a pre-built organization template to get started quickly:

Template Description
solo_founder Solo builder with full autonomy
startup CEO + small engineering team
dev_shop Engineering squad with quality gates
product_team Product-focused studio with design
agency Project manager + specialists
full_company Enterprise org with all departments
research_lab Lead researcher + research assistants
consultancy Client-facing advisory and delivery
data_team Analytics and ML-focused data team

Templates are selected through the dashboard during the setup wizard.

Stop

docker compose -f docker/compose.yml down

Next Steps