Documentation

Technical documentation for systemprompt.io - an embedded Rust library for building production AI infrastructure

Getting Started

Deploy with the Helm chart

Install the systemprompt.io gateway on Kubernetes with the Helm chart, using bundled or external Postgres.

Deploy from GitHub Container Registry

Run the systemprompt.io gateway from the public GHCR image ghcr.io/systempromptio/systemprompt-template with docker compose or docker run on port 8080.

Deploy the gateway to Coolify

Deploy the systemprompt.io gateway on Coolify, a self-hostable Heroku-style panel, from a docker-compose service.

Deploy on Dokploy

Run the systemprompt.io gateway on Dokploy, a self-hostable PaaS, from a compose blueprint that provisions the gateway and Postgres.

Deploy on Portainer

Run the systemprompt.io gateway as a Portainer stack from an app template or a Git repository, with Postgres from the public GHCR image.

Deploy to Railway

Deploy the systemprompt.io gateway on Railway in one click: it provisions a managed Postgres, wires DATABASE_URL, sets HOST, and takes one AI provider key.

Deploy the gateway on Northflank

One-click stack template deploy of the systemprompt.io gateway on Northflank with a managed Postgres addon.

Install the gateway with Nix

Run, install, or build the systemprompt.io gateway from the repo's Nix flake, including a NixOS module.

Install the gateway with Homebrew

Install the systemprompt.io gateway from the systempromptio Homebrew tap on macOS or Linuxbrew, then run it in the background with brew services on port 8080.

Deploy the gateway to Render

Deploy the systemprompt.io gateway on Render from the render.yaml Blueprint with a managed free-tier Postgres and DATABASE_URL wired in, taking one AI key.

Deploy on CapRover

Run the systemprompt.io gateway on CapRover as a one-click app with a bundled Postgres from the GHCR image, one AI provider key, and managed HTTPS on 8080.

Deploy the gateway on Zeabur

Deploy the systemprompt.io gateway on Zeabur from the template marketplace with a bundled Postgres, an AI provider key, and a generated zeabur.app domain.

Deploy

Every supported deployment channel for the systemprompt.io gateway: container registries, Kubernetes, one-click PaaS templates, and self-host panels.

Install the gateway binary

Install the systemprompt.io gateway from GitHub Releases with a one-line installer or a manual signed tarball download.

Deploy on CasaOS

Run the systemprompt.io gateway on CasaOS in a home lab, with bundled Postgres from the public GHCR image.

Deploy the gateway on DigitalOcean

Deploy the systemprompt.io gateway on a single DigitalOcean 1-Click droplet with a bundled Postgres, an AI provider key set at first boot, and TLS on 8080.

Licensing

Understand how systemprompt.io licensing works: the core is BSL-1.1, the template is MIT and fully yours.

Installation

Clone the systemprompt-template and run just setup-local for a complete running Rust binary with governed AI, A2A agents, MCP servers, and an admin dashboard.

Coding Standards

Rust coding standards for systemprompt.io - idiomatic patterns, mandatory requirements, and anti-patterns to avoid

Getting Started

Clone the systemprompt.io template, run just setup-local with a provider key, then just start to serve governance, agents, MCP, and admin on port 8080.

Configuration

Cloud Credentials

Authenticate the CLI via just login OAuth, storing api_token and api_url in credentials.json. Tokens expire with the JWT; re-run login when they lapse.

Server Configuration

Configure host, port 8080, use_https, cors_allowed_origins, and the three api_server_url, api_internal_url, and api_external_url endpoints for the HTTP server.

Rate Limits

Throttle requests per endpoint (mcp_per_second 200, contexts 100, agents 20) with burst_multiplier and per-tier multipliers for admin, user, and anon.

Security Configuration

Set JWT issuer, audiences (web, api, a2a, mcp), and token lifetimes. Access defaults to 30 days (2592000s), refresh to 180 days in jwt_issuer config.

Paths Configuration

Set system, services, bin, web_path, and storage directories. Paths resolve relative to the profile; cloud profiles must start with /app. GeoIP is optional.

Runtime Configuration

Set environment (development, test, staging, production), log_level (quiet to debug), output_format (text, json, yaml), no_color, and non_interactive.

Database

Configure PostgreSQL database connection for systemprompt.io. One connection string is all you need.

Configuration & Credentials

How credentials management works in .systemprompt/ - sessions, tenants, profiles, secrets, and cloud deployment.

Code Sync

Synchronize configuration between local development and systemprompt.io Cloud. Push, pull, and resolve conflicts.

Docker Configuration

Docker serves two purposes in systemprompt.io: running PostgreSQL locally and deploying your application to production.

Sessions

CLI authentication state and profile switching. Sessions track which profile is active and authenticate your requests.

Profiles

Environment configurations for systemprompt.io. Each profile contains all settings needed to run in a specific environment.

Tenants

Isolated environments for systemprompt.io. Local tenants run on your machine, cloud tenants run on managed infrastructure.

Secrets & Credentials

Manage API keys, credentials, and sensitive configuration for local development and cloud deployments.

Custom Domains

Point a CNAME or apex A record at your tenant, then systemprompt cloud domain set provisions TLS automatically. Track pending_dns to active with domain status.

Deployment

Deploy AI agents to systemprompt.io Cloud with a single command. CI/CD integration, zero-downtime deployments, and rollback strategies.

Services

Claude Cowork on macOS

Install the systemprompt-cowork credential helper on macOS, apply the .mobileconfig payload via Jamf or Intune, and verify the sync. Covers notarisation, mTLS.

Claude Cowork on Windows

Install the Authenticode-signed systemprompt-cowork.exe, apply the HKCU Policies Claude registry policy via Intune or Group Policy ADMX, and verify the sync.

Claude Cowork Deployment

Deploy Claude Cowork against a self-hosted /v1/messages gateway. Covers the architecture, three auth tiers (PAT, session, mTLS), signed manifest, audit schema.

Gateway Service

Self-hosted /v1/messages inference gateway and Cowork integration. Routes across Anthropic, OpenAI, and Gemini with identity propagation and a signed audit log.

Database Service

Database access patterns in Rust code - connecting to PostgreSQL, using repositories, and accessing the pool in different contexts

Skills Service

Define reusable agent capabilities through skills. Skills provide tagged, discoverable actions that multiple agents can share.

Web Service

Reference for the web service that renders pages, manages templates, serves assets, and controls the entire presentation layer of a systemprompt.io application.

Files Service

Database-backed file storage with typed metadata, upload validation policies, identity-linked provenance, and stable /files serving for AI workloads.

Content Service

Manage blog posts, documentation, and legal pages with markdown authoring, YAML frontmatter, automatic indexing, and generated sitemaps, RSS feeds, llms.txt.

Services

Configure and manage the runtime components that power your systemprompt.io instance - agents, skills, MCP servers, content, AI, scheduled jobs, and web interface.

Users

Per-user isolation from day one with WHERE user_id scoped queries, a separate PostgreSQL database per deployment, roles, sessions, and scope enforcement.

MCP Service -- Host and Manage MCP Servers

Host production MCP servers with OAuth authentication, tool discovery, capability negotiation, and streamable HTTP transport for Claude Desktop and Claude Code.

AI Services

Configure AI providers in systemprompt.io. Supports Anthropic, OpenAI, and Google Gemini with streaming, web search grounding, image generation, smart routing.

Agent Services

Configure and orchestrate AI agents in systemprompt.io with A2A protocol support, skills-based capabilities, multi-agent workflows, and OAuth security scoping.

Scheduled Jobs

Run background jobs on cron schedules for content publishing, analytics aggregation, session cleanup, database maintenance, and custom automation tasks.

Config Service

The config service aggregates all service configurations into a unified hub, managing includes, global settings, and startup validation.

Authentication

OAuth2/OIDC authorization, WebAuthn passwordless login, magic link authentication, JWT token lifecycle, and session management built into every layer of systemprompt.io.

Analytics Service

Automatic tracking of AI costs, usage metrics, session engagement, content performance, and audit trails. Every request logged with full observability.

Workflows

Define once, execute anywhere. Skills and multi-agent orchestration provide YAML-based automation that both humans and AI agents can run through CLI, MCP, or scheduled jobs.

Guides

Connect MCP Servers

Connect Claude Code, ChatGPT, and other AI clients to your systemprompt MCP servers. OAuth-secured tool access with full audit trail.

Deploy as a Website

Deploy your systemprompt template to production with user authentication, custom domains, and SSL. Ship your AI agents to real users.

Guides

Step-by-step guides to get the most out of your systemprompt.io installation.

Talk to Your Agents

Send HTTP messages to your systemprompt agents and see them respond in real-time. Learn the CLI commands and HTTP endpoints for agent communication.

Extensions

MCP Skill Integration

Load reusable prompts from services/skills with SkillService, pass them as AiMessage::system to the AI service, and combine voice and content skills.

MCP Response Patterns

Build CallToolResult with human-readable content blocks, machine-readable structured_content JSON, the is_error flag, and meta references to artifacts.

MCP Tool Structure

Organize MCP tools in per-tool directories with mod, handler, and helpers files, derive schemas from schemars structs, and dispatch via handle_tool_call.

MCP Resources

Expose read-only data to MCP clients: implement list_resources, list_resource_templates, and read_resource, returning text, blobs, or rendered UI artifacts.

MCP Server AI Integration

Complete guide to integrating AI services (Gemini, Anthropic, OpenAI) into MCP servers with search grounding and artifact persistence.

Frontmatter Processor

Implement FrontmatterProcessor::process_frontmatter() to read raw YAML fields after ingestion and index them into your own extension tables via side effects.

Config Extension

Add a config namespace with config_prefix(), define a JSON Schema via config_schema(), and enforce rules in validate_config() returning ConfigError variants.

Page Prerenderer

Implement PagePrerenderer::prepare() to build static HTML at publish time for list and index pages, returning a PageRenderSpec with template and output path.

Typed Extensions

Compile-time-safe traits over ExtensionType constants for typed schema, API, job, provider, and config capabilities, erased to AnyExtension at runtime.

RSS & Sitemap Providers

Implement RssFeedProvider and SitemapProvider to emit RSS feeds and sitemap URL entries during the publish pipeline via feed_specs() and source_specs().

Template Data Extender

Implement TemplateDataExtender::extend() to make final edits to assembled template data, adding canonical URLs, OpenGraph tags, and JSON-LD after providers run.

Extension Builder

ExtensionBuilder validates dependencies at compile time using type-level lists and the Subset trait, then build() returns a TypedExtensionRegistry or error.

Extension Registration

Register extensions at compile time with the register_extension! macro, which submits an ExtensionRegistration factory to the inventory crate for discovery.

API Extension

Mount Axum routers with the router() method, wrap them in ExtensionRouter::new or public, set a base path, and avoid the reserved /api/v1 prefixes.

Asset Declaration

Declare CSS, JavaScript, fonts, and images via declares_assets() and required_assets(), returning AssetDefinition values copied from storage/files to web/dist.

Extension Initialization

Extensions wire into AppContext after discovery: schema install, migration run, router mount, and job registration run in dependency order before serving.

Extension Trait Reference

Reference for the Extension trait: metadata() is the only required method, with defaults for schemas(), router(), jobs(), providers, roles, and web rendering.

Provider Extension

Add AI capabilities via ProviderExtensionTyped: return LlmProvider with chat() and stream_chat(), plus ToolProvider list_tools() and call_tool().

Schema Extension

Add database tables with schemas() using SchemaDefinition::new and include_str, evolve them with versioned migrations(), and order execution by dependencies().

Job Extension

Add background tasks with the jobs() method, implement the Job trait's execute(), set a 6-field cron schedule, and run them via systemprompt infra jobs.

Error Handling

Two error types drive extension loading: LoaderError for dependency, schema, migration, and path failures, and ConfigError for configuration validation.

Content Data Provider

Implement ContentDataProvider::enrich_content() to add computed fields, related content, and database lookups to content items before page data runs.

Extension Discovery

ExtensionRegistry::discover() collects inventory registrations, instantiates factories, validates dependencies, and sorts topologically with cycle detection.

Extension Dependencies

Declare load order with dependencies() returning extension IDs, validated at startup with cycle detection, or check typed Deps at compile time via the builder.

Component Renderers

Implement ComponentRenderer with component_id(), variable_name(), and render() to build HTML fragments like cards and navigation for template variables.

Page Data Providers

Implement PageDataProvider::provide_page_data() to supply TITLE, DESCRIPTION, DATE, and every other Handlebars template variable the generator core does not.

CLI Extensions

Build standalone CLI extensions for custom commands, external integrations, and utility tools that agents can execute via subprocess.

Library Extensions

Build library extensions that compile into the main binary: API routes, database schemas, background jobs, and providers.

MCP Extensions

Build standalone MCP server extensions that expose tools for AI agents via the Model Context Protocol.

Extensions and Scoped Permissions

How systemprompt.io extensions work across library, web, MCP, and CLI domains, and how scoping enforces per-agent, per-tool authorization via OAuth2 and roles.

Web Extensions

Build web extensions that supply all template variables, HTML fragments, static pages, RSS feeds, and sitemap entries while the generator core only coordinates.