agent-taskbayEnvironment map
Find every Taskbay runtime variable, understand secret boundaries, and apply configuration consistently.
The configuration reference explains each variable's default, valid values, effect and failure message. Configuration recipes combine them into working deployment profiles. This page maps the complete runtime surface to those explanations and highlights loading and security rules.
The A2A_ prefix is intentional: these are the application's current names. The documentation site itself does not need the console's database, identity-provider or agent secrets.
All runtime variables
| Area and detailed reference | Variables | Operational meaning |
|---|---|---|
| Database and storage | A2A_DATABASE_PROFILE, A2A_DATABASE_URL, A2A_PGLITE_DATA_DIR | Choose single-owner embedded PGlite or PostgreSQL. The PostgreSQL URL contains database credentials; treat it as secret. |
| Storage and migrations | A2A_ARTIFACT_DATA_DIR, A2A_DATA_DIR, A2A_AUTO_MIGRATE | Durable filesystem locations, legacy import/launcher state, migration startup policy. Use absolute paths in shared deployments and back up artifacts with the database. |
| Human authentication | A2A_AUTH_MODE, A2A_ALLOW_DEVELOPMENT_AUTH | OIDC for shared deployments; development identity gives all callers administrator access. |
| OIDC registration | A2A_AUTH_ORIGIN, A2A_OIDC_ISSUER, A2A_OIDC_CLIENT_ID, A2A_OIDC_CLIENT_SECRET, A2A_AUTH_ORGANIZATION_SLUG | Canonical console origin, issuer and client plus local membership scope. The client secret stays server-side. |
| Login and sessions | A2A_AUTH_FLOW_KEY, A2A_AUTH_SESSION_SECONDS | 64-hex random login encryption key; absolute session duration, default eight hours, range 60–86400 seconds. |
| Outbound policy | A2A_ALLOWED_AGENT_ORIGINS, A2A_ALLOW_PRIVATE_NETWORKS | Exact origins for cards, interfaces, OAuth token endpoints and notification webhook; explicit private-network exception. |
| Credential vault | A2A_VAULT_KEYS, A2A_VAULT_ACTIVE_KEY | JSON map of 64-hex secret encryption keys and the active key ID. Shared by web and workers; keep old keys through re-encryption. |
| Card trust | A2A_TRUSTED_CARD_KEYS, A2A_REQUIRE_SIGNED_CARDS | Origin-pinned public signing keys and optional rejection of unsigned cards. Pins are public; do not put private JWKs here. |
| Workers | A2A_COMMAND_WORKER_MODE, A2A_DECISION_SWEEP_MS | Embedded/external processing and approval/escalation sweep interval. The sweep defaults to 15000 ms; invalid values or values under 100 fall back to that default. |
| Agent push | A2A_PUSH_CALLBACK_ORIGIN, A2A_PUSH_SIGNING_KEY, A2A_PUSH_ALLOW_LOOPBACK_HTTP | Reachable callback origin, 64-hex secret for derived registration tokens, local-only HTTP exception. Push is off if origin is unset. |
| Notifications | A2A_NOTIFY_WEBHOOK_URL, A2A_NOTIFY_WEBHOOK_SECRET, A2A_NOTIFY_WEBHOOK_ORGANIZATION | Optional signed outgoing webhook for one organization. Set organization to the OIDC slug; default is local. Secret must have at least 32 characters. |
| Catalog and extensions | A2A_REGISTERED_AGENTS | Comma-separated card URLs seeded into the local organization only; these cannot be removed in the UI. |
| Sideband events | A2A_SIDEBAND_EXTENSION_URIS, alias A2A_SIDEBAND_EXTENSION_URI | Additional negotiated extension URIs. The plural takes precedence; built-in generic and trace URNs remain enabled. |
| AG-UI | A2A_AGUI_ENABLED | Exactly true enables the experimental same-origin adapter; 1 and TRUE do not. |
These are 33 A2A_ names, including the singular sideband alias. The approval sweep is configurable; other worker leases, polling/retry intervals and rate limits are fixed in source.
Process, framework and development values
NODE_ENV changes authentication and network-policy defaults. next start and the launcher run in production; separately started workers need this value explicitly. The launcher also uses PORT, HOSTNAME and CI; see Process variables and Launcher defaults.
NEXT_RUNTIME and NEXT_PHASE are framework-owned startup checks. NEXT_PUBLIC_APP_VERSION is generated from the package version by next.config.mjs and displayed in the console; it is public metadata, not an operator secret or a required environment setting. Never place credentials in any NEXT_PUBLIC_* value.
Repository-only controls such as A2A_TEST_POSTGRES_URL, HTTP verification ports/profiles, fixture directories and package tarballs are listed in Development setup. They are not production settings. NODE_EXTRA_CA_CERTS is a Node.js facility for adding a trusted CA, not a Taskbay reader; upstream has not verified a production private-CA recipe.
Which processes load environment files?
| Command/process | Loading behavior |
|---|---|
npx agent-taskbay | Shell environment plus launcher defaults; generated local vault secrets live in the protected data directory. |
npm run dev, npm start | Shell plus Next.js .env* loading. |
worker:tasks, worker:commands, security:credentials, db:projections:rebuild | Shell plus explicit Next.js environment loading in the script. |
auth:provision, db:migrate, other db:* commands | Export the required values into the shell; these scripts do not invoke that loader. |
Changing configuration generally requires restarting web and every worker. AG-UI enablement is read per request, but still depends on the environment actually present in that process. There is no complete environment-validation command; components validate their own settings at startup or first use.
Keep independent secrets independent
Use a different random value for the OIDC flow key, vault encryption key, push signing key and notification signing secret. Store the OIDC client secret and database password only in protected server configuration. Agent API keys, bearer tokens, OAuth client secrets and mTLS keys belong in encrypted credential bindings through the stdin CLI, never in browser forms, task text or command arguments.
Share keys consistently across the processes that use them. Back up vault keys separately from the database; the database alone cannot recover encrypted agent credentials. The application currently reads its key ring from environment variables; it has no built-in KMS or external secret-manager adapter. Your deployment platform can inject secrets, but that does not add an application-side integration.
Sources
The runtime-variable inventory was checked against non-test source and operator scripts at a52de4c, including auth config, network policy, worker sweep and build metadata.
Created and maintained by Shashi Kanth G S at allsrc.dev. Visit shashikanth.me.