Profiles

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

Last updated:

On this page

Profiles are environment configurations stored in .systemprompt/profiles/<name>/. Each profile contains everything needed to run systemprompt.io in a specific environment: database connection, server settings, security configuration, and API keys.

Profiles and Tenants

Every profile belongs to exactly one tenant. The tenant provides the database and isolation boundary, while the profile configures how you interact with that tenant.

# .systemprompt/profiles/local/profile.yaml
cloud:
  tenant_id: local_19bff27604c    # This profile belongs to this tenant

You can have multiple profiles per tenant. For example, a local tenant might have:

local - Standard development settings
local-test - Configured for running tests
local-verbose - Extra logging for debugging

Each profile points to the same tenant but with different configuration.

Profile Directory

Each profile has its own directory containing configuration and secrets:

.systemprompt/
├── docker/                # Docker compose files (local tenants)
│   ├── local.yaml
│   └── shared.yaml
└── profiles/
    ├── local/
    │   ├── profile.yaml   # Configuration (can be committed)
    │   ├── secrets.json   # API keys, DATABASE_URL (gitignored)
    │   └── signing_key.pem  # JWT signing key (gitignored)
    └── production/
        ├── profile.yaml
        └── secrets.json

Profile Structure

A complete profile configuration:

# .systemprompt/profiles/local/profile.yaml
name: local
display_name: "Local Development"
target: local                    # "local" or "cloud"

# Site identity
site:
  name: "My Project"
  github_link: "https://github.com/org/repo"

# Database configuration
database:
  type: postgres
  external_db_access: false      # Allow connections from outside Docker

# Server settings
server:
  host: "127.0.0.1"
  port: 8080
  api_server_url: "http://localhost:8080"
  api_internal_url: "http://localhost:8080"
  api_external_url: "http://localhost:8080"
  use_https: false
  cors_allowed_origins:
    - "http://localhost:8080"
    - "http://localhost:5173"

# File paths
paths:
  system: "/path/to/project"
  services: "/path/to/project/services"
  bin: "/path/to/project/target/release"
  storage: "/path/to/project/storage"

# Security settings
security:
  jwt_issuer: "systemprompt-local"
  jwt_access_token_expiration: 2592000    # 30 days
  jwt_refresh_token_expiration: 15552000  # 180 days
  jwt_audiences: ["web", "api", "a2a", "mcp"]
  signing_key_path: signing_key.pem

# Rate limiting
rate_limits:
  disabled: true                         # Disable for development

# Runtime configuration
runtime:
  environment: development               # development, test, staging, production
  log_level: verbose                     # quiet, normal, verbose, debug
  output_format: text                    # text, json, yaml
  no_color: false

# Tenant linkage
cloud:
  tenant_id: local_19bff27604c
  validation: skip                       # strict, warn, skip

# Secrets reference
secrets:
  secrets_path: secrets.json
  validation: warn
  source: file

Configuration Sections

Database

Database connection is configured in the profile but the actual DATABASE_URL is stored in secrets.

database:
  type: postgres
  external_db_access: false    # Allow connections from outside Docker

See Database for connection string formats.

Server

Controls how the HTTP server runs. See Server Configuration for details.

server:
  host: "127.0.0.1"                            # Bind address
  port: 8080                                   # Listen port
  api_server_url: "http://localhost:8080"      # Primary API URL
  api_internal_url: "http://localhost:8080"    # Internal service URL
  api_external_url: "http://localhost:8080"    # Public/external URL
  use_https: false                             # Enable for production
  cors_allowed_origins:
    - "http://localhost:8080"
    - "http://localhost:5173"

Note: All three API URLs are required (api_server_url, api_internal_url, api_external_url).

Security

JWT tokens and validation settings. See Security Configuration for details.

security:
  jwt_issuer: "systemprompt-local"
  jwt_access_token_expiration: 2592000       # 30 days in seconds
  jwt_refresh_token_expiration: 15552000     # 180 days
  jwt_audiences:
    - web
    - api
    - a2a
    - mcp

Note: Both expiration values must be positive; validation rejects zero or negative values.

Rate Limits

Protect your API from abuse. See Rate Limits Configuration for details.

rate_limits:
  disabled: false                  # Enable in production
  oauth_public_per_second: 10
  contexts_per_second: 100
  agents_per_second: 20
  mcp_per_second: 200
  burst_multiplier: 3
  tier_multipliers:
    admin: 10.0
    user: 1.0
    a2a: 5.0
    mcp: 5.0
    service: 5.0
    anon: 0.5

Disable rate limits in development to avoid interference during testing.

Runtime

Logging and output configuration. See Runtime Configuration for details.

runtime:
  environment: development        # development, test, staging, production
  log_level: verbose              # quiet, normal, verbose, debug
  output_format: text             # text, json, yaml
  no_color: false                 # Disable colors
  non_interactive: false          # Disable prompts

Use json output format in production for structured logging.

Production Profile

A typical production profile:

name: production
display_name: "Production"
target: cloud

server:
  api_server_url: "https://your-domain.com"
  use_https: true

rate_limits:
  disabled: false

runtime:
  environment: production
  log_level: normal
  output_format: json
  no_color: true

cloud:
  tenant_id: 999bc654-9a64-49bc-98be-db976fc84e76
  validation: strict

Create a Profile

Use the CLI wizard to create a new profile.

systemprompt cloud profile create staging

The wizard prompts for the tenant, database connection, and API keys.

For non-interactive creation, pass the tenant and keys as flags:

systemprompt cloud profile create staging \
  --tenant-id <tenant-id> \
  --tenant-type local \
  --anthropic-key sk-ant-...

List Profiles

View all profiles in your project.

systemprompt cloud profile list

Output:

Profiles
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  local          Local Development
  staging        Staging Environment
  production     Production

Show Profile Details

View a profile's configuration.

systemprompt cloud profile show local

Edit a Profile

Modify an existing profile.

systemprompt cloud profile edit local

Run it with no flags for the interactive editor, or set specific values directly:

systemprompt cloud profile edit local --set-port 8081 --set-anthropic-key sk-ant-...

Switch Profiles

Change the active profile for your CLI session.

# Via session command
systemprompt admin session switch staging

# Via environment variable
export SYSTEMPROMPT_PROFILE=/path/to/project/.systemprompt/profiles/staging/profile.yaml

# Per-command override
systemprompt admin agents list --profile production

See Sessions for the full profile priority order.

Delete a Profile

Remove a profile and its configuration.

systemprompt cloud profile delete staging -y

This removes the profile directory but does not affect the tenant or database.

Secrets

Each profile has a secrets.json file for sensitive values.

{
  "database_url": "postgres://user:pass@localhost:5432/systemprompt",
  "anthropic": "sk-ant-...",
  "openai": "sk-...",
  "gemini": "AIza..."
}

Provider keys are named to match each provider's api_key_secret in the profile's provider registry. Secrets are referenced in profile.yaml via the secrets.secrets_path setting and are always gitignored.

See Secrets for managing API keys and credentials.