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.

Changing TOTP_CLIENT_NAME or TOTP_ENVIRONMENT affects newly generated QR codes and setup URIs, including when an existing secret is displayed again, and backup codes downloaded afterwards. It does not rotate secrets or rename entries already saved on a device; rename those in your authenticator app if needed.

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.

MCP endpoint

Coding agents in a terminal and server-side clients send no Origin, so the check never applies to them. A browser page on another site does send one, and an API key in such a page is how that site would reach the endpoint. While enforcement is off, each request from an origin outside the list is logged as [mcp] origin-mismatch with the origin, the organization and the person. Read those lines to see which of your clients send an origin before you set TALE_MCP_ORIGIN_ENFORCE=true, and add their origins to TALE_MCP_ALLOWED_ORIGINS.

The four settings at the end of the table belong to coding-agent sign-in, which lets an agent connect to the MCP endpoint without holding an API key. Until it is complete, agents connect with an API key and both ways in stay off. To read a client metadata document, the backend needs outbound HTTPS to the agent's host. It never fetches a document from a private address or from the deployment itself, and it never follows a redirect. Self-registration accepts only the coding-agent scopes and is rate-limited per source address and per deployment.

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.

The backend settings above must reach both API and worker services. Recreate them after a change. The spawner checks memory and disk headroom when a released session is acquired again, so a warm workspace can wait for capacity too.

Connected devices apply the same local-host memory and disk admission checks while keeping their configured session ceiling.

An intentionally stopped Docker daemon remains ready for its next command; health checks do not start it. A failed health probe immediately refuses new work but does not by itself stop the session. Probe-based recovery needs at least three completed failures spanning five seconds; a healthy result or a new engine clears that failure history. A confirmed startup failure or unexpected engine exit can trigger recovery immediately. The spawner can then stop an idle, unpinned session after an atomic activity check, keeping the workspace for the next start. On Docker, stopping the whole session removes its inner Docker store; stopping only the idle inner engine preserves it. Busy or pinned sessions stay in place and refuse new starts until Docker recovers or an operator resolves the fault.

During a rolling upgrade, keep old spawners pinned to their existing runtime image until they are replaced. Do not move a runtime tag still used by an old spawner: it does not distinguish transient probe failures from confirmed failures. A new spawner with an older runtime refuses unhealthy new work and keeps the normal idle and lifetime cleanup limits.

A containerized spawner automatically checks Docker’s data filesystem when it can verify its existing /etc/hostname mount against the daemon. If discovery is unavailable, workspace admission remains active and /health reports Docker disk monitoring as unavailable. An explicit read-only data-root mount takes priority; if it cannot be verified or read, admission waits until it is available. To configure one, inspect docker info --format '{{.DockerRootDir}}' and use that actual host path. Docker Desktop and remote daemons may need a different setup. For raw Compose, add the following override and pass both variables into the sandbox service:

services:
  sandbox:
    environment:
      SANDBOX_DOCKER_DATA_ROOT: ${SANDBOX_DOCKER_DATA_ROOT}
      SANDBOX_DOCKER_DATA_PATH: /var/lib/tale-sandbox/docker-data
    volumes:
      - ${SANDBOX_DOCKER_DATA_ROOT}:/var/lib/tale-sandbox/docker-data:ro

A disk floor is admission control, not a per-session storage quota. Docker named volumes have no portable size limit, and a Kubernetes PVC size request depends on its storage backend for enforcement. For hard quotas, use a quota-capable filesystem or storage class. Separately mounted containerd stores, volume directories and external volume drivers need their own monitoring, alongside workspaces, image layers and build caches.

Kubernetes sessions use /readyz for startup and /livez for daemon liveness. Startup accepts an intentionally stopped inner Docker engine as ready; an engine that is running must respond to its health probe. Liveness checks only the sandbox daemon, so dependency failures do not restart busy sessions. A wedged daemon can restart even when its session is pinned. Docker and egress diagnostics appear in /healthz.

An already active generation is not charged again. A workflow without inner Docker keeps its agent identity and tools, but starts no Docker daemon and does not keep build-cache helpers alive. Without an explicit SANDBOX_AGENT_MEMORY, each session defaults to 4g without inner Docker or 8g with it, even when other sessions in the deployment use Docker. An explicit value applies to both modes. These limits are ceilings, not reserved RAM.

At full capacity, the spawner can stop a released, unpinned idle session before the idle timeout to admit new work, starting with the one idle longest. 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. The same applies when the host's free memory would drop below SANDBOX_MIN_FREE_MEMORY. While the disk that holds the session workspaces is below SANDBOX_MIN_FREE_DISK, new work waits without stopping idle sessions: a stopped session keeps its workspace. Only below SANDBOX_CRITICAL_FREE_DISK does the spawner stop released idle sessions with Docker inside at once, since their stop removes their inner image stores.

Agent runtime protocol records, including unfinished lines, are limited to 8 MiB. Oversized or incomplete output fails explicitly; a bounded progress preview is never treated as a complete structured result. Complete final answers are retained separately from that preview.

Reacquiring a released warm session checks the same memory reserve and reserves its expected working set before resuming work. Concurrent resumes share that accounting. A busy response is retryable; it does not destroy the workspace or interrupt a session that already holds work. These reservations do not cap the later growth of active tools or organization builders.

When Docker is enabled inside agent sandboxes, the engine starts automatically on the first Docker command. Agents do not choose a mode. After five minutes without connected clients, it stops only if no container is running, restarting or paused and every container has its restart policy disabled; an unknown state keeps it running. The next command restarts it with the same images, volumes and workspace. Existing container metadata at session-container boot starts the engine immediately so restart policies still work. This does not change the deployment's runtime isolation, privileges or memory limits.

Size session capacity

On a Docker host with SANDBOX_MAX_SESSIONS unset, the spawner sizes the capacity from the host's memory and CPUs (one session per 768 MiB beyond the reserve, at most two per CPU: a 16 GiB host with 8 CPUs gets 16 sessions, a 64 GiB host with 16 CPUs 32; a 16 GiB host gets 9 where agent sessions run their own Docker daemon) and admits a new session only while the host keeps SANDBOX_MIN_FREE_MEMORY free, counting what the sessions still starting or just started are about to use. A burst of new sessions that would overcommit the host therefore waits instead of starting; the check does not stop sessions already running from growing. While the host's CPU is under pressure (SANDBOX_CPU_PRESSURE_PERCENT), new sessions likewise start one at a time instead of adding to the load. Every project agent run that works at the same time as another takes a session of its own, an agent worker: one agent working three tasks at once runs three sessions, each with its own SANDBOX_AGENT_MEMORY limit. These two settings therefore bound how much agent work runs in parallel. Set the capacity yourself on Kubernetes, with a remote Docker daemon, or when the host also runs other heavy workloads: 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.

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; without one, a Docker host sizes the capacity from its memory as described above, and Kubernetes uses 8.

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.

From this release, a Docker deployment that never set SANDBOX_MAX_SESSIONS gets a capacity sized from its host's memory instead of 8, never less than 8. It can admit more sessions at once than before, and only while the host has memory to spare. Set an explicit value to keep a fixed capacity and disable adaptive memory admission; choose it from measured memory peaks. The disk floor remains enabled.

That sized capacity is now also at most two sessions per CPU, so a host with much memory and few CPUs gets fewer sessions than before (a 16 GiB host with 4 CPUs: 8 instead of 19). While the host's CPU is under pressure, new sessions also start one at a time (SANDBOX_CPU_PRESSURE_PERCENT, 0 turns this off). An explicit SANDBOX_MAX_SESSIONS is not changed.

Docker build caches

Shared build-cache preparation uses SANDBOX_BUILDKITD_PROVISION_TIMEOUT_MS (5 seconds by default). Each session waits at most that long or one quarter of its total startup budget, whichever is shorter, then uses its local builder. Shared preparation has its own bounded lifetime; cancelling one session’s wait does not cancel setup for other sessions, and a late result does not attach to a session that already fell back. Registry mirrors are prepared concurrently. The shared builder’s parallel steps follow its configured CPU limit, rounded down with a minimum of one; its memory limit still applies. Preparation time counts against the remaining session startup budget.

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 SANDBOX_BUILDKITD_IDLE_MS (10 minutes) and the registry mirrors are removed with their caches, since the builder's own cache keeps the base layers its builds used; the next build starts the builder again with its cache volume intact and recreates the mirrors. Right before the builder stops, the spawner prunes its cache to SANDBOX_BUILDKITD_IDLE_CACHE, because its garbage collection runs only while it runs. A stopped organization's cache is not pruned further; after SANDBOX_BUILDKITD_CACHE_RETENTION (14 days) with no build, its helpers and caches are removed, and otherwise they go with the organization. While the session disk is below SANDBOX_MIN_FREE_DISK, stopped organizations' caches go sooner, the longest-stopped first. The network and the builder's cache volume 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 for now. Old helper containers stop automatically after no running session depends on them. Once they have been stopped longer than SANDBOX_BUILDKITD_CACHE_RETENTION (14 days) and still no session depends on them, the spawner removes those helper containers and the four old cache volumes (tale-buildkitd-cache and tale-buildkitd-mirror-cache-docker-io, -ghcr-io, -quay-io), each only while it carries the old build-cache label without an organization, and logs every removal; off keeps 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 images

With the shared build cache on, a session's inner Docker engine pulls Docker Hub images through its organization's docker.io registry mirror, the same cache its builds use, and falls back to Docker Hub when that mirror is not running. Images from other registries are pulled directly. An inner engine that goes idle with more than 10 GiB of images and build cache first removes its dangling images and prunes its build cache to the 5 GiB used most recently; tagged images, containers and volumes stay. On Kubernetes, the size limit of the inner store's volume bounds it instead when that limit is below 10 GiB.

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.

SSH repository access

The native sandbox includes OpenSSH and netcat-openbsd. Grant a replaceable key restricted to the repository as a named agent secret, then load it into ssh-agent from stdin in the credentialed turn. Keep its private bytes in the environment; never write a key file or print them. A Member-started turn receives no agent secrets. Git commits use the workspace owner's author name and email even without a GitHub connector grant.

Internal sessions use their existing HTTP_PROXY for egress. Direct SSH cannot rely on external DNS from that network. Use the proxy's HTTP CONNECT tunnel and a port it authorizes. GitHub supports SSH at ssh.github.com:443; verify the host against GitHub's published fingerprints, as described in SSH over port 443. Keep a public known-hosts file with the independently verified pin and configure the command after the agent has loaded the key:

import os
import shlex
import subprocess
from urllib.parse import urlsplit

proxy = urlsplit(os.environ["HTTP_PROXY"])
if proxy.scheme != "http" or not proxy.hostname or not proxy.port or proxy.username or proxy.password:
    raise ValueError("Expected the existing unauthenticated HTTP egress proxy")
connect = shlex.join(["nc", "-X", "connect", "-x", f"{proxy.hostname}:{proxy.port}", "%h", "%p"])
environment = os.environ.copy()
environment["GIT_SSH_COMMAND"] = shlex.join([
    "ssh", "-o", f"ProxyCommand={connect}", "-o", "StrictHostKeyChecking=yes",
    "-o", "UserKnownHostsFile=/tmp/repository-known-hosts",
    "-o", "GlobalKnownHostsFile=/dev/null", "-o", "BatchMode=yes",
    "-o", "ConnectTimeout=20",
])
subprocess.run(["git", "ls-remote", "--exit-code", "ssh://git@ssh.github.com:443/org/repository.git", "HEAD"], env=environment, check=True, timeout=30)

The known-hosts file contains only the provider's public host key; the repository's private key stays in ssh-agent. This uses the existing egress policy and the repository key's own access scope. It needs no broader GitHub connector grant.

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.

A changed gateway worker count reaches each provider the next time an organization that uses it starts a sandbox session or calls the model endpoints. A lower count also reaches every other provider the gateway holds: the backend resizes them two to five minutes after its first sandbox session or model-endpoint request following a restart.

A provider whose upstream host no longer resolves, such as one of a removed connector or of a host you took off your network, is the exception: the gateway refuses to rewrite it, so it keeps its workers, and the backend logs a warning that names it after every restart. Delete such a provider from the gateway. A provider still in use is set up again at its next sandbox session or model-endpoint request. Send the request from a backend container, which reaches the gateway and holds its admin password; on a tale deploy host, its name contains -backend-api:

docker exec <backend-api-container> sh -c 'curl -fsS -X DELETE -u "${SANDBOX_LLM_GATEWAY_ADMIN_USERNAME:-admin}:$SANDBOX_LLM_GATEWAY_ADMIN_PASSWORD" "${SANDBOX_LLM_GATEWAY_URL:-http://sandbox-llm-gateway:8080}/api/providers/<name>"'

On Kubernetes, use kubectl exec -n tale deploy/backend-api -- in place of docker exec <backend-api-container>.

The gateway starts every provider's workers while it boots, before the backend can reach it. Providers stored with more workers than these values (the gateway's own default is 1,000) can need more memory than the gateway's limit, 512 MiB with tale deploy and in the Kubernetes manifest, and the gateway is then killed during every start. Do not delete its volume, which holds its admin account and the keys it issued. Raise the limit until the gateway starts instead: on a tale deploy host, run docker update --memory 2g --memory-swap 2g <container> for the container whose name ends in -sandbox-llm-gateway; on Kubernetes, raise resources.limits.memory of its Deployment. Then start a sandbox session or call the model endpoints, and wait for the backend's log line [llm-gateway] provider worker resize finished, which comes two to five minutes later. It counts the providers the backend resized, the ones the gateway refused and the ones the backend could not confirm. A refused or unconfirmed provider keeps its workers, and a warning before the line names it; a restarted backend tries an unconfirmed provider again. Delete a refused provider whose upstream host no longer resolves, as described above, before you restore the limit. Afterwards, restore the limit with docker update --memory 512m --memory-swap 1g <container> and docker restart <container>, or on Kubernetes the Deployment's original value.

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.