Skip to content

Configuration

Tessera reads its settings from environment variables at start-up. Everything else (users, SSO, email, AI providers, sharing, OpenLineage, retention) is set in the app under Admin and stored in the data folder.

Environment variables

Variable Default What it does
TESSERA_DATA_DIR ./tessera-data The data folder: metadata database, DuckDB warehouse, uploads, exports, master.key
TESSERA_HOST 127.0.0.1 Address to listen on. The container image uses 0.0.0.0
TESSERA_PORT 8710 Port to listen on
TESSERA_BASE_URL – Public address, for example https://tessera.example.com. Used for SSO redirects, links in emails, the OData feed and share links
TESSERA_SECURE_COOKIES false Set true whenever people reach Tessera over HTTPS. Adds Secure cookies and HSTS
TESSERA_SESSION_HOURS 12 How long a sign-in lasts
TESSERA_MASTER_KEY generated Base64 32-byte key that encrypts stored secrets. If unset, master.key is created in the data folder. Generate one with python -c "import os,base64;print(base64.b64encode(os.urandom(32)).decode())"
TESSERA_IMPORT_DIRS – Extra server folders the Files, SQLite, Delta and Iceberg connectors may read, separated by : (; on Windows)
TESSERA_MAX_UPLOAD_MB 512 Largest file accepted by the upload page
TESSERA_TIMEZONE UTC Time zone for pipeline, alert and subscription schedules, for example America/Vancouver
TESSERA_WORKERS 2 Pipeline runs that may execute at the same time
TESSERA_SCHEDULER_INTERVAL 20 Seconds between scheduler checks
TESSERA_RETRY_BASE_SECONDS 2 First retry delay for failing pipeline steps (doubles each attempt)
TESSERA_QUERY_TIMEOUT 60 Seconds before an interactive query is cancelled
TESSERA_MAX_RESULT_ROWS 10000 Row limit for interactive results (exports and OData page through larger results)
TESSERA_BLOCK_PRIVATE_HTTP false Stop REST, Iceberg REST, OpenLineage, streaming and SFTP connections from reaching private network addresses. Cloud metadata and link-local addresses are always blocked
TESSERA_RATE_LIMIT 1200 API requests per minute per caller (token, session or IP)
TESSERA_METRICS_TOKEN – Bearer token that may read /metrics (otherwise an admin session is required)
TESSERA_LOG_JSON false JSON log lines with request IDs, and an access log
TESSERA_MCP_ALLOWED_ORIGINS – Extra browser origins allowed to call /mcp, comma-separated
TESSERA_TRUST_PROXY_HEADERS false Use the first X-Forwarded-For address as the caller's address (sign-in lockout, rate limits, audit). Turn on only when Tessera is reachable solely through your proxy
TESSERA_SETUP_CODE generated Set the one-time setup code yourself (8+ characters) instead of reading it from the console; useful on hosted platforms

Cloud mode (tessera cloud-run)

For hosts whose disk does not survive a restart. See CLOUDFLARE.md.

Variable Default What it does
TESSERA_CLOUD_BUCKET – S3-compatible bucket for backups (required)
TESSERA_CLOUD_ENDPOINT AWS S3 Endpoint, for Cloudflare R2 https://<account id>.r2.cloudflarestorage.com
TESSERA_CLOUD_ACCESS_KEY_ID / TESSERA_CLOUD_SECRET_ACCESS_KEY – Credentials (or the platform's own role on AWS)
TESSERA_CLOUD_REGION auto Region (R2 uses auto)
TESSERA_CLOUD_PREFIX tessera/ Folder inside the bucket
TESSERA_CLOUD_BACKUP_MINUTES 5 Back up this often when anything changed (also after every pipeline run and on shutdown)
TESSERA_CLOUD_KEEP 48 Backups to keep
TESSERA_CLOUD_RESTORE_KEY – Restore this backup instead of the latest, once

Cloud mode requires TESSERA_MASTER_KEY, because backups deliberately leave the key out.

Command line

tessera serve [--host 0.0.0.0] [--port 8710]          run the server
tessera create-user someone@example.com --role engineer
tessera reset-password someone@example.com            also unlocks the account
tessera backup --out backup.tar.gz [--include-key]    stop the server first, or use Admin → Operations
tessera restore backup.tar.gz [--force]
tessera mcp --url https://tessera.example.com         MCP stdio bridge for desktop AI clients (token in TESSERA_TOKEN)
tessera cloud-run [--port 8710]                       run with data kept in an S3/R2 bucket (cloud mode)
tessera version

Every command accepts --data-dir before the sub-command, for example tessera --data-dir /srv/tessera serve.

Roles

Role Can
viewer Open dashboards, reports and published datasets; ask questions; read the catalog and glossary
analyst Everything a viewer can, plus SQL on published data, Explore, building reports and dashboards, alerts, subscriptions, AI agents and watching streams
engineer Everything an analyst can, plus connections, streams, pipelines, transforms, quality rules, raw and curated data, models
admin Everything, plus users, SSO, SCIM, email, AI providers, row-level security, integrations, sharing, backups and the audit log

Workspaces add per-workspace roles (viewer, contributor, admin) on top; see ENTERPRISE.md.

Health and monitoring endpoints

Endpoint Use
/api/health Liveness: the process answers
/api/ready Readiness: metadata and warehouse are reachable (use for load balancers and container health checks)
/metrics Prometheus metrics: requests, latency, pipeline runs, query cache
/api/docs Interactive REST API reference