Production infrastructure for AI agents

Website · Documentation · Guides · Core · Template · Discord

systemprompt-api

Axum-based HTTP server and API gateway for systemprompt.io AI governance infrastructure. Exposes governed agents, MCP, A2A, OAuth, the Claude gateway, marketplace, sync, analytics, and admin endpoints behind a unified middleware stack with authentication, rate limiting, RBAC, content negotiation, and security headers.

Layer: Entry — application boundary. Part of the systemprompt-core workspace.

This crate exposes a public library surface (ApiServer, route routers, middleware extractors) consumed by entry/cli.

Overview

The Entry layer turns an AppContext into a running Axum server. Responsibilities:

• Route mounting — every domain crate's router is composed under one tree by services/server/routes.rs.
• Middleware stack — JWT, sessions, CORS, IP ban, rate limiting, throttling, bot detection, analytics emission, context extraction, content negotiation, security headers, and trailing-slash normalization.
• Gateway — proxies Claude API traffic with quota enforcement, safety filtering, OTel ingest, audit, and pricing capture.
• Static content — serves the prebuilt web frontend with ETag, SPA fallback, and per-route session handling.
• Server lifecycle — readiness probes, agent reconciliation, and scheduler bootstrap.

Source layout

src/
├── lib.rs                          # Re-exports: ApiServer, HealthChecker, ContextMiddleware, ServerConfig
├── models/
│   └── mod.rs                      # ServerConfig
├── routes/
│   ├── mod.rs
│   ├── wellknown.rs                # /.well-known/* (agent cards, OAuth metadata)
│   ├── marketplace.rs              # Marketplace catalog endpoints
│   ├── admin/                      # CLI gateway, keys
│   ├── agent/                      # A2A: artifacts, contexts (+ events, notifications, webhook), registry, tasks, responses
│   ├── analytics/                  # Event ingestion + SSE stream
│   ├── content/                    # Blog, query, link tracking
│   ├── engagement/                 # Engagement metrics
│   ├── gateway/                    # Claude gateway: auth, bridge (data, heartbeat, manifest, profile usage, whoami), messages, OTel
│   ├── mcp/                        # MCP server registry
│   ├── oauth/                      # OAuth2/OIDC: discovery, endpoints, clients, webauthn, wellknown, health
│   ├── proxy/                      # A2A and MCP request forwarding
│   ├── stream/                     # SSE for context updates
│   └── sync/                       # File and auth sync for offline-first clients
└── services/
    ├── mod.rs
    ├── validation.rs               # Cross-route validation helpers
    ├── gateway/                    # ClaudeGatewayService — audit, captures, parse, policy, pricing, protocol, quota, registry, safety, stream_tap
    ├── health/                     # HealthChecker, ProcessMonitor
    ├── middleware/
    │   ├── analytics/              # Bot/scanner detection + event emission
    │   ├── context/                # Context extraction with header/A2A extractors and header/payload sources
    │   ├── jwt/                    # Token validation + JWT context
    │   ├── negotiation/            # Accept-header content negotiation
    │   ├── session/                # Lifecycle and skip rules
    │   ├── auth.rs                 # Route-level auth gate
    │   ├── bot_detector.rs         # Bot fingerprinting
    │   ├── cors.rs
    │   ├── ip_ban.rs
    │   ├── rate_limit.rs
    │   ├── security_headers.rs
    │   ├── session.rs              # Session middleware entry
    │   ├── site_auth.rs            # Site-wide auth gate
    │   ├── throttle.rs
    │   ├── trace.rs
    │   └── trailing_slash.rs
    ├── proxy/                      # ProxyEngine: auth, backend transform, client pool, resolver, MCP session
    ├── server/
    │   ├── builder.rs              # ApiServer construction
    │   ├── discovery.rs            # Extension router discovery
    │   ├── health.rs               # Health endpoint (incl. portable disk usage)
    │   ├── health_detail.rs        # Detailed health payload
    │   ├── readiness.rs            # Readiness probe state
    │   ├── routes.rs / routes/     # Route tree, extension mount, protocol mount, static setup
    │   ├── runner.rs               # Server entry point (run_server)
    │   └── lifecycle/              # Agent reconciliation + scheduler bootstrap
    └── static_content/             # SPA fallback, homepage, static files (cache + responses), session handling

Route surface

Service surface

Usage

[dependencies]
systemprompt-api = "0.11.0"

use systemprompt_api::services::server::{run_server, setup_api_server};
use systemprompt_runtime::AppContext;

let ctx = AppContext::new().await?;
run_server(ctx, None).await?;

Configuration

The API server is configured through systemprompt-runtime::Config and the active profile:

• api_external_url — public URL advertised in discovery metadata.
• rate_limits — per-endpoint rate limit configuration.
• security.signing_key_path — RSA private key the in-process TokenAuthority uses to sign RS256 access tokens. The matching public set is published at /.well-known/jwks.json; systemprompt admin keys generate mints the keypair.
• security.trusted_issuers — additional issuer → JWKS URI entries consulted by the RFC 8693 token-exchange grant when validating non-self-issued subject tokens.
• oauth_at_rest_pepper — HMAC pepper (>= 32 chars, loaded via the secrets bootstrap) under which refresh-token ids and authorisation codes are stored as HMAC-SHA-256 digests.
• cors — allowed origins.
• paths.system — root used by static_content to locate prebuilt web assets.

Notes

• Handlers extract request data and delegate to domain services; no direct repository access.
• All routes are composed in services/server/routes.rs; extensions are discovered via services/server/discovery.rs.
• Middleware order is significant — see services/server/builder.rs.
• The gateway path mints a UUID v5 ContextId from GatewayConversationId; it does not read upstream x-context-id.
• Static content requires prebuilt web assets under the configured system path.

Dependencies

Internal crates

• systemprompt-runtime — application context and configuration
• systemprompt-oauth — authentication and session management
• systemprompt-agent — agent registry, A2A protocol, orchestration
• systemprompt-mcp — MCP server registry and proxy
• systemprompt-content — content repository and serving
• systemprompt-analytics — session and event tracking
• systemprompt-scheduler — background job execution
• systemprompt-marketplace — marketplace catalog
• systemprompt-ai — Claude gateway integrations
• systemprompt-database — connection pooling
• systemprompt-security — token extraction and validation
• systemprompt-users — user services and IP banning
• systemprompt-events — event broadcasting
• systemprompt-files — file system configuration
• systemprompt-extension — extension loading and routing
• systemprompt-config, systemprompt-loader, systemprompt-logging, systemprompt-models, systemprompt-identifiers, systemprompt-traits

External crates

• axum, tower, tower-http, tower_governor, governor — HTTP framework and middleware
• tokio, tokio-stream, async-stream, futures-util — async runtime
• reqwest — upstream HTTP client
• rmcp — MCP transport
• jsonwebtoken, webauthn-rs, bcrypt, ed25519-dalek — auth primitives
• opentelemetry-proto, prost — OTLP ingest
• flate2, tar — sync payload (de)compression
• sqlx — database access

License

BSL-1.1 (Business Source License). Source-available for evaluation, testing, and non-production use. Production use requires a commercial license. Each version converts to Apache 2.0 four years after publication. See LICENSE.

systemprompt.io · Documentation · Guides · Live Demo · Template · crates.io · docs.rs · Discord

Entry layer · Own how your organization uses AI.