Configuration

Configuration is read from the environment, usually through a .env file created from .env.example.

What this server has configured

apowerb starts with almost nothing configured and says so rather than failing. A feature nobody has set up answers « not configured yet, contact your administrator » — never a 4xx or a 5xx. The server is the source of truth about its own state:

curl -H "Authorization: Bearer <token>" https://your-host/api/config/setup

{
  "items": [
    {
      "key": "orchestration",
      "configured": false,
      "optional": false,
      "blocks": ["orchestrator"],
      "missing": ["TH2ETL_BASE_URL", "TH2ETL_API_KEY"],
      "docs_url": "https://docs.apowerb.com/configuration/orchestration"
    }
  ],
  "missing_count": 1
}

The same answer feeds the interface: Admin → Configuration lists every capability, and the sidebar badge counts what is still missing.

Capability	Blocks	How to configure it
`default_llm`	agents carrying no key of their own	Shared model
`object_storage`	nothing — a local directory is the fallback	File storage
`microsoft_integration`	Outlook, OneDrive, Outlook triggers, campaigns	Microsoft
`google_integration`	Drive, Gmail, Calendar and their triggers	Google
`orchestration`	the Orchestrator screen, scheduled pipelines	Orchestrator
`observability`	the Logging screen	Logs and traces
`system_mail`	address verification, password reset	System mail

missing holds variable names, never values, and the server sends it to administrators only. Everyone else sees which features work — enough to know it is not their mistake, and nothing that helps an attacker.

Every setting below is read at startup. Restart the backend after changing one, then reload Admin → Configuration. A value written where the process never reads it changes nothing — check the environment of the container, not the shell that started it.

Required

Five settings, and the server refuses to boot without them — the list is RUNTIME_REQUIRED_FIELDS in configs/settings.py, which the boot check reads.

Variable	Description
`DB_HOST`	PostgreSQL host
`DB_NAME`	Database name
`DB_USER`	Database user
`DB_PASSWORD`	Database password
`ENCRYPT_KEY`	Fernet key used for encryption at rest and JWT signing. Must be a urlsafe-base64 32-byte key — `Fernet.generate_key()`

On the Quickstart path, none of these are yours to fill in: the Compose stack runs its own Postgres and generate-secrets.sh writes the key. This page is for an installation that brings its own database.

Two neighbours in the same block are not required, each carrying a default: DB_PORT (5432) and DB_SCHEMA (public).

.env.example may still carry TEST_TOKEN. It is not required: the only code that reads it is a middleware mounted nowhere. Setting it changes nothing, leaving it out breaks nothing.Earlier versions did refuse to start without it, which meant inventing a “test token” to run in production. That requirement is gone.

ENCRYPT_KEY encrypts the OAuth tokens of every connected integration. Changing it makes all previously connected integrations unreadable. Back it up with your other secrets — see Secrets.

Security and JWT

Variable	Default	Description
`WORKING_MODE`	`development`	`development` or `production`
`ALGORITHM`	`HS256`	JWT signing algorithm
`ACCESS_TOKEN_EXPIRE_MINUTES`	`120`	Access token lifetime
`ENCRYPT_PASS`	—	Encryption password

API schema

Variable	Default	Description
`PUBLISH_API_SCHEMA`	unset (`false`)	Serve `/docs`, `/redoc` and `/openapi.json`

FastAPI serves these three routes to anyone by default, with the full inventory of paths, parameters and response shapes — no credentials required, since Swagger UI cannot send a bearer token on its first load. apowerb removes them instead of guarding them, unless this flag is set.

Since 0.1.18, /docs and /openapi.json answer 404 by default. Set PUBLISH_API_SCHEMA=true to get a browsable schema back — typically for local development only. WORKING_MODE=production hides the schema regardless of this flag.

CORS

Variable	Default	Description
`CORS_ALLOWED_ORIGINS`	`http://localhost:3000`	Comma-separated list of allowed origins. Supersedes `FRONTEND_URLS` when set.
`FRONTEND_URLS`	`["http://localhost:3000"]`	Allowed origins, as a JSON array — used when `CORS_ALLOWED_ORIGINS` is not set

Set CORS_ALLOWED_ORIGINS whenever the front end lives on a different domain than the API. ADK 2.6 added an origin-check middleware that rejects any state-changing request (POST, PUT, PATCH, DELETE) carrying an Origin header it was not told about — with a 403 raised before authentication runs. GET requests are unaffected, which makes the symptom easy to misread: the app looks half-broken (browsing works, every submit fails) rather than looking like a CORS problem. List every origin the browser will call the API from directly, comma-separated.

OAuth — workspace integrations

These OAuth applications carry the scopes agents need to read Drive, send mail, or list Teams chats. They authorise an agent to act on a service — they are not how a user signs in.

Variable	Description
`GOOGLE_INTEGRATION_CLIENT_ID` / `_SECRET` / `_REDIRECT_URI`	Google Workspace — Drive, Gmail, Calendar, Sheets, Docs
`MICROSOFT_INTEGRATION_CLIENT_ID` / `_SECRET` / `_TENANT_ID` / `_REDIRECT_URI`	Microsoft 365 — Outlook, Teams, OneDrive, SharePoint
`GITHUB_INTEGRATION_CLIENT_ID` / `_SECRET` / `_REDIRECT_URI`	GitHub workspace integration

Signing in with an identity provider — GitHub, Google, Microsoft, LinkedIn — is part of a commercial edition and is absent here. The open-source build authenticates with email and password. See Editions.

Gmail Pub/Sub webhooks

Variable	Description
`GMAIL_PUBSUB_PROJECT_ID`	Google Cloud project hosting the topic
`GMAIL_PUBSUB_TOPIC`	Topic name only, not the full path
`GOOGLE_WEBHOOK_AUDIENCE`	Expected `aud` claim of the JWT Google signs its push with. The handler verifies that token before acting on the notification

See Gmail webhooks for the full setup.

RAG and webhooks

Variable	Default	Description
`PUBLIC_BASE_URL`	`http://localhost:8000`	Public URL of this apowerb instance
`RAG_WEBHOOK_SECRET`	`th2-webhook-default-secret`	HMAC-SHA256 secret for RAG webhooks
`RAG_BASE_URL`	—	Base URL of the RAG service (th2rag)

POST /rag/webhook sits outside the auth middleware and trusts this HMAC signature instead — it is the only credential guarding the route. Since 0.1.8, the server refuses to start when WORKING_MODE=production and RAG_WEBHOOK_SECRET is still empty or the shipped placeholder. Generate one before deploying: openssl rand -hex 32.

Notifications

Variable	Default	Description
`NOTIFICATION_EMAIL`	empty	Shared mailbox used as the `From` for system emails
`NOTIFICATION_EMAIL_PROVIDER`	`outlook`	Provider serving `NOTIFICATION_EMAIL`
`NOTIFICATION_INTEGRATION_OWNER`	empty	Login owning the mailbox integration whose refresh token sends the mail
`SUPER_ADMIN_EMAIL`	empty	Recipient of ETL and system alerts

All four default to empty, and the mailer is simply off until they are set — one log line, no error, no email. There is no hardcoded fallback address: an installation that leaves these unset sends nothing, rather than mailing a third party by default.

Storage (optional)

Variable	Description
`STORAGE_MODE`	`local`, `s3` (or any S3-compatible storage), or `azure` (coming soon)
`S3_REGION`, `S3_ENDPOINT`, `S3_BUCKET_NAME`	Bucket location for S3-compatible storage
`S3_ACCESS_KEY`, `S3_ACCESS_KEY_SECRET`	Credentials for S3-compatible storage

Orchestrator

Variable	Default	Description
`ORCHESTRATOR`	`mage`	Which orchestrator runs the schedules — `mage` or `th2etl`

With ORCHESTRATOR=mage (the default), the server talks to Mage AI:

Variable	Default	Description
`BASE_URL`	`http://localhost:6789`	Mage AI URL
`API_KEY`	—	Mage API key
`OAUTH_TOKEN`	—	Mage OAuth token
`PROJECT_NAME`	`default_repo`	Mage project

With ORCHESTRATOR=th2etl, it talks to th2etl instead:

Variable	Default	Description
`TH2ETL_BASE_URL`	`http://localhost:8009`	th2etl instance
`TH2ETL_API_KEY`	—	Must equal that instance’s own `API_KEY`: its business routes require `Authorization: Bearer <key>`

Both clients expose the same surface, so only these settings change. See Orchestrator.

Variable	Default	Description
`SCHEDULER_ENABLED`	`true`	Set to `false` to drop the scheduler integration entirely
`MAGE_PIPELINE_UUID`	`agents`	Pipeline the Mage backend triggers

Unset means mage. A deployment meant to run on th2etl must say so explicitly — silence selects the other backend, and the schedules land where nobody is looking.

Default LLM provider

Agents with no model of their own fall back to this provider.

Variable	Default	Description
`DEFAULT_LLM_MODEL`	—	LiteLLM model id used when an agent names none
`DEFAULT_LLM_API_KEY`	—	Key for that model
`DEFAULT_LLM_API_BASE`	—	Base URL, for self-hosted or proxied providers
`DEFAULT_LLM_MONTHLY_TOKEN_QUOTA`	`1000000`	Monthly token allowance on the default provider
`DEFAULT_LLM_PLAN_QUOTAS`	`{}`	Per-plan overrides, as JSON
`CREDIT_TOKEN_VALUE`	`100000`	Tokens one credit is worth

Variable	Default	Description
`AUTH_REGISTER_ENABLED`	`true`	Allow self-service account creation
`AUTH_BASIC_ENABLED`	`true`	Allow email/password sign-in
`AUTH_EMAIL_VERIFICATION_ENABLED`	`false`	Require a confirmed address before use
`EMAIL_VERIFY_TOKEN_EXPIRE_HOURS`	`24`	Lifetime of the confirmation token
`APP_PUBLIC_URL`	`http://localhost:3000`	Public URL of the front app, used to build verify and reset links

Database, beyond the required settings

Variable	Default	Description
`DB_TYPE`	`postgresql`	Database backend
`DB_SSLMODE`	`require`	libpq SSL mode
`DB_AGENT_STORE_TABLE_NAME`	`th2agents_store`	Table holding agent definitions
`ECHO_SQL`	`false`	Log every SQL statement — noisy, for debugging only

Runtime directories

Where the server writes on disk. S3 keys keep their own namespace and are unaffected.

Variable	Default	Description
`RUNTIME_ROOT`	—	Root for the directories below; empty means the working directory
`AGENTS_POOL_DIR`	`agents_pool`	Generated agent modules
`ARTIFACTS_STORE_DIR`	`artifacts_store`	Artifacts, in local storage mode
`UPLOADS_DIR`	`uploads`	Uploaded files, in local storage mode
`BI_STORE_DIR`	`bi_store`	CSV and Excel files imported into BI, when S3 is not configured
`TOOLBOX_DIR`	—	MCP toolbox location; empty means `RUNTIME_ROOT`
`ROOT_PATH`	`http://localhost:8000`	Mount prefix when served behind a path-rewriting proxy

Organisations

Variable	Default	Description
`ORG_DOMAIN_SLUGS`	`{}`	JSON map of email domain to organisation slug, e.g. `{"example.com": "example"}`. Membership is computed from it
`ETL_ALERT_RECIPIENTS`	—	Recipients of ETL and system alerts

Development-only switches

Both must stay false in production. The first is refused at boot when WORKING_MODE is production; the second must never run unattended — use the migration CLI explicitly instead.

Variable	Default	Description
`WEBHOOK_DEV_SKIP_SIG`	`false`	Skip signature verification on the Gmail webhook, so local testing needs no Google Cloud project
`ENCRYPT_LEGACY_ON_BOOT`	`false`	Run the legacy integration-token encryption migration at startup

Declared here, used by bricks

The core declares these so a brick can read them. In a core-only install they are inert: setting them changes nothing, and the matching routes still answer 404.

Variable	Brick
`STRIPE_SECRET_KEY`, `STRIPE_PUBLISHABLE_KEY`, `STRIPE_WEBHOOK_SECRET`	billing
`EVALUATION_ENABLED`, `EVALUATION_JUDGE_MODEL`, `EVALUATION_JUDGE_API_KEY`, `EVALUATION_PASS_THRESHOLD_*`, `EVALUATION_MIN_RERUN_INTERVAL_SECONDS`, `EVALUATION_TOOL_USAGE_TOKENS_PER_CALL_SOFT_CAP`	evaluation
`GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET`, `GITHUB_REDIRECT_URI`, `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`, `GOOGLE_REDIRECT_URI`, `MICROSOFT_CLIENT_ID`, `MICROSOFT_CLIENT_SECRET`, `MICROSOFT_TENANT_ID`, `LINKEDIN_CLIENT_ID`, `LINKEDIN_CLIENT_SECRET`	auth (identity-provider sign-in)

These are the sign-in credentials, not the workspace ones. Connecting Google Drive or Outlook for an agent uses the *_INTEGRATION_* variables above, which are part of this edition.

Extensions

Variable	Description
`TH2_EXTENSIONS`	Comma-separated list of modules to plug in at startup
`TH2_OVERLAY_MODULE`	Legacy single-module form, still honoured, loaded last

Empty means no extension: the core runs on its own. See Editions.

Get started

Concepts

Business Agents

Frontend

Automation

AgentOps

Integrations

Tools & Skills

Ecosystem

Contributing

What this server has configured

Required

Security and JWT

API schema

CORS

OAuth — workspace integrations

Gmail Pub/Sub webhooks

RAG and webhooks

Notifications

Storage (optional)

Orchestrator

Default LLM provider

Database, beyond the required settings

Runtime directories

Organisations

Development-only switches

Declared here, used by bricks

Extensions

​What this server has configured

​Required

​Security and JWT

​API schema

​CORS

​OAuth — workspace integrations

​Gmail Pub/Sub webhooks

​RAG and webhooks

​Notifications

​Storage (optional)

​Orchestrator

​Default LLM provider

​Sign-up and sign-in

​Database, beyond the required settings

​Runtime directories

​Organisations

​Development-only switches

​Declared here, used by bricks

​Extensions

What this server has configured

Required

Security and JWT

API schema

CORS

OAuth — workspace integrations

Gmail Pub/Sub webhooks

RAG and webhooks

Notifications

Storage (optional)

Orchestrator

Default LLM provider

Sign-up and sign-in

Database, beyond the required settings

Runtime directories

Organisations

Development-only switches

Declared here, used by bricks

Extensions