Server settings

Server Settings are available to server admins only. They expose non-secret runtime configuration backed by tow.yaml, plus read-only deployment and secret status.

Use this page when you need to adjust runtime behavior without editing the YAML file directly.

What server settings control

Server Settings are grouped by operating area.

Group	Examples
Runtime	App name and backend CORS origins.
AI	OpenAI base URL, reasoning model, fast model, reasoning effort, embedding model.
Agents	Global Agent definitions, availability, and schedule baselines.
Background Jobs	Operating review cadence, ticket conflict scan hour, AI queue concurrency.
Uploads	Upload storage path and maximum upload size.
Storage	Onboarding backup path.
Email	Transport, sender, SMTP host/port/TLS, worker cadence, and file delivery path.
Security	Session cookie name, secure cookie flag, and session max age.
Authentication	Built-in versus OIDC mode, OIDC issuer, client ID, scopes, claim names, and email verification policy.

Settings saved in the UI are written to the YAML file shown at the top of the page.

The Agents tab manages server-level Agent definitions and bindings. Agent configuration is stored in the database and seeded from the built-in Agent catalog.

YAML and restart behavior

In Docker, the backend reads TOW_CONFIG_PATH=/app/data/tow.yaml by default. For local development outside Docker, the default is usually config/tow.yaml.

When a server admin saves YAML-backed settings, the page marks the deployment as restart required. Restart the backend before relying on the new values.

warning

Saved YAML values do not always become active immediately. The running backend keeps its current settings until restart for these runtime fields.

Agent enablement and schedules are resolved from effective Agent bindings when a request or background scan checks whether AI can run. Restart is still the normal safe step after broader Server Settings changes, and it is required when you change deployment environment variables.

Environment overrides

Environment variables take precedence over matching YAML settings. The Server Settings page marks fields that are overridden by environment configuration.

For example, if OPENAI_REASONING_MODEL is set in .env or the container environment, changing openai_reasoning_model in tow.yaml will not affect the running backend until the environment variable is removed or changed.

Environment overrides are intentionally stronger than YAML, but they are not the preferred place for non-secret server config. Before troubleshooting a setting that will not change, check .env, Docker Compose environment values, and the process environment for a matching variable.

Read-only settings

Some fields are visible but not editable from the UI.

The most important example is embedding_dim. Changing embedding dimensions affects vector storage and requires a planned migration and re-embedding process. Treat it as an infrastructure change, not a routine settings edit.

Deployment values such as ports, API_PROXY_TARGET, VITE_API_BASE_URL, Postgres user, and Postgres database are also read-only from the app. Configure them in Docker Compose, your process manager, or your platform deployment settings. The UI shows their effective values for diagnosis but does not write them to YAML.

Secrets

Secrets stay in environment configuration and are never returned by the API. The UI only reports whether a secret appears configured.

Secret-backed values include:

• APP_SECRET.
• DATABASE_URL.
• POSTGRES_PASSWORD.
• OPENAI_API_KEY.
• EXA_API_KEY.
• SMTP_USERNAME.
• SMTP_PASSWORD.
• OIDC_CLIENT_SECRET.

warning

Set a strong, unique APP_SECRET before first boot. The app uses it to sign session cookies and OIDC state. The default placeholder is rejected at startup, and changing the secret later invalidates existing sessions.

Session cookie security

For HTTPS deployments, set session_cookie_secure: true in tow.yaml so browsers send the session cookie only over secure connections.

Use a stable session_cookie_name unless you intentionally want users to receive a new cookie. Use session_max_age_seconds to align session duration with your organisation's access policy.

Authentication settings

Choose authentication mode before first boot:

• builtin keeps local email/password login and invite-based registration.
• oidc disables local login and registration, then redirects users to authentik or another OIDC provider.

OIDC mode requires runtime.public_app_url, auth.oidc.issuer, auth.oidc.client_id, and the secret OIDC_CLIENT_SECRET. The app exposes only whether the secret is configured, never its value.

Enable OIDC provider logout only when the provider supports RP-initiated logout and has {PUBLIC_APP_URL}/login?logged_out=1 registered as an allowed post-logout redirect URI. Organisation-managed authentication can inherit, force-enable, or disable this behavior per organisation.

For authentik, set the issuer to the OAuth2/OIDC provider URL, usually:

https://auth.example.com/application/o/tow/

TOW remains the authorization system. authentik authenticates users and can broker LDAP, SAML, Active Directory, MFA, and other upstream identity systems, but TOW still owns organisations, membership roles, project access, and app permissions.

Safe change process

For production deployments:

1. Record the current YAML and environment values.
2. Make the change in Server Settings or in deployment configuration.
3. Restart the backend during an approved maintenance window.
4. Confirm /api/health is healthy.
5. Sign in and verify the changed behavior.

Keep secrets out of screenshots, issue descriptions, and exported support bundles.

For Agent behavior, inheritance, schedules, disabled UI actions, and examples, see Agent configuration.