Installation

systemprompt.io is self-hosted AI governance infrastructure — an embeddable Rust library you compile and keep. One binary, one PostgreSQL, four commands from git clone to governed inference.

The fastest path is the template repository: clone it, run one setup recipe, start the server.

Prerequisites

• Rust 1.75+ — install from rustup.rs
• Docker — runs the per-clone PostgreSQL container
• just — the command runner that drives setup (cargo install just or your package manager)
• Git
• jq / yq — used by the setup and demo scripts

rustc --version    # 1.75.0 or higher
docker --version
just --version

An API key for at least one AI provider (Anthropic, OpenAI, or Gemini). If you don't pass one, setup prompts you to pick a provider interactively.

Quick Start

git clone https://github.com/systempromptio/systemprompt-template
cd systemprompt-template
just setup-local            # prompts: pick a provider, enter its key
just start                  # serves governance + agents + MCP + admin on :8080

That's the whole flow. Visit http://localhost:8080 for the homepage and http://localhost:8080/admin/login for the admin dashboard.

What just setup-local does

One recipe performs the entire bootstrap, idempotently:

1. Writes your local profile to .systemprompt/profiles/local/ (server config, provider registry, secrets) via systemprompt admin setup
2. Writes a per-clone Docker Compose file and starts PostgreSQL 18 in a container
3. Builds the release binary
4. Runs database migrations (systemprompt infra db migrate)
5. Ensures the platform admin user exists (systemprompt admin bootstrap)
6. Generates the JWT signing key
7. Runs the publish pipeline (templates, CSS/JS bundles, prerendered content)

Re-running it is safe: an existing profile is reused, not overwritten.

Non-interactive setup

Pass provider keys as positional arguments; the first key becomes the default provider:

just setup-local <anthropic_key> [openai_key] [gemini_key] [http_port=8080] [pg_port=5432]

The port arguments let a second clone run side-by-side on the same machine:

just setup-local <anthropic_key> "" "" 8081 5433

Each clone gets its own Docker Compose project (derived from the repo path), so databases and volumes stay isolated.

Log In

Visit http://localhost:8080/admin/login. Login uses OAuth 2.0 Authorization Code with PKCE — there is no password form. Magic-link (email) sign-in and WebAuthn passkeys are also supported. See the Authentication documentation for the full flow.

For CLI and script access, mint a local admin session token:

systemprompt admin session login --profile local

Verify Installation

systemprompt infra services status   # API, agents, MCP servers
systemprompt infra db status         # database connection
systemprompt admin agents list       # configured agents

Discover the rest of the CLI with systemprompt --help — eight domains (core, infra, admin, cloud, analytics, web, plugins, build), each with its own --help.

What You Get

After installation, you have a complete running system on http://localhost:8080:

Component	Description
Governance pipeline	Every tool call passes scope check → secret scan → blocklist → rate limit, and every decision is audited to Postgres with a full trace chain.
A2A Agents	Out-of-the-box agent orchestration with Google's A2A protocol — discovery, capability negotiation, and secure cross-agent messaging.
MCP Servers	Production-ready MCP hosting with OAuth2 protection. Connect Claude Desktop, Claude Code, or any MCP client.
AI Gateway	An Anthropic-compatible /v1/messages endpoint that routes to your configured providers with per-request auditing.
Admin Dashboard	Server-rendered admin UI with analytics, logs, users, and configuration.
OAuth2/OIDC Server	Full authorization server with PKCE flows, WebAuthn passwordless auth, and user isolation.
CLI Control Plane	The same CLI that works locally also works in production. Every action auditable.

Extend and Customize

The template has three core directories:

.systemprompt/ — Profiles & Credentials

Generated by just setup-local, gitignored, one per developer/environment:

.systemprompt/
├── docker/local.yaml    # Per-clone PostgreSQL compose file
└── profiles/
    └── local/
        ├── profile.yaml # Server, paths, providers, security settings
        └── secrets.json # DATABASE_URL, API keys (encrypted at rest)

See the Configuration documentation for profile and secrets management.

services/ — Config as Code

All application configuration as YAML and Markdown. No Rust code here. Loaded at startup through services/config/config.yaml's explicit includes: list; unknown keys error loudly.

Directory	Purpose
services/agents/	AI agent definitions with system prompts and skills
services/mcp/	MCP server configurations
services/skills/	Reusable skill definitions for agents
services/content/	Blog posts, documentation (Markdown)
services/web/	Theme, branding, navigation
services/ai/	AI provider configuration
services/scheduler/	Background job scheduling
services/plugins/	Plugin binding descriptors

See the Services documentation for each service type.

extensions/ — Rust Crates

Rust crates compiled into your binary. Registration is compile-time via the inventory crate — no dynamic plugin loader.

extensions/
├── web/     # Web extension (pages, API routes, schemas, jobs)
└── mcp/     # MCP server extensions (tool servers), one crate each

Extensions implement traits from systemprompt-core and can add API routes, database schemas, background jobs, MCP servers, and CLI commands. See the Extensions documentation.

Other Install Channels

For hosted or production deploys, see the Deploy documentation — one page per channel, each with a quickstart and links to the maintained recipe in the template repository:

• Containers & clusters: GHCR image, Helm chart, binary curl | sh, Homebrew, Nix flake
• PaaS one-clicks: Railway, Render, Zeabur, Northflank, DigitalOcean
• Self-host panels: Coolify, Dokploy, Portainer, CapRover, CasaOS

The bridge client (systemprompt-bridge, for developer workstations connecting to a running gateway) has its own install docs for macOS, Windows (including Scoop), and Linux/headless in the same directory.

Database

PostgreSQL is the only external dependency. just setup-local provisions a per-clone Docker container automatically; to point at your own PostgreSQL instead (local install, Neon, Supabase, RDS), run systemprompt admin setup with --db-host/--db-port/--db-user/--db-password/--db-name, or edit your profile's secrets. See the Database Configuration documentation.

---

Related Resources

Skills:

• systemprompt core skills list — List available skills
• systemprompt core skills show <skill_id> — View skill details

For AI agents assisting with setup, read the CLAUDE.md file in the template repository — machine-readable instructions optimized for AI-assisted development.