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 source credentials and 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 more urgent of the two 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 organization, which in the open edition is the whole instance.

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: 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

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. 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 classify-service encoder endpoint.	Blank
`TESSARY_OBSERVER_ENCODER_API_KEY`	API key for the encoder endpoint.	Blank

Both ship blank, and in the open edition they stay blank: the model weights classify-service loads are gated and not published, so the frustration and groundedness classifiers are unavailable rather than merely unconfigured. See Encoder-based classifiers are unavailable in the open edition in Setup, and the classifier section of Troubleshooting.

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`
`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)

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 one ping carries. What the ping sends, once on backend start and then every 24 hours:

Field	Example	What it is
`contract_version`	`1`	Schema version of this payload.
`install_id`	a v4 UUID	Generated once at first boot. Identifies an install, never a person or an org.
`edition`	`"open"`	Which build sent the ping.
`app_version`	`"2026.9.1"`	The running app’s version.
`os` / `arch`	`"linux"` / `"arm64"`	Host OS family and CPU architecture.
`org_count_bucket` / `project_count_bucket`	`"1-5"`	Coarse, bucketed counts — never an exact number.
`trace_volume_bucket`	`"1k-10k"`	Coarse, bucketed daily trace-ingest volume — never an exact count, and never trace content.
`timestamp`	an ISO-8601 UTC timestamp	When the ping was generated.

It never carries an email address, an org or project name, trace/prompt/dataset content, a license key, or a retained IP address. The full field-by-field contract, including the closed bucket enums, 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; scripts/check-zero-egress.sh in the repository boots the stack on a network with no route out, points every service at a DNS sink that records each name asked for, runs the setup page’s steps end to end with the heartbeat turned off, and fails on any name outside this table, on any image pulled after the stack is up, and on any host named anywhere in the files the frontend serves, lazily loaded ones included, that is not on its enumerated list of never-fetched strings. The same run turns the heartbeat back on and requires the one permitted lookup to appear, so the check is known to be able to fail. Two limits the check states rather than hides: the frontend keeps a route out for its published port, so a connection it made to a bare IP address (never a name) would go unobserved, and its only configured egress is certificate issuance; and the sandbox runner pulls the agent image at the first analysis, which the check’s walk never reaches, so that pull is listed below rather than measured.

Destination	When	Why it is permitted
`home.tessary.ai`	Once at backend start and every 24 hours, only while `TESSARY_TELEMETRY_ENABLED` is `true`	The heartbeat above. Off, the name is never even resolved.
`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.

Turning it off costs nothing functional. TESSARY_TELEMETRY_ENABLED=false gives Tessary no install-count or activation visibility into your deployment — that is the entire effect. There is no license check, feature gate, or in-app behavior that depends on the heartbeat 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, backed by two guard tests in the codebase (NoSharedModelTrainingGuaranteeTest, PriorContributionGuardTest) that fail the build if this ever stops being true.

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 either sealing key is still on its shipped placeholder 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

Self-hosting

Legal

Configuration reference

Source of truth

Database

Secrets

Auth

Ingest buffer

Data retention

LLM providers

Classifier encoder service

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

​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

Agentic launcher and sandbox-runner

GitHub integration

Telemetry

What leaves your network

Ingest and OTLP

TLS and domain

Removed configuration