Skip to main content
Section navigation

Configuration & Credentials

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

On this page

systemprompt.io uses a layered credential system stored in the .systemprompt/ directory. This system manages authentication, multi-tenancy, and environment-specific configuration so you can run the same project in development, staging, and production with complete isolation.

How It Works

The credential system follows a clear hierarchy. Understanding this flow is essential for managing systemprompt.io effectively.

Cloud Login creates your authentication token via systemprompt cloud auth login. It is optional for local development and enables access to cloud features like deploy and sync.

Tenants are isolated environments that own databases and configuration. You might have a local tenant for development and a cloud tenant for production. Each tenant is completely separate.

Profiles are environment configurations within a tenant. A profile contains all the settings needed to run systemprompt.io: database connection, API keys, server configuration, and runtime options.

Sessions track your active CLI state. When you run commands, the session determines which profile is active and authenticates your requests.

The Credential Flow

Cloud Login (credentials.json)
    │
    └── Authenticates you with systemprompt.io Cloud
            │
            ▼
Tenants (tenants.json)
    │
    └── Isolated environments (local or cloud)
            │
            ▼
Profiles (profiles/<name>/)
    │
    └── Environment config + secrets for each tenant
            │
            ▼
Sessions (sessions/index.json)
    │
    └── Active CLI state, determines which profile is used

Directory Structure

The .systemprompt/ directory contains all credential and configuration files. These files are gitignored by default to protect sensitive data.

.systemprompt/
├── credentials.json              # Cloud authentication (OAuth token)
├── tenants.json                  # Registry of all tenants
├── sessions/
│   └── index.json               # Active session state per tenant
├── profiles/
│   ├── local/
│   │   ├── profile.yaml         # Environment configuration
│   │   └── secrets.json         # API keys, DATABASE_URL (gitignored)
│   └── production/
│       ├── profile.yaml
│       └── secrets.json
└── docker/
    └── local.yaml               # Per-clone PostgreSQL container

Quick Start

Get running with systemprompt.io in two steps.

1. Set Up the Local Profile

just setup-local
# or non-interactive:
just setup-local <anthropic_key> [openai_key] [gemini_key] [http_port=8080] [pg_port=5432]

This writes profiles/local/ (profile.yaml and secrets.json), starts a per-clone Docker PostgreSQL, runs database migrations, bootstraps the admin user, and generates the JWT signing key. With no key argument, the CLI prompts for which AI provider to use.

2. Start Services

just start      # Serve on :8080

Your session is now active. All CLI commands use the local profile by default. For cloud features, authenticate separately with systemprompt cloud auth login.

Bootstrap Sequence

systemprompt.io follows a strict 5-stage initialization sequence:

1. ProfileBootstrap   →  Load profile.yaml, validate
2. SecretsBootstrap   →  Load secrets (JWT, DATABASE_URL, API keys)
3. CredentialsBootstrap → Load cloud credentials (optional)
4. Config             →  Aggregate into runtime config
5. AppContext         →  Initialize database, services

Configuration Sections

Core Configuration

Section Purpose
Profiles Environment-specific settings
Secrets API keys and sensitive credentials
Credentials Cloud API authentication
Database PostgreSQL connection setup

Profile Sub-Configuration

Section Purpose
Server Host, port, API URLs, CORS
Security JWT issuer, token expiration
Paths Directory layout
Runtime Environment, logging, output format
Rate Limits API throttling

Multi-Tenancy & Cloud

Section Purpose
Tenants Isolated environments (local and cloud)
Sessions CLI authentication state and profile switching
Sync Push/pull configuration between environments
Deployment Deploy to systemprompt.io Cloud
Docker Container configuration for local and cloud
Domains Custom domain setup with TLS

Cloud Features

systemprompt.io Cloud is managed infrastructure for AI agents. Deploy with a single command, sync configuration between environments, and use custom domains with automatic TLS.

Feature Description
One-Command Deploy systemprompt cloud deploy pushes configuration to production
Managed Database Managed PostgreSQL provisioned with your tenant
Custom Domains Use your domain with automatically provisioned TLS certificates
Code Sync Push and pull configuration between local and cloud (cloud sync push / cloud sync pull)

Licensing

Local evaluation is free under the BSL-1.1 license published in the systemprompt-core repository. Production use and cloud hosting are commercial arrangements agreed directly: contact ed@systemprompt.io. See Licensing.

Profile Priority

When you run a CLI command, systemprompt.io determines which profile to use in this order:

  1. --profile flag on the command
  2. SYSTEMPROMPT_PROFILE environment variable
  3. Active session from sessions/index.json
  4. Default profile

This lets you override the active profile for individual commands without switching sessions.

Git Ignore

All sensitive files are automatically gitignored:

.systemprompt/credentials.json
.systemprompt/tenants.json
.systemprompt/sessions/
.systemprompt/profiles/*/secrets.json

Profile configuration (profile.yaml) can be committed since it contains no secrets. This makes it easy to share environment settings across a team while keeping credentials private.