Tenants

Tenants are isolated environments that own databases and configuration. Each tenant is completely separate from others, with its own data, users, and settings. You can run multiple tenants simultaneously for development, staging, and production.

Why Tenants

Multi-tenancy solves a fundamental problem: keeping environments truly isolated. Without tenants, it's too easy to accidentally run production commands in development or mix data between environments.

Tenants provide:

• Database isolation - Each tenant has its own PostgreSQL database
• Configuration isolation - Settings don't leak between environments
• Credential isolation - API keys and secrets are tenant-specific
• Session isolation - CLI state is tracked per-tenant

Tenant Types

systemprompt.io supports two types of tenants.

Local Tenants

Local tenants run on your machine using Docker. They're free and ideal for development.

• PostgreSQL runs in a Docker container
• Data is stored locally
• No network dependencies
• Perfect for offline development

Cloud Tenants

Cloud tenants run on systemprompt.io's managed infrastructure. They're designed for production.

• Managed PostgreSQL with automatic backups
• TLS certificates included
• Accessible via <tenant-id>.systemprompt.io
• Requires a paid subscription

Tenant Registry

All tenants are tracked in .systemprompt/tenants.json. This file is synced with systemprompt.io Cloud and includes both local and cloud tenants.

{
  "tenants": [
    {
      "id": "local_19bff27604c",
      "name": "my-project",
      "tenant_type": "local",
      "database_url": "postgres://systemprompt:localdev@localhost:5432/systemprompt",
      "external_db_access": false,
      "shared_container_db": "systemprompt-shared-db"
    },
    {
      "id": "999bc654-9a64-49bc-98be-db976fc84e76",
      "name": "my-project-prod",
      "tenant_type": "cloud",
      "app_id": "sp-999bc6549a64",
      "hostname": "999bc6549a64.systemprompt.io",
      "region": "iad",
      "internal_database_url": "postgres://user:pass@internal-db:5432/tenant"
    }
  ],
  "synced_at": "2026-02-01T10:00:00Z"
}

StoredTenant Fields

Field	Local	Cloud	Description
id	Yes	Yes	Unique tenant identifier
name	Yes	Yes	Display name
tenant_type	local	cloud	Tenant type
database_url	Yes	No	Local PostgreSQL URL
internal_database_url	No	Yes	Cloud internal database URL
external_db_access	Yes	No	Allow external connections
shared_container_db	Optional	No	Shared Docker container name
app_id	No	Yes	Fly.io app ID
hostname	No	Yes	Cloud hostname
region	No	Yes	Deployment region

Create a Tenant

Local Tenant

Local tenants are created for you during setup. just setup-local writes the profile, starts a per-clone Docker PostgreSQL container, and registers the local tenant in the registry.

just setup-local

Under the hood this runs systemprompt admin setup, which prompts for anything it can't infer and stores the database connection in the tenant registry.

Cloud Tenant

Create a cloud tenant for production. Requires authentication with systemprompt.io Cloud.

systemprompt cloud auth login
systemprompt cloud tenant create --region iad

Available regions:

• iad - US East (Virginia)
• lhr - Europe (London)
• syd - Asia Pacific (Sydney)

Cloud tenant creation takes 1-2 minutes while infrastructure provisions.

List Tenants

View all tenants registered in your project.

systemprompt cloud tenant list

Output:

Tenants
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  local_19bff27604c    local   my-project
  999bc654-9a64...     cloud   my-project-prod   iad

Select a Tenant

The active tenant follows the active profile. Each profile binds to one tenant via cloud.tenant_id, so you switch tenants by switching profiles, either through your session or per-command:

systemprompt cloud tenant show --profile local

Show Tenant Details

View detailed information about a tenant.

# Show selected tenant
systemprompt cloud tenant show

# Show specific tenant
systemprompt cloud tenant show 999bc654-9a64-49bc-98be-db976fc84e76

Output for cloud tenants includes hostname, region, and status.

Rotate Credentials

Regenerate database credentials for a tenant. Use this if credentials are compromised.

systemprompt cloud tenant rotate-credentials <tenant-id> -y

After rotation, update any external systems that use these credentials.

Delete a Tenant

Remove a tenant and all its data. This action is irreversible.

systemprompt cloud tenant delete <tenant-id> -y

For cloud tenants, this also cancels the subscription:

systemprompt cloud tenant cancel <tenant-id>

Tenants and Profiles

Tenants and profiles work together. A profile belongs to exactly one tenant, specified in profile.yaml:

# .systemprompt/profiles/local/profile.yaml
name: local
target: local

cloud:
  tenant_id: local_19bff27604c

When you create a profile, it's linked to its tenant through cloud.tenant_id. You can have multiple profiles per tenant (e.g., local-dev, local-test) but each profile points to exactly one tenant.

Tenant: local_19bff27604c
├── Profile: local
├── Profile: local-test
└── Profile: local-integration

Tenant: 999bc654-... (cloud)
├── Profile: staging
└── Profile: production

Tenants and Sessions

Sessions are tenant-keyed. When you switch profiles, you switch to that tenant's session:

1. Switch to profile A → tenant A's session is active
2. Switch to profile B → tenant B's session is active (completely separate)
3. Switch back to profile A → tenant A's session is restored

This means you can work in multiple tenants without cross-contamination. Each tenant tracks its own authentication, permissions, and state.

Local Tenant Setup

Local tenants require PostgreSQL. The easiest approach is Docker:

# Start shared PostgreSQL container
just db-up

# Verify it's running
docker ps | grep postgres

The database connection is stored in the tenant registry and profile secrets. See Database for connection options.

Cloud Tenant Setup

Cloud tenants are fully managed. After creation:

1. Wait for provisioning - Takes 1-2 minutes
2. Create a profile - systemprompt admin setup --environment production
3. Add secrets - API keys are required for AI features
4. Run migrations - systemprompt infra db migrate

Your cloud tenant is now ready at https://<tenant-id>.systemprompt.io.

Troubleshooting

Issue	Cause	Solution
"No tenant configured"	Active profile has no tenant	Run cloud tenant list, then set cloud.tenant_id in the profile
"Tenant not found"	Invalid tenant ID	Check tenants.json for valid IDs
"Database connection failed"	PostgreSQL not running	Run just db-up for local tenants
"Provisioning failed"	Cloud infrastructure issue	Check cloud tenant show for status
"Access denied"	Credential issue	Run cloud tenant rotate-credentials