Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.tesslate.com/llms.txt

Use this file to discover all available pages before exploring further.

Tesslate OpenSail

​
Overview

All OpenSail configuration is environment-driven. The canonical reader is orchestrator/app/config.py (Pydantic settings). Feature flags live in orchestrator/app/config_features.py. Frontend runtime config reads window._env_.*; build-time config reads VITE_*. Use this page together with:
  • Repo-root .env.example and .env.prod.example
  • docs/guides/environment-variables.md (the exhaustive reference)
  • Kustomize overlays under k8s/overlays/*/backend-patch.yaml
After changing a variable, restart the affected service. In Docker: docker compose restart orchestrator. In Kubernetes: kubectl rollout restart deploy/orchestrator -n tesslate.

​
Required core

​
SECRET_KEY
string
required
JWT signing and general crypto fallback. Never reuse across environments. Generate with python3 -c "import secrets; print(secrets.token_urlsafe(32))".
​
DEPLOYMENT_MODE
string
default:"docker"
docker, kubernetes, or desktop. Selects orchestrator backend, DB driver, task queue, and pub/sub.
​
DATABASE_URL
string
SQLAlchemy async URL. Docker default points at the postgres service. Desktop mode resolves to SQLite automatically.
​
INTERNAL_API_SECRET
string
Shared secret for cluster-internal callers (Volume Hub GC, btrfs CSI) hitting /api/internal/*. Desktop mode ignores.

​
Database

VariablePurpose
POSTGRES_DBDatabase name
POSTGRES_USERDB user
POSTGRES_PASSWORDDB password
POSTGRES_PORTHost port (compose default 5432)
DATABASE_URL=postgresql+asyncpg://tesslate:tesslate@postgres:5432/tesslate
POSTGRES_PASSWORD=dev_password_change_me

​
Redis, pub/sub, task queue

VariablePurpose
REDIS_URLARQ + RedisPubSub connection. Empty string falls back to in-memory for single-process dev.
WORKER_MAX_JOBSConcurrent agent tasks per ARQ worker pod (default 10)
WORKER_JOB_TIMEOUTTask timeout seconds (default 600)
Desktop mode uses LocalTaskQueue (asyncio + apscheduler) and LocalPubSub (in-process). No Redis required.

​
LiteLLM and agent

VariablePurpose
LITELLM_API_BASEProxy URL, e.g. https://your-litellm.example.com/v1
LITELLM_MASTER_KEYMaster key for minting per-user virtual keys
LITELLM_DEFAULT_MODELSComma-separated models granted to new users
LITELLM_TEAM_IDLiteLLM team or access group
LITELLM_EMAIL_DOMAINInternal email domain stamped into LiteLLM users
LITELLM_INITIAL_BUDGETStarting budget USD per user
COMPACTION_SUMMARY_MODELCheap model used for context compaction
DEFAULT_THINKING_EFFORTExtended thinking effort for supported models
AGENT_MAX_COSTGlobal cost cap USD (default 20.0)
AGENT_MAX_ITERATIONSGlobal iteration cap, 0 disables
AGENT_MAX_COST_PER_RUNPer-run cost cap USD (default 5.0)

​
Auth and cookies

​
ALGORITHM
string
default:"HS256"
JWT signing algorithm.
​
ACCESS_TOKEN_EXPIRE_MINUTES
number
default:"30"
Access token TTL.
​
REFRESH_TOKEN_EXPIRE_DAYS
number
default:"14"
Refresh token TTL.
​
CSRF_SECRET_KEY
string
Separate key for CSRF tokens. Falls back to SECRET_KEY.
​
CSRF_TOKEN_MAX_AGE
number
default:"86400"
CSRF token TTL seconds.
​
COOKIE_SECURE
boolean
default:"false"
Set true in production.
​
COOKIE_SAMESITE
string
default:"lax"
lax, strict, or none.
​
COOKIE_DOMAIN
string
Scope cookies to apex, e.g. .tesslate.com, for subdomain access.
​
CORS_ORIGINS
string
Comma-separated allowed origins.
​
ALLOWED_HOSTS
string
Host header allowlist.

​
OAuth providers

All optional. Absence of credentials disables the provider gracefully.
ProviderVariables
GitHubGITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET, GITHUB_OAUTH_REDIRECT_URI
GoogleGOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GOOGLE_OAUTH_REDIRECT_URI

​
SMTP and 2FA

VariablePurpose
SMTP_HOST, SMTP_PORT, SMTP_USERNAME, SMTP_PASSWORD, SMTP_USE_TLS, SMTP_SENDER_EMAILEmail transport for magic links, 2FA codes, and password resets
TWO_FA_ENABLEDRequire 6-digit email 2FA after password login (default false)

​
S3 and object storage

VariablePurpose
S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEYCredentials. Omit on AWS with IRSA.
S3_ENDPOINT_URLCustom endpoint for DO Spaces, MinIO, etc. Omit for AWS S3.
S3_BUCKET_NAMEProjects bucket (default tesslate-projects)
S3_REGIONRegion (default us-east-1)
S3_PROJECTS_PREFIXKey prefix (default projects)

​
Kubernetes (user-project runtime)

VariablePurpose
K8S_DEVSERVER_IMAGEImage for user containers. Minikube uses tesslate-devserver:latest; prod uses an ECR URL.
K8S_IMAGE_PULL_SECRETRegistry pull secret (ecr-credentials in prod)
K8S_STORAGE_CLASSStorageClass for PVCs
K8S_SNAPSHOT_CLASSVolumeSnapshotClass
K8S_SNAPSHOT_RETENTION_DAYSDays to keep soft-deleted snapshots (default 30)
K8S_MAX_SNAPSHOTS_PER_PROJECTMax snapshots in timeline (default 5)
K8S_SNAPSHOT_READY_TIMEOUT_SECONDSSnapshot readiness timeout (default 300)
K8S_HIBERNATION_IDLE_MINUTESAuto-hibernate after N idle minutes (default 10)
K8S_HYDRATION_TIMEOUT_SECONDS, K8S_DEHYDRATION_TIMEOUT_SECONDSHibernation transitions
K8S_PVC_SIZEDefault PVC size per project (default 5Gi)
K8S_ENABLE_POD_AFFINITYKeep multi-container projects on the same node
K8S_RWX_STORAGE_CLASSReadWriteMany class for shared source code
K8S_INGRESS_CLASSIngress class name (default nginx)
K8S_NAMESPACE_PER_PROJECTNamespace-per-project isolation (default true)
K8S_ENABLE_NETWORK_POLICIESCreate NetworkPolicies for project isolation (default true)
K8S_WILDCARD_TLS_SECRETTLS secret for wildcard cert (empty for HTTP)
K8S_INGRESS_DOMAINApex domain for user-project ingress
K8S_USE_S3_STORAGEUse S3 hibernation instead of PVCs (default false)

​
Volume Hub and btrfs CSI

VariablePurpose
VOLUME_HUB_ADDRESSHub gRPC endpoint (default tesslate-volume-hub.kube-system.svc:9750)
TEMPLATE_BUILD_STORAGE_CLASSStorageClass for template builds (tesslate-btrfs)
TEMPLATE_BUILD_NODEOPS_ADDRESSNodeOps gRPC endpoint for template builds
FILEOPS_ENABLEDUse FileOps gRPC service for v2 file operations (default true)
FILEOPS_TIMEOUTFileOps RPC timeout seconds (default 30)
COMPUTE_MAX_CONCURRENT_PODSMax concurrent compute pods (default 5)
COMPUTE_POD_TIMEOUTPod readiness timeout (default 600)
COMPUTE_REAPER_INTERVAL_SECONDSOrphan pod reaper interval (default 60)
COMPUTE_REAPER_MAX_AGE_SECONDSMax pod age before reaping (default 900)
VariablePurpose
WEB_SEARCH_PROVIDERtavily, brave, or duckduckgo (default tavily)
TAVILY_API_KEYTavily API key
BRAVE_SEARCH_API_KEYBrave API key

​
Messaging channels and gateway

VariablePurpose
AGENT_DISCORD_WEBHOOK_URLWebhook for the agent send_message tool
CHANNEL_ENCRYPTION_KEYFernet key for encrypting per-user channel credentials
GATEWAY_ENABLEDEnable gateway runner (default false)
GATEWAY_SHARDShard identifier for multi-instance gateway
GATEWAY_TICK_INTERVALScheduler tick interval seconds
GATEWAY_SESSION_IDLE_MINUTESIdle timeout for gateway sessions
GATEWAY_VOICE_TRANSCRIPTIONEnable voice message transcription

​
MCP (Model Context Protocol)

VariablePurpose
MCP_TOOL_CACHE_TTLTool schema cache TTL seconds (default 300)
MCP_TOOL_TIMEOUTTool call timeout seconds (default 30)
MCP_MAX_SERVERS_PER_USERCap on installed MCP servers per user (default 20)

​
Stripe and billing

VariablePurpose
STRIPE_SECRET_KEY, STRIPE_PUBLISHABLE_KEY, STRIPE_WEBHOOK_SECRETStripe core keys
STRIPE_CONNECT_CLIENT_IDStripe Connect (creator payouts)
STRIPE_BASIC_PRICE_ID, STRIPE_PRO_PRICE_ID, STRIPE_ULTRA_PRICE_IDMonthly subscription prices
STRIPE_BASIC_ANNUAL_PRICE_ID, STRIPE_PRO_ANNUAL_PRICE_ID, STRIPE_ULTRA_ANNUAL_PRICE_IDAnnual prices
CREDIT_PACKAGE_SMALL, CREDIT_PACKAGE_MEDIUM, CREDIT_PACKAGE_LARGE, CREDIT_PACKAGE_TEAMOne-time credit prices (cents)
SIGNUP_BONUS_CREDITS, SIGNUP_BONUS_EXPIRY_DAYSSignup bonus
CREATOR_REVENUE_SHARE, PLATFORM_REVENUE_SHARERevenue split decimals (sum to 1)
USAGE_INVOICE_DAYDay of month to generate usage invoices (1..28)

​
Frontend

VariableModePurpose
VITE_API_URLbuildAPI base URL (empty for Vite proxy, or http://localhost:8000)
VITE_ALLOWED_HOSTSbuildComma-separated host allowlist for Vite dev server
VITE_PUBLIC_POSTHOG_KEY, VITE_PUBLIC_POSTHOG_HOSTbuildPostHog project
window._env_.API_URLruntimeBase URL without /api (frontend code prepends it)
window._env_.POSTHOG_KEY, window._env_.POSTHOG_HOSTruntimePostHog runtime config

​
Domain, ports, Traefik

VariablePurpose
APP_DOMAINApex domain (no protocol)
APP_PROTOCOLhttp or https
APP_PORT, APP_SECURE_PORTPublic HTTP and HTTPS ports
BACKEND_PORTUvicorn port
FRONTEND_PORTVite dev port
APP_BASE_URLFull base URL; defaults to protocol + domain
TRAEFIK_DASHBOARD_PORTDashboard port (dev)
TRAEFIK_BASIC_AUTHhtpasswd admin credential
TRAEFIK_CERT_RESOLVERletsencrypt or cloudflare
CF_DNS_API_TOKENCloudflare DNS token for wildcard certs

​
Desktop

VariablePurpose
OPENSAIL_HOMEDesktop data directory override. Resolved by orchestrator/app/services/desktop_paths.py.
TEST_HELPERS_ENABLEDExpose test-only routes (CI)
BUILD_SHADeployment identifier reported by /api/version

​
Observability

VariablePurpose
LOG_LEVELDEBUG, INFO, WARNING, ERROR, CRITICAL (default INFO)
VITE_PUBLIC_POSTHOG_KEYPostHog project key (empty to disable)

​
Feature flags (Tesslate Apps)

Apps features are gated by TSL_FEATURE_* booleans. Default is off except governance policies. The env variable is the dotted flag name upper-cased with dots replaced by underscores: apps.publish becomes TSL_FEATURE_APPS_PUBLISH.
FlagDefault
apps.manifest_schema_v1, apps.publish, apps.installfalse
apps.runtime.ui, apps.runtime.chat, apps.runtime.scheduled, apps.runtime.triggered, apps.runtime.mcp_toolfalse
apps.hosted_agent, apps.source_view, apps.fork, apps.bundlesfalse
apps.review.stage1, apps.review.stage2, apps.review.stage3, apps.yankfalse
apps.yank.critical_two_admintrue (governance policy)
apps.billing.dispatcher, apps.billing.revenue_splitfalse
apps.triggers.webhook, apps.triggers.mcp_event, apps.triggers.app_invocationfalse
apps.canvas.hosted_agent_node, apps.embedding.postmessagefalse

​
Testing

VariablePurpose
TEST_HELPERS_ENABLEDExpose test-only routes in CI
PLAYWRIGHT_BASE_URLBase URL for Playwright E2E
CI sets SECRET_KEY=test-secret-key-*, DEPLOYMENT_MODE=docker, LITELLM_API_BASE=http://localhost:4000/v1, LITELLM_MASTER_KEY=test-key, and points DATABASE_URL at Postgres on port 5433.

​
Environment comparison

SettingDocker (Local)MinikubeAWS EKS
DEPLOYMENT_MODEdockerkuberneteskubernetes
K8S_DEVSERVER_IMAGEN/Atesslate-devserver:latest<ECR_URL>/tesslate-devserver:latest
K8S_IMAGE_PULL_SECRETN/A(empty)ecr-credentials
K8S_STORAGE_CLASSN/Atesslate-btrfstesslate-block-storage
K8S_WILDCARD_TLS_SECRETN/A(empty, HTTP)tesslate-wildcard-tls
APP_DOMAINlocalhostlocalhoste.g. opensail.example.com
COOKIE_SECUREfalsefalsetrue

​
Next steps

Deployment

Production paths: Docker, Kubernetes, AWS EKS.

Architecture

How the orchestrator, agent, and storage fit together.

Authentication

JWT, OAuth, email 2FA, API keys, and desktop pairing.

API reference

REST surface overview and OpenAPI spec pointer.