Environment Variables Documentation

Last Updated: 2025-08-09

Overview

This document provides a comprehensive reference for all environment variables used in Sasha Studio. Environment variables can be configured through .env files or set directly in the deployment environment.

Configuration Methods

Local Development

Create a .env file in the project root:

cp .env.example .env
# Edit .env with your values

Docker Deployment

Configuration is stored in persistent volumes:

• Location: /app/config/.env
• Volume: sasha-config
• Persists across container restarts

Production Deployment

Set environment variables through your hosting platform:

• Heroku: heroku config:set VAR_NAME=value
• AWS: Use Systems Manager Parameter Store
• Docker: Use docker-compose environment section

Core Environment Variables

Server Configuration

Variable	Description	Default	Required
PORT	Server listening port	3005	No
HOST	Server binding address	0.0.0.0	No
NODE_ENV	Environment mode (development, production)	development	No

API Configuration

Variable	Description	Default	Required
ANTHROPIC_API_KEY	Claude API key for AI functionality	-	Yes
VITE_API_URL	Backend API URL	http://localhost:3005	No
VITE_WS_URL	WebSocket server URL	ws://localhost:3005	No

Security Configuration

Variable	Description	Default	Required
SESSION_SECRET	Express session secret	Random generated	Yes (production)
JWT_SECRET	JWT token signing secret	Random generated	Yes (production)
HELMET_ENABLED	Enable security headers	true	No
RATE_LIMIT_ENABLED	Enable rate limiting	true	No
RATE_LIMIT_MAX	Max requests per window	100	No
RATE_LIMIT_WINDOW_MS	Rate limit time window (ms)	900000 (15 min)	No

Database Configuration

Variable	Description	Default	Required
DB_PATH	SQLite database file path	/app/data/sasha.db	No
DB_LOGGING	Enable database query logging	false	No

Storage Configuration

Variable	Description	Default	Required
DOCS_PATH	Documents storage directory	/app/docs	No
UPLOADS_PATH	File uploads directory	/app/uploads	No
MAX_FILE_SIZE	Maximum file upload size (bytes)	52428800 (50MB)	No
CONFIG_DIR	Configuration files directory	/app/config (Docker)	No

Docker-Specific Variables

Variable	Description	Default	Required
RUNNING_IN_DOCKER	Indicates Docker environment	true (in Docker)	Auto-set
USE_DOCKER_WORKSPACE	Enable Docker workspace mode	true (in Docker)	Auto-set
CLAUDE_HOME	Claude CLI config directory	/home/nodejs/.claude	No

Branding Configuration

Variable	Description	Default	Required
VITE_APP_NAME	Application display name	Sasha Studio	No
VITE_AI_NAME	AI assistant name	Sasha	No
VITE_COMPANY_NAME	Organization name	Your Company	No

Example Configuration Files

Development (.env)

# Server
PORT=3005
NODE_ENV=development

# API Keys
ANTHROPIC_API_KEY=sk-ant-your-dev-key-here

# Security (use weak keys for dev only)
SESSION_SECRET=dev-session-secret
JWT_SECRET=dev-jwt-secret

# Database
DB_PATH=./data/sasha.db
DB_LOGGING=true

# Paths
DOCS_PATH=./docs
UPLOADS_PATH=./uploads

Production (.env.production)

# Server
PORT=3005
NODE_ENV=production
HOST=0.0.0.0

# API Keys (use environment-specific keys)
ANTHROPIC_API_KEY=sk-ant-your-prod-key-here

# Security (use strong, unique secrets)
SESSION_SECRET=your-strong-random-session-secret-here
JWT_SECRET=your-strong-random-jwt-secret-here
HELMET_ENABLED=true
RATE_LIMIT_ENABLED=true
RATE_LIMIT_MAX=100
RATE_LIMIT_WINDOW_MS=900000

# Database
DB_PATH=/app/data/sasha.db
DB_LOGGING=false

# Paths
DOCS_PATH=/app/docs
UPLOADS_PATH=/app/uploads
CONFIG_DIR=/app/config
MAX_FILE_SIZE=52428800

Docker Compose Override

# docker-compose.override.yml
version: '3.8'

services:
  sasha-studio:
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - SESSION_SECRET=${SESSION_SECRET}
      - JWT_SECRET=${JWT_SECRET}
      - NODE_ENV=production

Security Best Practices

API Keys

• Never commit API keys to version control
• Use different keys for development and production
• Rotate keys regularly
• Monitor API usage for anomalies

Secrets Management

• Generate strong, random secrets for production:

  openssl rand -base64 32
  

• Use environment-specific secrets
• Consider using secret management services:
  • AWS Secrets Manager
  • HashiCorp Vault
  • Docker Secrets

Environment Files

• Add .env to .gitignore
• Use .env.example for documentation
• Validate required variables on startup
• Log missing required variables

Docker Persistence

Volume Mounts

The Docker deployment uses persistent volumes to maintain configuration:

volumes:
  sasha-config:    # Stores .env and configuration files
  sasha-data:      # Database persistence
  sasha-uploads:   # Uploaded files
  claude-config:   # Claude CLI configuration

Configuration Priority

1. Environment variables (highest priority)
2. /app/config/.env (Docker persistent)
3. ./.env (project root)
4. Default values (lowest priority)

Troubleshooting

Missing API Key

# Check if API key is set
echo $ANTHROPIC_API_KEY

# Configure through UI
# Settings -> Tools -> Claude API Configuration

Permission Issues (Docker)

# Fix config directory permissions
docker exec sasha-studio chmod 777 /app/config

# Verify volume mounts
docker volume inspect sasha-config

Environment Not Loading

# Check .env file location
ls -la .env
ls -la /app/config/.env  # Docker

# Verify file format (no spaces around =)
cat .env | grep ANTHROPIC_API_KEY

Migration Guide

From Client-Side Storage

If upgrading from a version that stored API keys in the browser:

1. API keys are now configured server-side only
2. Use Settings -> Tools -> Claude API Configuration
3. Previous localStorage values are ignored
4. Configuration persists in Docker volumes

From Ephemeral to Persistent (Docker)

The system automatically uses the new persistent configuration:

1. New location: /app/config/.env
2. Old location: /app/.env (ephemeral)
3. Automatic fallback for backwards compatibility
4. No manual migration required

Validation Script

Create a validation script to check required variables:

// scripts/validate-env.js
const required = [
  'ANTHROPIC_API_KEY',
  'SESSION_SECRET',
  'JWT_SECRET'
];

const missing = required.filter(key => !process.env[key]);

if (missing.length > 0) {
  console.error('Missing required environment variables:');
  missing.forEach(key => console.error(`  - ${key}`));
  process.exit(1);
}

console.log('✅ All required environment variables are set');

Support

For issues with environment configuration:

1. Check this documentation
2. Review the .env.example file
3. Check Docker logs: docker logs sasha-studio
4. Contact support with configuration details (never share API keys)