Configuration reference

Source of truth

.env.example at the repository root is the authoritative list of environment variables for a self-hosted deployment. You do not need it to start Tessary: every variable has a working default, and docker compose up -d boots on a clone with no .env at all. Copy it when you want to change something:

cp .env.example .env

The sections below group the variables most deployments need to set or understand.

This page does not restate every comment in .env.example. For a variable not covered below, read its comment in the file itself rather than assuming a default.

Database

Compose builds the Postgres connection from these values. You only set TESSARY_JDBC_URL directly if you run the backend outside Compose, against a Postgres you manage yourself.

Variable	Description	Default
`POSTGRES_DB`	Name of the Postgres database.	`tessary`
`POSTGRES_USER`	Postgres user Tessary connects as.	`tessary`
`POSTGRES_PASSWORD`	Password for `POSTGRES_USER`. The database publishes no host port, so it is reachable only from the Compose network; set your own if you publish that port or share the host.	`tessary`
`POSTGRES_DATA_DIR`	What backs the Postgres data volume. A bare name is a Docker named volume; a path (`/data/postgres`) is a host bind. The default keeps the database inside Docker, so a fresh install leaves nothing else on disk.	a named volume (`tessary_tessary-postgres-data`)

Secrets

Variable	Description	Default
`TESSARY_SECRET_KEY`	AES-256-GCM key Tessary uses to seal secrets it stores, such as provider API keys.	A placeholder, published in `docker-compose.yml`

Generate a key with:

openssl rand -base64 32

The shipped default is not a secret. It is written in docker-compose.yml in the public repository so a first boot needs no configuration, which means anyone who reaches the database of an instance still using it can decrypt every credential in there. Replace it before the instance holds anything real: see Secure the instance. Tessary warns on every boot that runs the default, and refuses to start once SITE_DOMAIN is set.

Changing this key makes everything already sealed with the old one unreadable, so pick a value per environment and keep it. That is also what a restore depends on: a pg_dump carries the ciphertext and not the key, so the target host needs the same TESSARY_SECRET_KEY to read the credentials back.

Auth

Variable	Description	Default
`TESSARY_AUTH_COOKIE_PASSWORD`	Key for the session cookie. Used regardless of which identity provider you use.	A placeholder, published in `docker-compose.yml`
`TESSARY_AUTH_FRONTEND_URL`	Where Tessary sends users after sign-in and sign-out.	Derived from `HTTP_PORT`, so it follows the port Compose actually publishes
`WORKOS_API_KEY`	WorkOS API key, for bring-your-own SSO.	Optional, ships blank
`WORKOS_CLIENT_ID`	WorkOS client ID, for bring-your-own SSO.	Optional, ships blank

TESSARY_AUTH_COOKIE_PASSWORD is the most urgent of the three placeholders. The sealing key above needs database access to exploit; this one does not. Anyone can forge a session cookie against an instance still running the published default. Replace it before anything but your own machine can reach the instance: see Secure the instance.

The default identity provider is local email and password; it needs none of the WorkOS variables. Set WORKOS_API_KEY and WORKOS_CLIENT_ID only if you want to bring your own WorkOS organization for SSO instead.

Who may create an account is a setting, not an environment variable: an owner or admin sets it under Settings → Members → Sign-up policy, and it is enforced by the backend on every path that creates an account, including a first sign-in through WorkOS. It is stored on the first organization created on the install and governs the whole instance, so a self-hoster who signs up first owns it. Anyone the policy admits later gets an organization of their own, and that organization sees the policy read-only, named with the organization that governs it.

Mode	Who gets an account
Anyone (`open`)	Anyone who can reach the instance. The default, on a fresh install and after an upgrade.
Listed email domains (`domain`)	Addresses at the domains you list, such as `acme.com`. Exact domains, not patterns.
Invitation only (`invite`)	Nobody without a pending invitation from Settings → Members.

In every mode a pending invitation admits its address, so a contractor on a personal address can be let in under domain, and invite is the invitation list itself. Admission and membership are different things: someone the policy admits creates an account with an organization of their own, while an invitation from Settings → Members both admits them and joins them to yours. The policy gates account creation only: tightening it never removes a member or blocks an existing member’s next sign-in, and while the instance has no account at all any mode admits the first one. A refused sign-up creates nothing and answers 403 AUTH.SIGNUP_REFUSED; the WorkOS callback sends the visitor back to the sign-in screen with that reason. Each change is written to the audit log, and the setting is refused through the raw organization settings endpoint so it can only change through the validated route. The same setting is readable and writable over the API, for an owner or admin of the governing organization: GET and PUT /api/orgs/{orgSlug}/signup-policy with a body of {"mode": "domain", "domains": ["acme.com"]}. If you are putting the instance on a real hostname, set this before anyone else can reach it.

Ingest buffer

Between the OTLP endpoint and the database sits a buffer. The default needs nothing beyond the stack you already run; the alternative is a broker, for installs that want an accepted batch to survive a restart.

Variable	Description	Default
`TESSARY_INGEST_SPOOL_MODE`	`memory`: a 200 means the batch is queued in the backend process, the buffer sheds with `503 + Retry-After` when its byte budget is full, and a restart loses what was queued (stock exporters retry a 503, so a shed costs latency, not data). `kafka`: a 200 means the batch is persisted by a Kafka-API broker before the response, and nothing acknowledged is lost on restart.	`memory`
`TESSARY_INGEST_SPOOL_KAFKA_BOOTSTRAP_SERVERS`	The broker, in `kafka` mode. The bundled single-node Redpanda answers at the default.	`redpanda:9092`
`TESSARY_INGEST_SPOOL_KAFKA_REPLICATION_FACTOR`	Copies the broker keeps of each accepted batch, applied when the spool creates its topics. The bundled single-node Redpanda can only satisfy `1`. Against your own multi-broker cluster this is what decides whether `kafka` mode’s promise survives a broker failure: at `1`, an acknowledged batch is on one machine’s disk, and losing that machine loses data the API already answered `200` to. Set `3` there. The broker is told to wait for two copies whenever this is above `1`.	`1`
`TESSARY_INGEST_SPOOL_KAFKA_CONSUMERS`	Drainer threads in `kafka` mode, each with its own consumer; the broker spreads the eight partitions across them, and one project’s batches stay on one partition so they never run concurrently. Raise it with cores, up to the eight partitions (a ninth consumer would sit idle); `memory` mode always runs one.	`4`

To use the bundled broker, set the mode and start the stack with its profile:

TESSARY_INGEST_SPOOL_MODE=kafka

docker compose --profile kafka up -d

The broker and the larger backend heap that goes with it need a bigger host than the default configuration assumes. Host sizing states the smallest one to run this mode on. Redpanda keeps its log in the redpanda-data volume, listens on the internal network only, takes about 512 MB, and runs with write caching off so the acknowledgement the backend waits for means the batch is on disk. Any Kafka-compatible broker you already run works instead: set the bootstrap address and leave the profile off. The topics (tessary.ingest, eight partitions keyed by project, and tessary.ingest.dead-letter for a batch that exhausted its write retries) are created the first time the backend reaches the broker. In both modes /actuator/health carries an ingest component with the buffer’s depth, the age of its oldest unprocessed batch, its dead-lettered count and whether the drainer is alive; it reports DOWN when the drainer is dead or the oldest batch is older than TESSARY_INGEST_SPOOL_MAX_LAG_MS (five minutes by default, 0 disables).

Data retention

An hourly sweep deletes traces and classifier detections older than their retention period. The install-wide defaults are environment variables; 0 means keep forever.

Variable	Description	Default
`TESSARY_RETENTION_TRACE_TTL_DAYS`	Days a trace and its content are kept. `0` keeps them forever.	`90`
`TESSARY_RETENTION_DETECTION_TTL_DAYS`	Days a classifier detection is kept. `0` keeps them forever.	`90`
`TESSARY_RETENTION_ENABLED`	The sweep itself. `false` deletes nothing, whatever the periods say.	`true`

An owner or admin can override either period for one project under Settings → Data retention, which is also GET and PUT /api/orgs/{orgSlug}/projects/{projectSlug}/retention. The PUT body replaces both overrides at once: {"traces": 30, "detections": null} sets a 30-day override for traces and clears the detections override, so the install default applies to it again; an absent key clears too. The page shows the install default next to each override, and the sweep enforces exactly what the page shows. A trace that an open finding still cites is kept past its period until the finding closes.

LLM providers

LLM providers have no environment variables. Configure them in-app, under Settings then Providers. Tessary seals whatever you enter there with TESSARY_SECRET_KEY. A TypeSafe key serves only the frustration classifier. An OpenRouter key serves triage, RCA, and the frustration classifier. The one exception is an ambient region for Bedrock:

Variable	Description	Default
`AWS_REGION`	Region Tessary uses for Bedrock calls that don’t otherwise specify one.	Blank

Classifier encoder service

Variable	Description	Default
`TESSARY_OBSERVER_ENCODER_URL`	URL of the groundedness model server.	Blank
`TESSARY_OBSERVER_ENCODER_API_KEY`	API key for the groundedness model server.	Blank
`TESSARY_GROUNDEDNESS_CLASSIFIER_MODE`	`dev` scores whenever the model answers. `production` is a GPU instance that wakes on a schedule and stops when idle, so Tessary waits 30 minutes after it catches up before scoring again.	`dev`
`TESSARY_OBSERVER_ENCODER_PROBE_INTERVAL_MS`	How often the backend checks the model server’s `/healthz`. While it doesn’t answer, groundedness pauses and picks up where it left off once it does.	`60000`

Frustration shadow model

Optional. A second decision model every Frustration turn is re-sent to after the configured provider has scored it, with both answers kept side by side in frustration_shadow and nothing a customer sees changed. It is how a self-hosted model is measured against the provider on real traffic before it replaces anything.

Variable	Description	Default
`TESSARY_FRUSTRATION_SHADOW_URL`	Base URL of a server that speaks TypeSafe’s `/v1/systemone` wire format (Eikos, Kev, Winnow and the like) and answers `GET /health`. Blank disables the shadow.	Blank
`TESSARY_FRUSTRATION_SHADOW_API_KEY`	Bearer key sent with each request, if the server wants one.	Blank
`TESSARY_FRUSTRATION_SHADOW_MODEL`	The `model` field of each request; whatever the server expects.	`decider`
`TESSARY_FRUSTRATION_SHADOW_SWEEP_MS`	How often the backend probes the server and drains the backlog. A server that stops itself when idle must stay up longer than this.	`300000`
`TESSARY_FRUSTRATION_SHADOW_BATCH`	Turns fetched and sent per batch.	`100`
`TESSARY_FRUSTRATION_SHADOW_BUDGET_MS`	The most one sweep runs before it yields to the next.	`1200000`

The backlog is every assessment whose request body retention has not yet removed and that has no shadow row; a server that is down just leaves it waiting. To read the comparison, count frustration_shadow rows by frustrated against reference_frustrated; the sweep also logs the running totals as frustration.shadow.sweep. The groundedness model needs a GPU: a Mac with Apple silicon for development, or a GPU instance on AWS for production. The setup file your coding agent follows sets these on a Mac, or prints them for you to add on AWS: on a Mac or on AWS. The frustration classifier does not use this server; it needs an OpenRouter or TypeSafe key, stored under Settings then Providers. See Groundedness needs a GPU in Setup.

Agentic launcher and sandbox-runner

Variable	Description	Default
`TESSARY_OBSERVER_AGENTIC_LAUNCHER_URL`	URL of the sandbox-runner service that runs agentic analysis (RCA, triage, drift detection).	Auto-wired by Compose to `http://sandbox-runner:8080`
`SANDBOX_BACKEND`	Where sandbox-runner launches sandboxed agent sessions: `docker` (sibling containers), `e2b` (Tessary-hosted microVMs), or `local` (the host’s logged-in `claude`).	`docker`
`E2B_ANALYZER_TEMPLATE`	The E2B template sandbox-runner starts agent sessions from, when `SANDBOX_BACKEND` is `e2b`. Leave it unset. The launcher runs scripts that its own release puts in the template, so it refuses to start on a template from a different release.	`tessary/tessary-agent-sandbox:<TESSARY_VERSION>`
`SANDBOX_WORK_VOLUME`	Name of the Docker volume sandbox-runner shares with the sibling containers it spawns. The launcher hands this exact string to the Engine API, so it is the volume’s real name and not a project-prefixed one.	`tessary-sandbox-work`
`AGENT_PROVIDER`	Where the sandboxed agent runs: unset for SigV4 Bedrock, `anthropic` for the first-party Anthropic API, or `bedrock-api-key` for Bedrock over a bearer token.	Unset (SigV4 Bedrock)
`TESSARY_OBSERVER_AGENTIC_LAUNCHER_API_KEY`	The bearer the backend presents to the sandbox launcher, and the launcher checks it against. Anyone holding the published default can drive the launcher into spawning containers on the host, so replace it before the instance holds anything real: see Secure the instance.	A placeholder, published in `docker-compose.yml`

GitHub integration

Connecting a GitHub repository needs no environment variables. Connect one in-app, under Settings then Git integration, through the manifest wizard or with a personal access token. See Optional: connect a GitHub repository in Setup.

Telemetry

Variable	Description	Default
`TESSARY_TELEMETRY_ENABLED`	Sends one anonymous, opt-out heartbeat to home.tessary.ai.	`true`

Set TESSARY_TELEMETRY_ENABLED to false for zero outbound network calls, including DNS lookups, to home.tessary.ai.

A default deployment has exactly one outbound destination: home.tessary.ai. There is no Google Fonts call, no analytics SDK, and no other third-party host a default install reaches. The product’s one non-Geist typeface (the wordmark) ships as a local font file, not a call to Google’s CDN. Nothing else in this section is an exception to that; it exists to say precisely what the backend sends there and fetches from there. What the ping sends, once on backend start and then every 6 hours:

Field	Example	What it is
`contract_version`	`1`	Schema version of this payload.
`instance_id`	a v4 UUID	Generated once at first boot. Identifies an instance, never a person or an org.
`ping_seq`	`41`	How many pings this instance has sent before this one.
`sent_at`	an ISO-8601 UTC timestamp	When the ping was generated.
`app_version`	`"2026.9.1"`	The running app’s version.
`edition`	`"open"`	Which build sent the ping.
`os` / `arch`	`"linux"` / `"arm64"`	Host OS family and CPU architecture.
`counts`	`{"projects": 3, "spans": 1204551, "findings": 88, "cases": 12, "l1": 40210}`	Install-wide usage totals: projects, spans ingested, findings, cases, and classifier detections. One number each for the whole install, never per org or project.
`price_book`	`{"digest": "a5ad23f7…", "schema_max": 1}`	Which model price book this install prices from, by its sha256.

It never carries an email address, an org or project name, trace/prompt/dataset content, a license key, or a retained IP address. What the backend fetches, on the same schedule: the model price book. It requests /v1/pricing/manifest.json, a few hundred bytes naming the current book’s hash, and downloads the book itself (about 2 MB) only when that hash is one it does not already hold. It checks the download against the hash before using it. Neither request carries a body or any identifier. New prices apply to spans ingested afterwards; costs already recorded never change. The full field-by-field contract lives at devdocs/reference/telemetry-contract.md in the repository for anyone auditing the wire format against the running code.

What leaves your network

The complete set of destinations a self-hosted instance may reach, and when. Anything else is a defect.

Destination	When	Why it is permitted
`home.tessary.ai`	Once at backend start and every 6 hours, only while `TESSARY_TELEMETRY_ENABLED` is `true`	The heartbeat and the price book check above. Off, the name is never even resolved.
`home.tessary.ai` (paid, licensed installs only)	Hourly, regardless of `TESSARY_TELEMETRY_ENABLED`	A paid self-hosted install under a license pulls its signed license check-in document. The open edition never makes this call; the paid overlay’s README documents it.
`docker.io`	`docker compose pull`, before the stack runs; and once more at the first analysis, for the agent image the sandbox runner pulls lazily unless you pull it first	The published images. The check pulls or builds them before its observation window opens, so a pull during operation is a failure; the agent image is the one exception, named here because the check’s walk stops before the first analysis.
Nothing from the bundled Redpanda	Only with `--profile kafka`	Redpanda’s metrics reporter (`enable_metrics_reporter`, the one setting that phones home) is off in the flags the profile starts it with.
`acme-v02.api.letsencrypt.org`	Only when `SITE_DOMAIN` names a real host	Caddy’s certificate issuance. Unset, Caddy serves plain HTTP and contacts nobody.
The provider, alert and Git endpoints you configure	Only after you enter a credential in Settings	Your own integrations. A default boot has none.
The groundedness model server you set up	Only when `TESSARY_OBSERVER_ENCODER_URL` is set: a health check every `TESSARY_OBSERVER_ENCODER_PROBE_INTERVAL_MS`, and a scoring request for each answer while the groundedness classifier is on	Your own Mac or AWS instance. Tessary sends each answer with its retrieved documents and the user’s question, or with its prompt when it has no documents. The variable ships blank, so a default boot never contacts it.

The machine that runs the groundedness model makes its own downloads, separate from Tessary’s containers: serve.py from GitHub, the Python packages it runs on, and the model’s weights from Hugging Face. See What is sent, and to whom. Turning it off costs one thing: price updates between releases. TESSARY_TELEMETRY_ENABLED=false gives Tessary no install-count or activation visibility into your deployment, and your instance stops checking for newer model prices, so it prices from the book bundled in the release you run until you upgrade. There is no license check, feature gate, or other in-app behavior that depends on reaching us. Tessary will never use your conversations to train or improve any model. No exceptions, no toggle. This is an absolute guarantee, not a default you could accidentally switch off. See devdocs/reference/principles.md § “Product & positioning” for the full argument.

Ingest and OTLP

Tessary can receive traces directly over OTLP (OpenTelemetry Protocol) instead of pulling them from a connected source.

Variable	Description	Default
`TESSARY_INGEST_OTLP_TRANSPORT`	Transport the OTLP ingest endpoint accepts: `HTTP`, `GRPC`, or `BOTH`.	`HTTP`
`TESSARY_INGEST_OTLP_GRPC_PORT`	Port the gRPC transport binds, when enabled.	`4317`

TLS and domain

These variables apply to the prod Docker Compose stack (docker-compose.yml). The dev stack always serves plain HTTP on port 8000. Custom domain walks through them.

Variable	Description	Default
`SITE_DOMAIN`	The one public-origin variable: a bare hostname such as `tessary.acme-corp.com`. Unset serves plain HTTP on `HTTP_PORT` (default 80) only. Set, it is served the way `TLS_MODE` says, and the sign-in landing origin, the WorkOS callback and the agentic lanes’ callback origin are derived from it. A value carrying a scheme, port or path is refused at boot.	Unset
`TLS_MODE`	`acme` (Caddy obtains a Let’s Encrypt certificate over TLS-ALPN-01), `owncert` (your certificate and key mounted at `/certs/tls.crt` and `/certs/tls.key` in the frontend container), or `upstream` (plain HTTP behind a terminator you run).	`acme`
`ACME_EMAIL`	Your address for the Let’s Encrypt account. Required when `SITE_DOMAIN` is set in `acme` mode; there is no default.	Blank
`TRUSTED_PROXIES`	Space-separated CIDRs of the proxy in front of Tessary in `upstream` mode. Forwarded headers are honoured from these addresses only.	Blank
`TESSARY_AUTH_FRONTEND_URL`	Where the browser lands after sign-in and sign-out. Derived from `SITE_DOMAIN` when set; otherwise from `HTTP_PORT`. An explicit value must name the same host as `SITE_DOMAIN`.	Derived
`WORKOS_REDIRECT_URI`	The WorkOS callback, registered in the WorkOS dashboard. Derived from `SITE_DOMAIN` when set.	Derived
`HTTP_PORT`	Host port mapped to the frontend container’s port 8000.	`80`
`HTTPS_PORT`	Host port for HTTPS, when `SITE_DOMAIN` is set in `acme` or `owncert` mode.	`443`

SITE_DOMAIN is also how Tessary knows this instance is reachable from outside the host. Setting it while any of the three placeholder keys is still on its shipped value refuses the boot, naming the key. That is what makes the placeholders safe to ship: they cannot follow you onto a public host.

Removed configuration

These keys and blocks belonged to features Tessary has removed entirely, not merely disabled. Spring ignores an unbound key, so setting one has no effect: it will not turn the feature back on.

The TESSARY_SANDBOX_* block
The TESSARY_SYNTH_* block
TESSARY_CI_GATE_BLOCK_ON_REGRESSION
TESSARY_RISK_MODEL_ENABLED
The TESSARY_GRADING_* keys
TESSARY_STORAGE_EMBED_ENABLED
TESSARY_EMBEDDING_BASE_URL

Get started

Tessary Cloud

Instrument

Concepts

Classifiers

Reference

Self-hosting

Configuration reference

Source of truth

Database

Secrets

Auth

Ingest buffer

Data retention

LLM providers

Classifier encoder service

Frustration shadow model

Agentic launcher and sandbox-runner

GitHub integration

Telemetry

What leaves your network

Ingest and OTLP

TLS and domain

Removed configuration

​Source of truth

​Database

​Secrets

​Auth

​Sign-up policy

​Ingest buffer

​Data retention

​LLM providers

​Classifier encoder service

​Frustration shadow model

​Agentic launcher and sandbox-runner

​GitHub integration

​Telemetry

​What leaves your network

​Ingest and OTLP

​TLS and domain

​Removed configuration

Source of truth

Database

Secrets

Auth

Sign-up policy

Ingest buffer

Data retention

LLM providers

Classifier encoder service

Frustration shadow model

Agentic launcher and sandbox-runner

GitHub integration

Telemetry

What leaves your network

Ingest and OTLP

TLS and domain

Removed configuration