Sovereign

Sovereign is a modular, self-hostable workspace runtime for running personal or organisational software under one roof. It provides the shared platform pieces applications need — authentication, data access, email, and UI — while allowing installable plugins to run as first-class applications.

The plugin system is the core product. Sovereign acts as the host, giving each plugin a place in the same workspace while sharing one login, one database, and one design system. It is open source, privacy-first, and designed to be fully owned by the person or organisation running it.

Features

• Plugin-first runtime — plugins install into the platform as native applications with their own routes and a shared workspace shell.
• One account, one workspace — one account system, role-based administration, and a Console for managing users and installed plugins.
• Self-hostable by default — deploy on a single machine with Docker Compose, using SQLite by default or PostgreSQL when needed.
• Privacy-first ownership — run your own instance, control your own data, and keep the deployment scoped to the people who use it.
• Developer-ready platform — an installable PWA, typed SDK, and shared design system for building plugins that fit cleanly into the runtime. Browse the live component and token reference at sovereignfs.github.io/storybook.

Quick start

Requirements: Docker with Compose, or Node 24.x + pnpm for local development.

Run with Docker

git clone https://github.com/sovereignfs/sovereign.git
cd sovereign
cp .env.example .env          # set AUTH_SECRET and SOVEREIGN_ADMIN_KEY
docker compose up --build

Open http://localhost:3000 — the first user to register becomes the platform admin. Full instructions, env vars, and production/Postgres setup are in docs/self-hosting.md.

Develop locally

pnpm install
cp .env.example .env          # fill in AUTH_SECRET + SOVEREIGN_ADMIN_KEY
pnpm dev                      # runtime on :3000, auth on :3001

The sv CLI wraps common tasks: pnpm sv <command> (dev, build, generate, plugin add/remove, …).

Monorepo layout

apps/auth/        better-auth identity server (the only separate Next.js app)
packages/
  sdk/            @sovereignfs/sdk — published plugin↔platform contract
  ui/             @sovereignfs/ui — published design system
  db/             Drizzle client factory + schema (SQLite/Postgres)
  manifest/       manifest schema + validation
  mailer/         SMTP abstraction
  tsconfig/       shared TypeScript configs
runtime/          the platform shell: middleware, plugin host, SDK bridge
plugins/          built-in platform plugins (console, launcher, account)
registry/         public plugin index (plugins.json) + submission process
scripts/          install-plugins, generate-registry, dev orchestrator
bin/sv            the sv CLI

Documentation

• Self-hosting — deployment, configuration, operations, and production setup. For VPS deployments, see the sovereign-infra template (operator-owned Caddy + Docker + age-encrypted secrets + GitHub Actions CI/CD).
• Plugin development — SDK usage, plugin structure, manifests, routing, and runtime integration.
• SDK stability — the @sovereignfs/sdk semver policy and which parts of the surface are stable vs experimental.
• Architecture — platform boundaries, package layout, and how the runtime, plugins, auth, and data layers connect.
• Repository map — canonical list of the primary, plugin, docs, Storybook, infra, and legacy repositories in the Sovereign project.
• Security — threat model, the no-telemetry guarantee, security headers/CSP, and a self-hoster hardening checklist.
• Design system — shared UI tokens, components, and conventions for platform and plugin interfaces. Live component reference: sovereignfs.github.io/storybook.
• Upgrade guide — versioned changes, migration notes, and compatibility guidance.
• Troubleshooting — known dev-server quirks, 404 patterns, license token issues, and Docker gotchas.
• Real-device PWA testing — agent-assisted iOS/Android installed-PWA checks, HTTPS tunnels, LAN URL tradeoffs, and device checklist.
• Contributing — development workflow, local verification hooks, draft-PR/CI behavior, release tag conventions, and contribution expectations.
• RFCs — design proposals with a status-at-a-glance index; the individual files hold motivation, design, and impact.
• Concept · Plan · SRS and the roadmap — product specification, scope, and the milestone (Pre-v1 / v1) build plan.

License

Sovereign is licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later).
See LICENSE for the full text.