Configuration reference

Tau stores different kinds of configuration in different places. Most people should connect models and integrations in the app. Self-hosted operators also manage the environment used by the API and worker.

Choose the right place to change a setting

You want to change	Where to do it
Agent model accounts and credentials	Settings → AI Providers; see models.
GitHub and other service connections	Settings → Integrations, then select or inherit the connection for the squad where appropriate.
Instance execution concurrency	Settings → System → Agent Execution.
Which instance a CLI command calls	tau auth backend configuration; see the CLI reference.
A self-hosted port, database, data directory or runtime	The instance checkout’s .env, normally written by setup.

Tau CloudSwitch to Self-hosted

Tau Cloud manages the server environment. Use the app’s settings for the controls available to your account. The environment variables below describe self-hosted installations; they are not values you need to supply to start using Cloud.

Self-hostedSwitch to Tau Cloud

bun run setup creates and merges .env for you. Keep that file with the instance whose services read it. Setup preserves existing secrets and values unless a corresponding explicit setup option replaces a managed value.

After changing server environment settings, restart the local installation with tau server restart. The UI concurrency setting and API-service credential changes have their own live update behavior and do not require editing .env.

Data and required settings

Setting	Meaning
DATABASE_URL	PostgreSQL connection for this instance. Setup writes the connection for its managed container, or uses your explicit --database-url.
HOME_DIR	Root for Tau’s local data. Normally ~/.tau; named installs default to ~/.tau-<label>. Prefer an absolute path.
TAU_SANDBOX_RUNTIME	Required: host, docker-socket, docker-sysbox, vm or k8s. No implicit default.
TAU_ENCRYPTION_KEY	A 32-byte hex key used to encrypt credentials in the database. Setup generates it only when missing. Preserve it with backups.
TAU_INTERNAL_EVENT_TOKEN	Shared authentication for communication between the API and worker. Setup writes a matching value for the instance.
TAU_INSTANCE	Local instance label used for service names, registry selection and related resources. Use setup to create labelled installations.

Changing HOME_DIR or DATABASE_URL selects different storage; it does not move existing data. Changing the runtime also does not automatically migrate all workspaces. See runtime and access before changing those values.

Browser addresses and ports

Setting	Meaning and local behavior
PORT	API and built-in web port; fresh local setup uses 3000.
HOST	API bind address. Outside Kubernetes, the default is 127.0.0.1; setting it can expose the listener beyond the local machine.
WORKER_PORT	Worker HTTP port; setup derives the API port plus 2. Not the browser entrypoint.
TAU_WORKER_BIND	Worker bind address. Overrides HOST; otherwise the worker defaults to loopback outside Kubernetes.
TAU_WORKER_EVENT_PORT	Internal event port; setup derives the API port plus 3.
APP_URL	User-facing application URL, including links Tau generates. Local setup uses http://localhost:<port>.
TAU_WEB_ORIGIN	Exact browser origin for passkeys and browser access policy: scheme://host[:port], with no path.
TAU_API_URL	API address used by clients and runtime connections. Keep it reachable from the components that use it.
TAU_SERVE_WEB	1, true or yes serves the built web app from Core. 0, false or no disables it. If unset, Core serves it only when a build exists.

Example for a same-machine HTTPS proxy, with the API still on its local port:

APP_URL=https://tau.example.com
TAU_WEB_ORIGIN=https://tau.example.com
TAU_SERVE_WEB=1

This example does not install a proxy or certificate. Follow configure access for the complete sequence.

Authentication settings

TAU_PASSWORD is the initial bootstrap/legacy password. Setup generates it so you can create the first administrator. Once an administrator has a passkey, password login and password bearer authentication stop being accepted. Emptying the variable does not disable account authentication.

WEBAUTHN_RP_ID optionally pins the passkey relying-party domain. It is a hostname without scheme, port or path; the default comes from the web origin. Leave it alone unless you are deliberately configuring the domain used by passkeys. WEBAUTHN_RP_NAME controls the name shown in the passkey prompt and defaults to Tau.

Browser sessions, CLI device credentials and model-provider credentials are separate. A successful CLI login does not connect a model provider. Use first installation and model setup for those steps.

Execution and optional services

MAX_CONCURRENT_AGENTS supplies the environment default for concurrent worker runs. The application fallback is 30 when no valid value is supplied; a checkout’s .env may already set a different number. Settings → System → Agent Execution overrides the environment value without restarting. The UI accepts up to 500; clearing the setting returns to the environment default.

For host-runtime browsing, TAU_BROWSER_EXECUTABLE_PATH selects an installed browser executable, and TAU_BROWSER_CHANNEL selects a supported Chromium-family channel. They are alternatives to automatic local browser discovery, not downloads or installation commands.

Connect optional OpenAI Realtime voice, transcription and embeddings through Settings → Integrations → OpenAI API services. This is separate from the model accounts in AI Providers. OPENAI_API_KEY remains a legacy environment source and can also affect model-provider discovery, so prefer the integration card for services-only configuration.

Google Cloud Text-to-Speech is configured through its integration card. An existing server-side GOOGLE_APPLICATION_CREDENTIALS file is also supported when that integration is enabled. These credentials serve read-aloud speech, rather than the OpenAI Realtime voice conversation.

Do not configure new agent GitHub access with GITHUB_TOKEN or GH_TOKEN. Connect GitHub in the app and grant the required repository access. See maintenance for preserving configuration during upgrades and backups.