Skip to main content
Piper is configured through environment variables. In Kubernetes deployments, these are set via Helm values and Kubernetes secrets.

​
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 (DigitalOcean, AWS ElastiCache), 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

​
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": "[email protected]"
  }'
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

​
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 which supports 100+ LLM providers.

​
Cloud LLM (Groq)

VariableRequiredDescription
GROQ_API_KEYFor cloud LLMGroq API key
LLM_MODELNoModel identifier (default: llama-3.3-70b-versatile)

​
AWS Bedrock

For enterprise deployments using AWS Bedrock:
VariableRequiredDescription
AWS_ACCESS_KEY_IDYesAWS access key
AWS_SECRET_ACCESS_KEYYesAWS secret key
AWS_REGION_NAMEYesAWS region
LLM_MODELYesModel in LiteLLM format
AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=...
AWS_REGION_NAME=us-east-1
LLM_MODEL=bedrock/anthropic.claude-sonnet-4-5-20250929-v1:0

​
Embeddings

VariableRequiredDescription
OPENAI_API_KEYFor embeddingsOpenAI API key
EMBEDDING_MODELNoEmbedding model (default: text-embedding-3-small)

​
Email (SMTP)

VariableRequiredDescription
SMTP_HOSTYesSMTP server host
SMTP_PORTNoSMTP server port (default: 587)
SMTP_USERNoSMTP username
SMTP_PASSWORDNoSMTP password
SMTP_FROM_EMAILNoSender email address
SMTP_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_FROM_EMAIL=[email protected]

​
Observability

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:[email protected]:5432/piper
REDIS_URL=rediss://:[email protected]:6379
JWT_SECRET=your-enterprise-secret-key-here
ADMIN_API_SECRET=your-admin-secret-key-here

# AWS Bedrock
AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=...
AWS_REGION_NAME=us-east-1
LLM_MODEL=bedrock/anthropic.claude-sonnet-4-5-20250929-v1:0

# Embeddings
OPENAI_API_KEY=sk-xxxxx

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