Skip to main content
Piper is configured through environment variables. Set these in your Docker Compose file, container platform, or .env file.

​
Core Configuration

​
Database

VariableRequiredDescription
DATABASE_URLYesPostgreSQL connection string
DB_POOL_SIZENoDatabase connection pool size (default: 20)
DB_MAX_OVERFLOWNoMax overflow connections (default: 10)

​
Redis

VariableRequiredDescription
REDIS_URLYesRedis/Valkey connection string
For managed Redis services, use TLS: 
REDIS_URL=rediss://:password@your-redis-host:25061

​
Authentication

VariableRequiredDescription
JWT_SECRETYesSecret key for JWT signing (min 32 chars)
SESSION_MAX_AGE_SECONDSNoSession duration in seconds (default: 604800 / 7 days)
COOKIE_DOMAINNoCookie domain for cross-subdomain auth

​
Deployment Mode

VariableRequiredDescription
DEPLOYMENT_MODENoenterprise (default) or saas
ADMIN_API_SECRETYesSecret for Admin API authentication (min 32 chars)
Enterprise Mode (default): Single-tenant deployment for VPC or on-premises.
  • Organization creation only via Admin API
  • No public signup flows
SaaS Mode: Multi-tenant hosted deployment.
  • Self-service organization creation
  • Billing features enabled

​
Example Deployment Configurations

Enterprise / On-Prem: 
DEPLOYMENT_MODE=enterprise
ADMIN_API_SECRET=your-admin-secret-key-here
JWT_SECRET=your-enterprise-jwt-secret
FRONTEND_URL=https://app.yourcompany.com
API_BASE_URL=https://api.yourcompany.com
SaaS / Hosted: 
DEPLOYMENT_MODE=saas
ADMIN_API_SECRET=your-admin-secret-key-here
JWT_SECRET=your-saas-jwt-secret
FRONTEND_URL=https://app.letpiper.com
API_BASE_URL=https://api.letpiper.com

​
Bootstrapping an Enterprise Install

After deploying Piper in enterprise mode, create the first organization and admin user: 
curl -X POST https://your-piper-domain.com/v1/admin/organizations \
  -H "X-Admin-Secret: $ADMIN_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Organization",
    "admin_email": "admin@company.com"
  }'
The response includes an invitation URL for the admin user to set their password.

​
Application Settings

VariableRequiredDescription
ENVIRONMENTNoEnvironment name (default: production)
DEBUGNoEnable debug mode (default: false)
LOG_LEVELNoLogging level (default: INFO)
FRONTEND_URLNoFrontend URL for email links
API_BASE_URLNoAPI base URL for OAuth redirects

​
CORS

VariableRequiredDescription
BACKEND_CORS_ORIGINSNoAllowed CORS origins (comma-separated)
BACKEND_CORS_ORIGINS=https://app.example.com,https://admin.example.com

​
LLM Configuration

Piper uses LiteLLM for LLM provider integration.

​
System Default Provider

The system default provider is used when organizations haven’t configured their own LLM credentials.
VariableRequiredDescription
PIPER_AGENT_PROVIDERYesProvider name: piper (managed), groq, openai, anthropic, google, fireworks, together, or cerebras
PIPER_AGENT_API_KEYYesAPI key for the default provider (for piper, use a Fireworks AI key)
SECRET_ENCRYPTION_KEYYesFernet key for encrypting stored credentials (generate with python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())")
PIPER_AGENT_PROVIDER=piper
PIPER_AGENT_API_KEY=fw_xxxxx
SECRET_ENCRYPTION_KEY=your-fernet-key-here

​
Per-Organization LLM Providers

Organizations can configure their own LLM providers through the dashboard under Settings > LLM Providers. This allows:
  • Bring Your Own Keys: Organizations use their own API keys
  • Per-Agent Model Selection: Each agent can use a specific provider and model
  • Automatic Fallback: If no org config exists, the system default is used
Supported providers:
  • Groq - Fast inference with Llama models
  • OpenAI - GPT-4, GPT-5 models
  • Anthropic - Claude models
  • Google - Gemini models

​
Embeddings

VariableRequiredDescription
PIPER_EMBEDDING_MODELNoEmbedding model (default: text-embedding-3-small)
PIPER_EMBEDDING_API_KEYYesAPI key for embedding provider

​
Scenario Evaluation

VariableRequiredDescription
PIPER_EVAL_MODELNoLLM judge model (default: anthropic/claude-opus-4-5-20251101)
PIPER_EVAL_API_KEYYesAPI key for eval provider

​
Email (SMTP)

VariableRequiredDescription
SMTP_HOSTYesSMTP server host
SMTP_PORTNoSMTP server port (default: 587)
SMTP_USERNoSMTP username
SMTP_PASSWORDNoSMTP password
SMTP_DEFAULT_FROM_EMAILNoSender email address
SMTP_DEFAULT_FROM_NAMENoSender display name (default: Piper)
SMTP_TLSNoUse TLS (default: true)
SMTP_SSLNoUse SSL (default: false)
Example (SendGrid): 
SMTP_HOST=smtp.sendgrid.net
SMTP_PORT=587
SMTP_USER=apikey
SMTP_PASSWORD=SG.xxxxx
SMTP_DEFAULT_FROM_EMAIL=noreply@yourcompany.com

​
Slack Integration

VariableRequiredDescription
SLACK_CLIENT_IDFor OAuthSlack app client ID
SLACK_CLIENT_SECRETFor OAuthSlack app client secret
SLACK_SIGNING_SECRETYesSlack signing secret for webhook verification
OAUTH_STATE_SECRETRecommendedSecret used for OAuth state signing (fallback: SLACK_CLIENT_SECRET)
SLACK_OAUTH_SCOPESNoComma-separated OAuth scopes (default: chat:write,app_mentions:read,im:history,channels:history,groups:history)

​
Observability

​
Pydantic Logfire

VariableRequiredDescription
LOGFIRE_TOKENNoPydantic Logfire write token for agent tracing (LLM calls, tool execution, token usage)
When set, Logfire automatically traces all Pydantic AI agent runs (including delegations), FastAPI requests, and worker tasks. Traces are OTEL-compatible.

​
LangSmith

VariableRequiredDescription
LANGSMITH_API_KEYNoLangSmith API key for tracing
LANGSMITH_PROJECTNoLangSmith project name
LANGSMITH_TRACINGNoEnable LangSmith tracing (default: false)

​
Example Configuration

DATABASE_URL=postgresql+asyncpg://piper:xxx@piper-db.internal:5432/piper
REDIS_URL=rediss://:xxx@piper-redis.internal:6379
JWT_SECRET=your-enterprise-secret-key-here
ADMIN_API_SECRET=your-admin-secret-key-here
SECRET_ENCRYPTION_KEY=your-fernet-key-here

# System Default LLM Provider
PIPER_AGENT_PROVIDER=piper
PIPER_AGENT_API_KEY=fw_xxxxx

# Embeddings
PIPER_EMBEDDING_API_KEY=sk-xxxxx

SMTP_HOST=smtp.sendgrid.net
SMTP_USER=apikey
SMTP_PASSWORD=SG.xxxxx