Environment reference

Use this reference to find a deployment variable, its default and the process that needs it. The project .env is one way to supply values; container environment settings and secret-manager injection are also deployment inputs. The example environment file carries the corresponding source configuration.

After changing an environment value, recreate the consuming services through your deployment workflow. docker compose restart retains the container’s existing environment. File-based organization configuration has a separate lifecycle.

How to read this page

Tables list names, defaults, and purpose. Required values must reach the consuming service; deployment tooling may generate some of them. Optional values can remain unset. A documented default can come from the shipped Compose configuration rather than the process itself.

Use the example file alongside this reference and inspect your effective service environment before diagnosing a missing value.

Domain identity (required at first boot)

SITE_URL identifies the canonical public origin. Keep scheme, hostname, and port consistent with the browser address and registered callbacks; BASE_PATH supplies a deployment path prefix. A trailing slash is normalized by the proxy. Additional addresses belong in ADDITIONAL_SITE_URLS as bare origins. Invalid additional origins stop backend startup.

The prose documentation uses its own origin. On the platform origin, /docs opens the interactive API reference and /openapi.json serves its schema. DOCS_URL changes the proxy’s docs host; it does not install the docs service or rewrite links in existing client bundles. The SEO tooling’s TALE_DOCS_URL and the docs service’s build/runtime path prefix DOCS_BASE_URL are separate settings.

TLS

selfsigned runs Caddy with a generated cert — the browser warns, fine for development. letsencrypt requires a real domain and ports 80/443 reachable from the public Internet. external makes Caddy serve plain HTTP; an upstream reverse proxy terminates TLS.

Security secrets (required)

Replace the values that ship in .env.example before exposing the instance — they are intentionally insecure placeholders.

Database

Tale keeps two databases: the operational store (tale_app — agents, runs, the audit log) and the knowledge corpus (tale_knowledge — document chunks, embeddings, crawled pages). A production stack folds both into one ParadeDB service (db, port 5432, aliased knowledge-db). Both share DB_PASSWORD, and the corpus can be pointed at external infrastructure on its own.

The auto-constructed operational form is postgresql://tale:${DB_PASSWORD}@db:5432/tale_app (override the database name with APP_DB_NAME). The knowledge corpus lives in tale_knowledge with the private_knowledge and public_web schemas. These variables set the deployment defaults every organization shares; an organization can additionally point its own corpus and its own bucket at infrastructure of its own under Settings > Data residency (per-organization files, applied live, no restart), covered in Data residency.

Two things to know before pointing either database at infrastructure of your own:

• The knowledge corpus needs pgvector installed. Tale creates its schemas and tables on a database that starts empty, but it never installs extensions — the chunk table has a vector column, so CREATE EXTENSION vector; has to have been run on the target database first. ParadeDB's pg_search is optional: without it, search degrades to vector-only rather than failing. The operational database needs no extensions at all.
• Use a direct or session-compatible Postgres connection. Job notifications, migration locks, and prepared statements need session semantics. Validate any managed connection proxy against those requirements.

Object store

Files and media use S3-compatible storage. These variables configure the deployment default. An organization’s explicit connection takes precedence; an unavailable default does not imply that every organization’s own bucket is unavailable.

The packaged proxy exposes the bundled store’s object route to browsers without publishing the store’s administration port. An external store can be reached directly through its configured public endpoint.

How these variables reach the running deployment

At startup, the backend reconciles default/object-storage/connection.json with its environment. Apply changed values by recreating backend-api and backend-worker. The startup messages identify these outcomes:

To manage the store by hand instead, set "managedBy": "operator" in connection.json; the backend then never touches that file. A file with no managedBy at all — written before this behaviour existed — is taken over only if it still names the same bucket at the same endpoint the environment does; if you had repointed it by hand, that edit is kept.

Bucket permissions: the backend checks the bucket exists (HeadBucket) and creates it only if it does not. A key that may read, write and delete objects but not create buckets is therefore fine, as long as you create the bucket yourself. Presigned uploads and downloads run in the browser, so an external bucket also needs a CORS policy allowing your deployment's origin with GET, PUT and HEAD — see Data residency.

Audit log privacy

A pepper pseudonymizes personal data recorded after failed sign-ins. Earlier releases also generated TALE_AUDIT_SIGNING_KEY and TALE_AUDIT_SIGNING_KEY_PREVIOUS. Nothing reads either, so you can keep or delete an existing value.

See Audit log integrity for the verification model.

Observability

Setting METRICS_BEARER_TOKEN exposes the metrics endpoints behind the token: /metrics/platform, /metrics/backend (the application backend's metrics), and /metrics/sla-rules. See Observability config for the scrape config.

Provider secrets encryption

SOPS protects supported configuration secret sidecars. Current provider credentials in the database use ENCRYPTION_SECRET_HEX, listed with the security secrets above.

Without an age key, the SOPS helper writes supported sidecars as plaintext at mode 0600; existing encrypted files still require their key. Read Secrets with SOPS before changing either variable.

Provider credentials may instead reference a variable under TALE_PROVIDER_KEY_ (maximum name length 40). Subscription-broker credentials use the separate TALE_TOKEN_SOURCE_ prefix (maximum 60). These fields store variable names, not secret values. Inject values into the backend processes and recreate the consumers when values change. Providers describes this setup.

Connector OAuth apps

OAuth connectors (Gmail, Google Drive, Outlook, Teams, Slack, …) resolve their vendor app per organization first: an app configured under Settings > Connectors > OAuth apps wins for that org. The environment supplies the deployment-wide default underneath (and is the only source for Slack, whose inbound event verification runs before any org is known). For each connector slug:

Register ${SITE_URL}${BASE_PATH}/api/connectors/oauth2/callback on the vendor app, and for Slack also ${SITE_URL}${BASE_PATH}/api/connectors/slack/events as the Events Request URL. Details: Connectors (develop).

Knowledge cloud import (Documents)

Per-user OneDrive / Google Drive authorizations for Knowledge → Documents are separate from org connectors and from login. An org-level app configured under Settings > Connectors > OAuth apps takes precedence here too — the google-drive entry is shared with the connector lane, and OneDrive / SharePoint (Knowledge import) has its own entry. The chains below resolve wherever the org has not configured one. Register this redirect URI on the Microsoft (or Google) app:

${SITE_URL}${BASE_PATH}/api/cloud-import/oauth2/callback

Credential resolution for OneDrive (first match wins):

Single-tenant Entra app registrations must use a tenant-specific authorize URL — /common fails with AADSTS50194. Set the tenant ID (or organizations / common for a multi-tenant app). When unset, Tale falls back to the org's Entra SSO issuer tenant if configured.

The Microsoft consent screen requests Graph Files.Read and Sites.Read.All (list/download OneDrive and SharePoint), User.Read (account label), and offline_access (refresh token for sync). That grant is intentional and per user — it is not attached by signing in to Tale.

Google Drive uses a dedicated app only (no login-app fallback):

Register the same cloud-import callback URI on the Google OAuth client. Consent requests drive.readonly and userinfo.email.

Feature flags

These variables configure backend authentication, file events, and operator permissions. Recreate the consuming backend roles when their environment changes; changing only the web container is insufficient.

The private-crawl opt-in affects two boundaries: website registration and crawler requests, and validation of a product’s imageUrl. Without it, a private website target returns 400 WEBSITE_DOMAIN_NOT_CRAWLABLE; a private product image URL returns 400 INVALID_BODY. Product validation checks the hostname string without fetching the image or resolving DNS. Website registration and crawling also check resolved addresses. Enable the flag only for a deployment that needs these private destinations; it is separate from the private-provider flag.

Deployment topology

These values shape the application roles of a workspace deployment: the replica counts, which tale deploy reads from the project environment and clamps to the supported range with a warning, and how much work one worker replica takes on at once.

A workspace rollout temporarily runs both colors. Plan capacity for that overlap. Increase the role whose measured workload is the bottleneck; more replicas also increase database connections and memory use. See Upgrades.

Sessions

Leave it unset to keep the default session lifetime. When set, an idle session expires server-side once the window elapses, while an active one keeps sliding forward on each request. Org admins can tighten the effective window per organisation — never loosen it past this cap — via the session idle timeout governance policy; idle sessions under that policy are revoked by a sweep that runs about every five minutes.

Support link

Set it to your own help desk so people who hit an error reach the team that runs your deployment. Where the error screen knows the organization, the link adds organizationId=<id> to the query string, after any query the URL already carries, and replaces an organizationId the URL already has. Any other value, such as mailto: or a URL without a scheme, is ignored with a warning in the platform service's log, and the link keeps the default.

Sandbox infrastructure

The sandbox spawner reads the settings below. Pass them into its environment and recreate that service after a change. SANDBOX_MAX_SESSIONS sets the capacity shared by all organizations; an organization's three workload limits add up automatically and cannot be saved above that capacity. Manage those limits in Sandboxes, where actual runtime counts and host measurements appear separately from workload allocations.

At full capacity, the spawner can stop a released, unpinned idle session before the idle timeout to admit new work. The daemon must confirm that no work is in progress; busy sessions and sessions with unknown state are protected. Stopping compute preserves the persistent workspace directory or volume. If no safe session can be reclaimed, admission remains blocked by the deployment capacity.

Size session capacity

Start with 8, then test the tasks your deployment will run together. Browser rendering and Docker builds have different peaks; include agents, workflows and crawling across all organizations. A free session slot does not guarantee enough resources, and the spawner does not automatically adjust this setting to host memory.

On Docker, sample resource use while representative tasks overlap. Repeat this command during the run; an idle snapshot does not show task peaks:

docker stats --no-stream --format 'table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}'

Subtract the operating system, platform services, databases, build-cache helpers and a safety margin from host memory. Divide the remaining memory by the measured peak per active session and round down. For example, a 32 GiB host with 8 GiB set aside and a measured peak of 3 GiB per session gives (32 - 8) / 3 = 8 sessions. This is a sizing example, not a benchmark. For mixed workloads, budget their simultaneous peaks together and check CPU saturation and task duration before raising the limit.

An agent's 4 GiB or 8 GiB memory limit is a ceiling, not memory reserved at startup. Eight agents running Docker builds can therefore require much more memory than eight mostly idle sessions. Measure under representative load and keep headroom; increase capacity to 16 or higher only when the host can sustain it. Before lowering capacity, reduce any organization totals that exceed the new value. The default organization limits total 6, so a smaller deployment capacity also needs smaller organization limits.

Apply a capacity change

Add or update this line in the deployment's .env, keeping its other entries. Explicit values remain in effect across upgrades; the default of 8 applies when the variable is unset.

SANDBOX_MAX_SESSIONS=8

For a Compose stack you manage yourself, recreate only the sandbox service using its existing local image:

docker compose up -d --no-deps --no-build --pull never sandbox

Use the same project, -f files and environment-file options as the running stack. A restart alone does not load an edited .env. For CLI-managed installations, apply the change through the deployment workflow in Upgrades. On Kubernetes, set the variable on the sandbox spawner Deployment and roll out that Deployment.

Confirm the new deployment capacity in Sandboxes. With organization limits at 2/2/2 and deployment capacity at 8, the total reads 6 / 8. Existing organization settings are preserved; saving still requires their total to fit the current capacity. Changing the capacity does not increase any container's CPU or memory limit.

After an upgrade

The default capacity used to be 16, and organizations created before this release were seeded with limits of 2/4/4, a total of 10. A deployment that never set SANDBOX_MAX_SESSIONS therefore starts the new version with a capacity of 8 and organizations whose saved total exceeds it. Running work is not affected, and each organization keeps admitting work under its saved limits; only saving the Sandboxes page is blocked until its total fits, and lowering limits still saves. Either set SANDBOX_MAX_SESSIONS=16 explicitly to keep the previous capacity, or ask each affected organization to lower one limit.

Docker build caches

Docker build caches are isolated by organization. Each organization uses one privileged builder and three unprivileged registry mirrors. Once no session may still use them, the helpers stop after the session idle window; the next build restarts them with their cache volumes intact. Networks and volumes remain available for reuse. Kubernetes sessions use their own inner Docker builder; Kubernetes reconciliation does not invoke the Docker CLI for these helpers.

The spawner packs organization bridges into the first available Docker address pool before moving to the next. Its default /23 gives each bridge 512 addresses; an otherwise unused /16 holds 128 such organization networks. Smaller subnets configured in Docker’s pools remain smaller. It excludes existing Docker networks, routes and DNS server addresses on the Docker daemon’s host, and 172.31.0.0/16 for older runtime images, then validates the created network.

To observe the daemon’s host even with remote Docker, the spawner briefly runs the configured BuildKit image in the host network namespace with a read-only filesystem, all capabilities dropped and no mounts. If that observation fails or no safe subnet remains, sessions build locally without the shared cache. An unused owned network left with an invalid subnet is rebuilt; in-use and foreign networks are preserved.

Upgrades create cold organization caches and retain the old global cache data. Old helper containers stop automatically after no running session depends on them. Drain or stop old pinned sessions to complete that transition; until then the old shared cache service remains reachable. Browser automation uses headless Chromium; live browser viewing and manual browser takeover are retired.

Inner Docker networks

On Docker and Kubernetes, automatic selection checks IPv4 routes and gateways from all routing tables, interface addresses and prefixes, DNS servers, and the resolved addresses of proxy and gateway hosts configured in the container environment at startup. Hosts supplied later during an agent turn are outside that initial observation. It also accounts for a Docker organization bridge that will attach later. The runtime prefers a free 172.31.0.0/16, then tries other private /16 ranges. The first /24 serves docker0; inner Compose networks use /24 blocks from that same pool. In automatic mode, failed observations or exhausted private space prevent session startup.

A Pod cannot discover the cluster’s complete Pod, Service and VPC CIDRs from its own network namespace. Set SANDBOX_DIND_INNER_POOL to a private /16 you have checked against all those networks when deploying DinD on Kubernetes. An explicit pool still fails on every discovered overlap or invalid value. If some observations are unavailable, the runtime names them in a warning and can continue with the explicit pool; responsibility for the unseen address space remains with the operator.

After changing this pool, restart the spawner and recreate existing sessions to apply it. Restarting a runner container inside the same Kubernetes Pod retains that Pod’s environment and inner Docker store.

The egress proxy allows upstream DNS queries to the validated nameserver IPs in its /etc/resolv.conf, including private cluster DNS. Each exception covers only that exact IP and UDP/TCP destination port 53. Other private destinations and forwarding between attached networks stay blocked.

IPv6 forwarding protection

Keep sandbox, sandbox-egress and SANDBOX_RUNTIME_IMAGE on the same release when upgrading. Before attaching an organization’s Docker build network, the spawner verifies the session’s forwarding protection. Compose and generated Docker session containers disable IPv6 with net.ipv6.conf.all.disable_ipv6=1 and net.ipv6.conf.default.disable_ipv6=1; preserve both in custom Docker definitions.

Kubernetes Pods do not receive unsafe sysctls automatically. The egress proxy needs working IPv6 firewall support or IPv6 disabled in its network namespace. If the IPv6 firewall is unavailable, the entrypoint attempts that local disable and verifies the default and every interface. A read-only /proc/sys or denied write can prevent it; enabled IPv6 without protection still stops startup. Configure the egress Pod according to the cluster’s permitted networking settings before deployment.

Sandbox devices

Organizations can run their sandboxes on their own machines, which they connect under Settings > Sandboxes. A device connects out over HTTPS to <SITE_URL><BASE_PATH>/sandbox/tunnel and keeps one WebSocket open. The bundled proxy forwards that path, and only that path, to the spawner's device hub; the spawner's signed API stays on the internal network. Devices need the Docker backend: the hub is off with Kubernetes.

A device always runs the server's release. It learns the release each time it renews its connection and replaces its own containers when the server moves on, unless it was connected with --no-auto-update. It keeps no data on the server: its workspaces stay on the machine. Sandboxes on a device call the backend's sandbox endpoints and the model gateway through the device's connection, along the same paths sessions use on the server; the gateway's management API is never reachable that way. A device keeps the backend and gateway addresses it received when it joined: after changing SANDBOX_HTTP_API_BASE_URL or EXTERNAL_AGENT_GATEWAY_URL, run tale sandbox update on each device.

A device must trust the site's TLS certificate. A deployment with TLS_MODE=selfsigned cannot take devices.

With a proxy of your own instead of the bundled one, forward /sandbox/tunnel to port SANDBOX_HUB_PORT of the spawner, keep WebSocket upgrades and the Authorization header intact, and allow connections that stay open for hours.

Sandbox agent turns

Investigate why output consumption stopped before increasing this deadline. It limits orphaned output streams, not total task duration. Recreate the consuming backend roles after changing the environment.

Video-link ingestion (yt-dlp)

The worker uses these values for video transcript retrieval. Its image includes yt-dlp and a PO-token plugin. Use Video ingestion to distinguish source restrictions, egress problems, and authorized session handling. Recreate the worker after changing deployment environment values; rereading a variable inside a process does not reload .env.