Configuration

Overview

All configuration for Tesslate Studio is managed through environment variables, typically stored in a .env file in the project root. This page documents every available variable, organized by category, with clear labels for which are required and which are optional. To get started, copy the example file:

cp .env.example .env

Then edit .env with your preferred text editor.

After changing any environment variable, restart the affected service for the change to take effect:

docker compose restart orchestrator

Required Variables

These variables must be set for Tesslate Studio to start. Without them, the orchestrator will fail on boot.

Application Secrets

SECRET_KEY

string

required

Used for JWT token signing, session encryption, and Fernet encryption of stored credentials (GitHub tokens, deployment OAuth tokens). Must be a long, random string. Never reuse this across environments.

Generate a secure key:

python3 -c "import secrets; print(secrets.token_urlsafe(32))"

Example:

SECRET_KEY=dGhpcyBpcyBhIHNlY3JldCBrZXkgZm9yIGRlbW8gcHVycG9zZXM

If you change SECRET_KEY on a running instance, all existing JWT tokens and encrypted credentials will become invalid. Users will need to log in again, and OAuth connections will need to be re-authorized.

AI / LLM Configuration

LITELLM_API_BASE

string

required

The base URL of your LiteLLM proxy or compatible API endpoint. This is where the orchestrator sends all LLM requests.

LITELLM_MASTER_KEY

string

required

Authentication key for the LiteLLM proxy. Used by the backend to authorize requests.

LITELLM_API_BASE=https://your-litellm-proxy.com/v1
LITELLM_MASTER_KEY=sk-your-litellm-master-key

Using direct provider API keys instead of a LiteLLM proxy?

If you are running a LiteLLM proxy that routes to provider APIs, configure the provider keys on the proxy itself. Tesslate Studio communicates only with the LiteLLM endpoint; it does not send keys directly to OpenAI or Anthropic.If you run the built-in LiteLLM instance (included in some deployment configurations), you can set provider keys as environment variables on that service:

OPENAI_API_KEY=sk-your-openai-key
ANTHROPIC_API_KEY=sk-your-anthropic-key

Database Configuration

DATABASE_URL

string

PostgreSQL connection string using the asyncpg driver. For Docker Compose, the default value connects to the bundled PostgreSQL container. For production, point this at a managed database (Amazon RDS, Supabase, etc.).

POSTGRES_PASSWORD

string

default:"dev_password_change_me"

Password for the PostgreSQL container (Docker Compose only). This value is used both to initialize the database and in the DATABASE_URL.

POSTGRES_USER

string

default:"tesslate"

PostgreSQL username (Docker Compose only).

POSTGRES_DB

string

default:"tesslate"

PostgreSQL database name (Docker Compose only).

Docker Compose (local)
External / Managed Database
AWS RDS

# The default works out of the box.
DATABASE_URL=postgresql+asyncpg://tesslate:tesslate@postgres:5432/tesslate
POSTGRES_PASSWORD=dev_password_change_me

DATABASE_URL=postgresql+asyncpg://admin:[email protected]:5432/tesslate
# POSTGRES_PASSWORD is not needed when using an external database.

DATABASE_URL=postgresql+asyncpg://tesslate:[email protected]:5432/tesslate

Always change the default password in production. The Docker Compose default is for local development only.

Authentication & Security

APP_DOMAIN

string

default:"localhost"

The domain where Tesslate Studio is hosted, without protocol. Used for CORS configuration, cookie scoping, and generating project URLs.

Domain for setting authentication cookies. Leave empty for localhost. For production, prefix with a dot to cover subdomains (e.g., .studio.yourcompany.com).

Set to true when using HTTPS in production. This ensures cookies are only sent over secure connections.

CORS_ORIGINS

string

default:""

Comma-separated list of allowed origins for CORS. The orchestrator also dynamically allows APP_DOMAIN and its subdomains.

# Local development
APP_DOMAIN=localhost
COOKIE_DOMAIN=
COOKIE_SECURE=false
CORS_ORIGINS=http://localhost:3000,http://localhost:5173

# Production
APP_DOMAIN=studio.yourcompany.com
COOKIE_DOMAIN=.studio.yourcompany.com
COOKIE_SECURE=true
CORS_ORIGINS=https://studio.yourcompany.com

CSRF Protection

Tesslate Studio uses a double-submit cookie pattern for CSRF protection. This is handled automatically; no configuration is needed. The CSRF token is set in a JavaScript-readable cookie, and the frontend sends it back in the X-CSRF-Token header.

Encryption

DEPLOYMENT_ENCRYPTION_KEY

string

Optional Fernet key for encrypting deployment provider credentials (Vercel, Netlify, Cloudflare OAuth tokens). If not set, derived from SECRET_KEY.

Configure OAuth for GitHub and Google login. Without these, only email/password authentication is available.

GitHub
Google

GITHUB_CLIENT_ID

string

GitHub OAuth application client ID.

GITHUB_CLIENT_SECRET

string

GitHub OAuth application client secret.

GITHUB_OAUTH_REDIRECT_URI

string

Callback URL registered in your GitHub OAuth app settings.

GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret

# Local development
GITHUB_OAUTH_REDIRECT_URI=http://localhost/api/auth/github/callback

# Production
GITHUB_OAUTH_REDIRECT_URI=https://studio.yourcompany.com/api/auth/github/callback

Create a GitHub OAuth app at github.com/settings/developers. Set the Authorization callback URL to match GITHUB_OAUTH_REDIRECT_URI.

GOOGLE_CLIENT_ID

string

Google OAuth 2.0 client ID.

GOOGLE_CLIENT_SECRET

string

Google OAuth 2.0 client secret.

GOOGLE_OAUTH_REDIRECT_URI

string

Callback URL registered in your Google Cloud Console.

GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-google-client-secret

# Local development
GOOGLE_OAUTH_REDIRECT_URI=http://localhost/api/auth/google/callback

# Production
GOOGLE_OAUTH_REDIRECT_URI=https://studio.yourcompany.com/api/auth/google/callback

Create OAuth credentials at console.cloud.google.com/apis/credentials.

AI / LLM Settings

LITELLM_DEFAULT_MODELS

string

default:""

Comma-separated list of model identifiers to offer users in the model selector. These must match models configured on your LiteLLM proxy.

# Single provider
LITELLM_DEFAULT_MODELS=claude-3-5-sonnet-20241022

# Multiple providers
LITELLM_DEFAULT_MODELS=gpt-4o-mini,claude-3-5-sonnet-20241022,qwen-3-235b-a22b-thinking-2507

Supported model providers (via LiteLLM):

Provider	Example Models
OpenAI	`gpt-4`, `gpt-3.5-turbo`, `gpt-4o-mini`
Anthropic	`claude-3-5-sonnet-20241022`, `claude-3-opus-20240229`
Custom / Self-hosted	`qwen-3-235b-a22b-thinking-2507`

Deployment Mode

DEPLOYMENT_MODE

string

default:"docker"

Controls which container orchestration backend the orchestrator uses. Options: docker or kubernetes.

# Local development (Docker Compose + Traefik)
DEPLOYMENT_MODE=docker

# Production or Minikube testing (Kubernetes + NGINX Ingress)
DEPLOYMENT_MODE=kubernetes

The orchestrator automatically adapts its behavior based on this value. No code changes are needed to switch between modes. See the Deployment Guide for details.

Container Runtime (Docker Mode)

These settings apply when DEPLOYMENT_MODE=docker.

DEV_SERVER_BASE_URL

string

default:"http://localhost"

Base URL used for routing to user project containers in Docker mode.

APP_PORT

number

default:"80"

Host port for Traefik (HTTP).

BACKEND_PORT

number

default:"8000"

Host port for the backend API.

FRONTEND_PORT

number

default:"5173"

Host port for the Vite dev server.

DEPLOYMENT_MODE=docker
DEV_SERVER_BASE_URL=http://localhost
APP_PORT=80
BACKEND_PORT=8000
FRONTEND_PORT=5173

Container Runtime (Kubernetes Mode)

These settings apply when DEPLOYMENT_MODE=kubernetes.

Core Kubernetes Settings

K8S_DEVSERVER_IMAGE

string

required

Docker image used for user project containers. For Minikube, use a local image name. For AWS EKS, use a full ECR URL.

K8S_IMAGE_PULL_SECRET

string

default:""

Name of the Kubernetes image pull secret for private registries. Leave empty for local images (Minikube with imagePullPolicy: Never).

K8S_STORAGE_CLASS

string

default:"tesslate-block-storage"

Kubernetes StorageClass for user project PVCs.

K8S_PVC_SIZE

string

default:"10Gi"

Size of the PersistentVolumeClaim created for each user project.

Minikube (local testing)
AWS EKS (production)

DEPLOYMENT_MODE=kubernetes
K8S_DEVSERVER_IMAGE=tesslate-devserver:latest
K8S_IMAGE_PULL_SECRET=
K8S_STORAGE_CLASS=standard

DEPLOYMENT_MODE=kubernetes
K8S_DEVSERVER_IMAGE=859561299901.dkr.ecr.us-east-1.amazonaws.com/tesslate-devserver:latest
K8S_IMAGE_PULL_SECRET=ecr-credentials
K8S_STORAGE_CLASS=tesslate-block-storage

Snapshot / Hibernation Settings

These control the EBS VolumeSnapshot-based persistence system used in Kubernetes mode for hibernating and restoring user projects.

K8S_SNAPSHOT_CLASS

string

default:"tesslate-ebs-snapshots"

VolumeSnapshotClass name for creating EBS snapshots.

K8S_SNAPSHOT_RETENTION_DAYS

number

default:"30"

Number of days to retain soft-deleted snapshots before permanent deletion.

K8S_MAX_SNAPSHOTS_PER_PROJECT

number

default:"5"

Maximum number of snapshots kept per project (for the Timeline UI).

K8S_SNAPSHOT_READY_TIMEOUT_SECONDS

number

default:"90"

Maximum time (in seconds) to wait for a VolumeSnapshot to become ready.

K8S_HIBERNATION_IDLE_MINUTES

number

default:"10"

Minutes of inactivity before a project is automatically hibernated (snapshot taken, namespace deleted).

K8S_SNAPSHOT_CLASS=tesslate-ebs-snapshots
K8S_SNAPSHOT_RETENTION_DAYS=30
K8S_MAX_SNAPSHOTS_PER_PROJECT=5
K8S_HIBERNATION_IDLE_MINUTES=10

Networking and Ingress

K8S_INGRESS_CLASS

string

default:"nginx"

Ingress class for user project Ingress resources.

K8S_WILDCARD_TLS_SECRET

string

default:""

Name of the Kubernetes TLS secret containing the wildcard certificate. Leave empty for HTTP-only (Minikube).

K8S_ENABLE_POD_AFFINITY

boolean

default:"true"

When enabled, all containers in a multi-container project are scheduled on the same node. Required for sharing ReadWriteOnce PVCs.

K8S_ENABLE_NETWORK_POLICIES

boolean

default:"true"

When enabled, creates NetworkPolicy resources that enforce zero cross-project communication.

K8S_INGRESS_CLASS=nginx
K8S_WILDCARD_TLS_SECRET=tesslate-wildcard-tls
K8S_ENABLE_POD_AFFINITY=true
K8S_ENABLE_NETWORK_POLICIES=true

S3 / Object Storage

Used in Kubernetes mode for legacy project storage. The current primary persistence mechanism uses EBS VolumeSnapshots, but S3 configuration is still relevant for asset storage.

S3_BUCKET_NAME

string

default:"tesslate-projects"

S3 bucket name for project storage.

S3_ENDPOINT_URL

string

default:""

S3 endpoint URL. Leave empty for native AWS S3. Set to a MinIO URL for local development or a DigitalOcean Spaces URL for DO deployments.

S3_REGION

string

default:"us-east-1"

AWS region for S3 signature calculation.

S3_ACCESS_KEY_ID

string

S3 access key. Not needed on AWS EKS when using IRSA (IAM Roles for Service Accounts).

S3_SECRET_ACCESS_KEY

string

S3 secret key. Not needed on AWS EKS when using IRSA.

AWS S3 (with IRSA)
MinIO (Minikube local)
DigitalOcean Spaces

S3_BUCKET_NAME=tesslate-projects-production-7761157a
S3_REGION=us-east-1
# No access keys needed; IRSA handles authentication.

S3_ENDPOINT_URL=http://minio.minio-system.svc.cluster.local:9000
S3_BUCKET_NAME=tesslate-projects
S3_ACCESS_KEY_ID=minioadmin
S3_SECRET_ACCESS_KEY=minioadmin

S3_ENDPOINT_URL=https://nyc3.digitaloceanspaces.com
S3_BUCKET_NAME=your-space-name
S3_REGION=nyc3
S3_ACCESS_KEY_ID=your-access-key
S3_SECRET_ACCESS_KEY=your-secret-key

Billing (Stripe)

Optional. Configure Stripe for subscription billing, credit purchases, and marketplace creator payouts.

STRIPE_SECRET_KEY

string

Stripe API secret key (starts with sk_test_ or sk_live_).

STRIPE_PUBLISHABLE_KEY

string

Stripe publishable key for the frontend (starts with pk_test_ or pk_live_).

STRIPE_WEBHOOK_SECRET

string

Webhook signing secret for validating Stripe event payloads (starts with whsec_).

# Test mode
STRIPE_SECRET_KEY=sk_test_your-stripe-secret-key
STRIPE_PUBLISHABLE_KEY=pk_test_your-stripe-publishable-key
STRIPE_WEBHOOK_SECRET=whsec_your-webhook-secret

# For local webhook testing, use the Stripe CLI:
# stripe listen --forward-to localhost:8000/api/webhooks/stripe

Email / SMTP

Optional. Configure SMTP for email-based two-factor authentication and password reset flows.

SMTP_HOST

string

SMTP server hostname.

SMTP_PORT

number

default:"587"

SMTP server port.

SMTP_USERNAME

string

SMTP authentication username.

SMTP_PASSWORD

string

SMTP authentication password.

SMTP_SENDER_EMAIL

string

The “From” address for outgoing emails.

TWO_FA_ENABLED

boolean

default:"false"

Enable email-based two-factor authentication for user logins.

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
[email protected]
SMTP_PASSWORD=your-app-password
[email protected]
TWO_FA_ENABLED=true

Analytics

VITE_PUBLIC_POSTHOG_KEY

string

PostHog project API key for frontend analytics.

VITE_PUBLIC_POSTHOG_HOST

string

default:"https://us.i.posthog.com"

PostHog instance URL.

VITE_PUBLIC_POSTHOG_KEY=phc_your_posthog_key
VITE_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com

Logging

LOG_LEVEL

string

default:"INFO"

Application logging level. Options: DEBUG, INFO, WARNING, ERROR, CRITICAL.

# Development (verbose output)
LOG_LEVEL=DEBUG

# Production (normal output)
LOG_LEVEL=INFO

Log format: %(asctime)s - %(name)s - %(levelname)s - %(message)s Key loggers include app.main, app.services.orchestration.kubernetes_orchestrator, app.agent.stream_agent, and app.routers.*.

Configuration Profiles

Here are complete example configurations for common scenarios:

# Deployment
DEPLOYMENT_MODE=docker
DEV_SERVER_BASE_URL=http://localhost

# Database (uses bundled PostgreSQL)
DATABASE_URL=postgresql+asyncpg://tesslate:tesslate@postgres:5432/tesslate
POSTGRES_PASSWORD=dev_password_change_me

# Auth
SECRET_KEY=your-dev-secret-key

# AI
LITELLM_API_BASE=https://your-litellm.com/v1
LITELLM_MASTER_KEY=sk-your-master-key
LITELLM_DEFAULT_MODELS=gpt-4o-mini,claude-3-5-sonnet-20241022

# Domain
APP_DOMAIN=localhost
CORS_ORIGINS=http://localhost:3000,http://localhost:5173

# Logging
LOG_LEVEL=DEBUG

Environment Comparison Table

Setting	Docker (Local)	Kubernetes (Minikube)	Kubernetes (AWS EKS)
`DEPLOYMENT_MODE`	`docker`	`kubernetes`	`kubernetes`
`K8S_DEVSERVER_IMAGE`	N/A	`tesslate-devserver:latest`	`<ECR_URL>/tesslate-devserver:latest`
`K8S_IMAGE_PULL_SECRET`	N/A	(empty)	`ecr-credentials`
`K8S_STORAGE_CLASS`	N/A	`standard`	`tesslate-block-storage`
`K8S_WILDCARD_TLS_SECRET`	N/A	(empty, HTTP only)	`tesslate-wildcard-tls`
`APP_DOMAIN`	`localhost`	`localhost`	`studio.yourcompany.com`
`COOKIE_DOMAIN`	(empty)	(empty)	`.studio.yourcompany.com`
`COOKIE_SECURE`	`false`	`false`	`true`

Troubleshooting

Invalid or missing SECRET_KEY

Symptom: The orchestrator crashes on startup with a key-related error.Fix: Generate a new key and update .env:

python3 -c "import secrets; print(secrets.token_urlsafe(32))"

Then restart: docker compose restart orchestrator

Database connection failed

Symptom: Errors about PostgreSQL not being accessible.Fix:

# Check if postgres container is running
docker compose ps postgres

# Check logs for details
docker compose logs postgres

# Restart the database
docker compose restart postgres

Verify that DATABASE_URL in .env matches the actual database credentials.

AI models not appearing or returning errors

Symptom: The model selector is empty, or chat returns “API key not found.”Fix:

Verify LITELLM_API_BASE points to a running LiteLLM instance.
Verify LITELLM_MASTER_KEY is correct.
Check that LITELLM_DEFAULT_MODELS lists valid model names.
Restart the orchestrator: docker compose restart orchestrator

OAuth redirect errors

Symptom: After clicking “Login with GitHub/Google,” you see a redirect error.Fix: Ensure the callback URL registered with the OAuth provider matches GITHUB_OAUTH_REDIRECT_URI or GOOGLE_OAUTH_REDIRECT_URI exactly, including the protocol (http vs https) and path.

Next Steps

Deployment Guide

Deploy to production with Docker Compose, Kubernetes, or AWS EKS

Architecture Overview

Understand how the components fit together

Quickstart

Get up and running locally in minutes

API Documentation

Explore the REST API reference

Get Started

Self-Hosting

Core Concepts

Working with Projects

AI Agents

Advanced Features

Developer Guide

Development

Overview

Required Variables

Application Secrets

AI / LLM Configuration

Database Configuration

Authentication & Security

CSRF Protection

Encryption

AI / LLM Settings

Deployment Mode

Container Runtime (Docker Mode)

Container Runtime (Kubernetes Mode)

Core Kubernetes Settings

Snapshot / Hibernation Settings

Networking and Ingress

S3 / Object Storage

Billing (Stripe)

Email / SMTP

Analytics

Logging

Configuration Profiles

Environment Comparison Table

Troubleshooting

Next Steps

Deployment Guide

Architecture Overview

Quickstart

API Documentation

Get Started

Self-Hosting

Core Concepts

Working with Projects

AI Agents

Advanced Features

Developer Guide

Development

​Overview

​Required Variables

​Application Secrets

​AI / LLM Configuration

​Database Configuration

​Authentication & Security

​CSRF Protection

​Encryption

​OAuth Providers (Social Login)

​AI / LLM Settings

​Deployment Mode

​Container Runtime (Docker Mode)

​Container Runtime (Kubernetes Mode)

​Core Kubernetes Settings

​Snapshot / Hibernation Settings

​Networking and Ingress

​S3 / Object Storage

​Billing (Stripe)

​Email / SMTP

​Analytics

​Logging

​Configuration Profiles

​Environment Comparison Table

​Troubleshooting

​Next Steps

Deployment Guide

Architecture Overview

Quickstart

API Documentation

Overview

Required Variables

Application Secrets

AI / LLM Configuration

Database Configuration

Authentication & Security

CSRF Protection

Encryption

OAuth Providers (Social Login)

AI / LLM Settings

Deployment Mode

Container Runtime (Docker Mode)

Container Runtime (Kubernetes Mode)

Core Kubernetes Settings

Snapshot / Hibernation Settings

Networking and Ingress

S3 / Object Storage

Billing (Stripe)

Email / SMTP

Analytics

Logging

Configuration Profiles

Environment Comparison Table

Troubleshooting

Next Steps