You are viewing the docs for Archestra v1.4. View the latest docs
Configuration
Archestra reads these environment variables at startup. Pass them with -e to docker run, or set them under archestra.env in the Helm values. The Docker quickstart and the Helm chart run with none set. See Deployment for the install.
Shutdown
Give long model requests and MCP tool calls time to finish when a replica stops.
-
ARCHESTRA_— Seconds after a stop signal for admitted requests, handlers and background persistence to finish. DefaultSERVER_ REQUEST_ DRAIN_ SECONDS 60; integer1–86400. -
ARCHESTRA_— Extra time for persistence, dependency cleanup and telemetry. DefaultSERVER_ SHUTDOWN_ CLEANUP_ SECONDS 20; integer5–86400. The backend deadline ismax(request drain, worker task shutdown timeout) + cleanup. The unified container gives the backend another 10 seconds before forcing it to stop. -
ARCHESTRA_— Injected by Helm from the rendered pod grace period. At server startup, checks the resolved environment values, including Secret and ConfigMap imports, againstSERVER_ POD_ GRACE_ SECONDS max(drain, worker timeout) + cleanup + 40. Insufficient grace prevents startup. Leave unset outside Helm unless you want this validation.
The Helm chart derives web and worker pod grace periods from settings it can read, reserving 40 seconds beyond the backend deadline. The archestra.shutdown values default to null, preserving existing envFrom, envFromSecrets and envWithValueFrom settings. Explicit chart settings override imported values; literal archestra.env values take precedence over the chart settings.
Helm cannot read timeout values inside a Secret or ConfigMap. When importing longer durations, set archestra.terminationGracePeriodSeconds high enough for the resolved values. For example, an imported worker timeout of 90 seconds with default drain and cleanup requires at least 150 seconds of pod grace. Both servers validate that budget before accepting requests.
Database
-
ARCHESTRA_- PostgreSQL connection string.DATABASE_ URL - Default: the bundled PostgreSQL (Docker quickstart and Helm)
- Values:
postgresql://user:password@host:5432/database - Required when you use an external database.
-
ARCHESTRA_- Runs database migrations before the backend starts.DATABASE_ RUN_ MIGRATIONS_ ON_ STARTUP - Default:
true - Set
falseonly when your deployment pipeline applies migrations before rollout.
- Default:
-
ARCHESTRA_- Maximum PostgreSQL connections per backend process.DATABASE_ POOL_ MAX - Default:
50 - Values:
1–500 - In Helm,
archestra.database.connectionBudgetsizes the pool across all pods. This variable andarchestra.database.poolMaxoverride it. See Database Configuration.
- Default:
-
ARCHESTRA_- PostgreSQLDATABASE_ STATEMENT_ TIMEOUT_ MILLIS statement_for every pooled connection, in milliseconds.timeout - Default:
30000 - Values:
0disables the timeout. - Raise it if you run legitimate long queries.
- Default:
Server and Network
-
ARCHESTRA_- Public URL of the Archestra API, shown in the connection instructions for the LLM Proxy, MCP Gateway, and A2A Gateway.API_ BASE_ URL - Default: unset (connection instructions show the URL the app is open on)
- Values: one URL, or a comma-separated list, for example
http://archestra.default.svc:9000,https://api.example.com - Set it when clients reach the API through an ingress or load balancer. List every public host you serve the gateways on.
-
ARCHESTRA_- URL the backend listens on inside the container. In-cluster workloads use it to reach the backend.INTERNAL_ API_ BASE_ URL - Default:
http://127.0.0.1:9000 - The port in this URL sets the API listen port.
- Agent Runtime pods use it to reach the API unless
ARCHESTRA_is set.AGENT_ RUNTIME_ PLATFORM_ BASE_ URL
- Default:
-
ARCHESTRA_- Public URL of the Archestra web app. Setting it restricts CORS and sign-in to the configured origins.FRONTEND_ URL - Default: unset (only same-origin requests to the host the app is opened on are accepted)
- Values: an origin, for example
https://archestra.example.com - Set it in production. Users who open the app on a LAN IP need that URL here, for example
http://192.168.1.5:3000.
-
ARCHESTRA_- Extra port that serves only the endpoints meant for the Internet: the Microsoft Teams webhook (PUBLIC_ ENDPOINTS_ PORT /api/webhooks/chatops/ms-teams).- Default: unset (no extra port)
- Values:
1–65535. Any other value disables the extra port and logs a warning. - The main API port keeps serving these endpoints. In Helm, set
archestra.publicEndpointsPort, which also exposes the port on the Service.
-
ARCHESTRA_- Trusts theTRUST_ PROXY X-Forwarded-*headers of a reverse proxy or load balancer. Rate limits and audit logs then see each client's IP.- Default:
false - Values:
true,false, or a comma-separated list of proxy IPs or CIDRs, for example10.0.0.0/23,10.0.2.2 - Prefer the IP list. With
true, any caller can setX-Forwarded-Forand pick the IP it is rate-limited and audited under. - List every proxy between the client and Archestra, including a load balancer's own IP when it adds one to
X-Forwarded-For, as Google Cloud Application Load Balancers do. A list always trusts loopback, which is how the web UI reaches the API.
- Default:
-
ARCHESTRA_- How long the API and web servers keep an idle keep-alive connection open, in milliseconds.HTTP_ KEEP_ ALIVE_ TIMEOUT_ MS - Default:
620000 - Values: a positive whole number of milliseconds, digits only, such as
620000 - Keep it above the keep-alive timeout of every proxy and load balancer in front of Archestra. See Keep-Alive Timeouts.
- Default:
-
ARCHESTRA_- Maximum HTTP request body size for LLM Proxy and chat requests.API_ BODY_ LIMIT - Default:
70MB - Values: bytes (
73400320) or a size withKB,MB, orGB(100MB) - When a policy omits
externals.max_body_bytes, guardrails use this size for external helper responses and tool results. - The policy setting accepts a positive integer of bytes, not a size string such as
70MB. It overrides both caps without changing the HTTP request limit; oversized tool results are withheld. - All attachments of one chat message share this limit. Raise it when you raise
ARCHESTRA_, or for very long conversations.CHAT_ ATTACHMENT_ STORAGE_ BYTES_ LIMIT
- Default:
-
ARCHESTRA_- Which part of the backend this process runs.PROCESS_ TYPE - Default:
all - Values:
all,web,worker - The Helm chart sets it for each deployment. Set it yourself only when you split processes without the chart.
- Default:
General
-
ARCHESTRA_- Turns on beta features.BETA - Default:
false - Values:
true,false - Also turns on
ARCHESTRA_when it is left blank. Set toKNOWLEDGE_ BASE_ MFILES_ CONNECTOR_ ENABLED false, it stays off.
- Default:
-
ARCHESTRA_- Digests of the images released with this version: the MCP server base, the p4 shim, and the maintained agent images. The Helm chart of every release sets it, so those images run exactly as released, pinned by digest instead of a tag that could move.RELEASE_ IMAGE_ DIGESTS - Default: unset (the Docker quickstart and charts built outside a release use the version tags)
- Leave it to the chart. A mirror set with
ARCHESTRA_, or an image set withAGENT_ RUNTIME_ IMAGE_ REGISTRY ARCHESTRA_orORCHESTRATOR_ MCP_ SERVER_ BASE_ IMAGE ARCHESTRA_, runs exactly as you set it. To pin a mirrored image, set its digest in that value:KNOWLEDGE_ BASE_ PERFORCE_ SHIM_ IMAGE registry.example.com/mcp-server-base:1.6.0@sha256:….
-
ARCHESTRA_- Runs MCP servers in a small Kubernetes (KinD) cluster inside the Docker container.QUICKSTART - Default:
false - Values:
true,false - Requires the Docker socket mounted into the container. For evaluation only. See Quickstart Deployment.
- Default:
-
ARCHESTRA_- Activates the enterprise license.ENTERPRISE_ LICENSE_ ACTIVATED - Default:
false - Values:
true,false - See Pricing Model for what it unlocks.
- Instances with fewer than 30 users get most enterprise features without it. Content encryption, data retention, Vault, and Real User Monitoring always need it.
- Turns
ARCHESTRA_off unless that variable is set.ANALYTICS
- Default:
-
ARCHESTRA_- Activates the enterprise Knowledge Base features, such as team-scoped connectors.ENTERPRISE_ LICENSE_ KNOWLEDGE_ BASE_ ACTIVATED - Default:
false - Values:
true,false - Instances with fewer than 30 users get these features without it.
- Default:
-
ARCHESTRA_- Activates the Platform + AI Security tier: the OpenAPPA integration behind Guardrails. Instances with fewer than 30 users get it without this flag.ENTERPRISE_ LICENSE_ AI_ SECURITY_ ACTIVATED - Default:
false - Values:
true,false
- Default:
-
ARCHESTRA_- Removes the "Powered by Archestra" branding and the community links.ENTERPRISE_ LICENSE_ FULL_ WHITE_ LABELING - Default:
false - Values:
true,false
- Default:
-
ARCHESTRA_- Minimum level of log messages.LOGGING_ LEVEL - Default:
info - Values:
trace,debug,info,warn,error,fatal
- Default:
-
ARCHESTRA_- Format of the logs written to stdout.LOGGING_ FORMAT - Default:
json. The Docker quickstart usespretty. - Values:
json(one JSON object per line),pretty(colorized text) - The OTLP log exporter always receives structured records.
- Default:
-
ARCHESTRA_- Sends product analytics, instance heartbeats, and backend error reports to Archestra. Guardrails diagnostic forwarding has a separate opt-in.ANALYTICS - Default: on in production builds, including the released Docker images. Off in development, and off when
ARCHESTRA_isENTERPRISE_ LICENSE_ ACTIVATED true. - Values:
disabledturns it off. Any other value turns it on.
- Default: on in production builds, including the released Docker images. Off in development, and off when
-
ARCHESTRA_- PostHog project key for analytics.ANALYTICS_ POSTHOG_ KEY - Default: Archestra's PostHog project
- Set it with
ARCHESTRA_to send analytics to your own PostHog.ANALYTICS_ POSTHOG_ HOST
-
ARCHESTRA_- PostHog API host for analytics.ANALYTICS_ POSTHOG_ HOST - Default:
https://eu.i.posthog.com
- Default:
-
ARCHESTRA_- Blocks the app for all users with a full-screen message.MAINTENANCE_ MODE_ MESSAGE - Default: unset (maintenance mode off)
- Values: the message text
- While it is set, the container skips database migrations on startup.
-
ARCHESTRA_- Shows a banner at the top of every page, including the sign-in page. The app stays usable.SITE_ NOTIFICATION_ MESSAGE - Default: unset (no banner)
- Values: Markdown text
- Users can dismiss the banner. A changed message shows again.
Authentication
-
ARCHESTRA_- Email of the default admin user, created on first startup.AUTH_ ADMIN_ EMAIL - Default:
admin@example.com
- Default:
-
ARCHESTRA_- Password of the default admin user, set on first startup.AUTH_ ADMIN_ PASSWORD - Default:
password - Change it for any deployment other people can reach.
- Default:
-
ARCHESTRA_- Extra origins allowed for CORS and sign-in, besidesAUTH_ ADDITIONAL_ TRUSTED_ ORIGINS ARCHESTRA_.FRONTEND_ URL - Default: unset
- Values: comma-separated origins, for example
https://idp.example.com,http://192.168.1.5:3000 - Setting it restricts origins to the configured list, even without
ARCHESTRA_. Add your SSO identity provider and any other URL users open the app on.FRONTEND_ URL
-
ARCHESTRA_- Domain the session cookie is scoped to. Set it when the frontend and backend run on different subdomains.AUTH_ COOKIE_ DOMAIN - Default: unset (the cookie stays on the exact frontend host)
- Values: the narrowest domain covering both hosts. For
frontend.example.comandbackend.example.com, useexample.com. - The cookie then reaches every subdomain. Give each other Archestra instance on that domain its own
ARCHESTRA_. Otherwise sign-in loops back to the sign-in page.AUTH_ COOKIE_ PREFIX
-
ARCHESTRA_- Prefix of the auth cookie names, for exampleAUTH_ COOKIE_ PREFIX archestra.session_token.- Default:
archestra - Give each instance a unique prefix when two instances run on one host on different ports, or on sibling subdomains that share a cookie domain. Otherwise their session cookies overwrite each other.
- Default:
-
ARCHESTRA_- Turns off email and password sign-in. Users sign in only through SSO.AUTH_ DISABLE_ BASIC_ AUTH - Default:
false - Values:
true,false - Configure an identity provider before you set it to
true.
- Default:
-
ARCHESTRA_- Turns off user invitations in the UI and the API.AUTH_ DISABLE_ INVITATIONS - Default:
false - Values:
true,false - Use it when an identity provider provisions users.
- Default:
-
ARCHESTRA_- Turns off View as user, so nobody can start an impersonated session.AUTH_ DISABLE_ IMPERSONATION - Default:
false - Values:
true,false - With
false, impersonation still requires themember:impersonatepermission. See Available Permissions.
- Default:
-
ARCHESTRA_- Allows OAuth clients to register themselves (Dynamic Client Registration and CIMD).AUTH_ DCR_ ENABLED - Default:
true - Values:
true,false - With
false, only OAuth clients you register can run OAuth flows.
- Default:
-
ARCHESTRA_- Window, in seconds, in which a replayed OAuth refresh token gets a fresh token pair instead of revoking the grant.AUTH_ REFRESH_ TOKEN_ REUSE_ GRACE_ SECONDS - Default:
60 - Values:
0or more.0treats every replay as reuse. - The window lets a client retry after a lost token response.
- Default:
-
ARCHESTRA_- Turns off rate limiting on the sign-in and auth endpoints.AUTH_ RATE_ LIMIT_ DISABLED - Default:
false - Values:
true,false - The OAuth token endpoint allows 100 requests per minute per client IP, shared across grants and replicas. On HTTP
429, wait for theRetry-Afterdelay. IP resolution followsARCHESTRA_.TRUST_ PROXY - Use it only for load tests or automated test runs.
- Default:
-
ARCHESTRA_- Skips the sign-in page in development by signing in as the user with this email.AUTH_ DEV_ AUTO_ AUTHENTICATE_ EMAIL - Default: unset
- Ignored in production builds. The session has that user's normal permissions.
Encryption and Secrets
-
ARCHESTRA_- Signs session cookies and encrypts JWT signing keys and two-factor secrets.AUTH_ SESSION_ SECRET - Default: Helm generates one in the
<release>-authSecret undersession-secret. Without Helm, it falls back toARCHESTRA_.AUTH_ SECRET - Values: a random string of at least 32 characters, for example from
openssl rand -base64 32 - Changing it signs out every user, invalidates issued JWTs, and makes users with two-factor authentication enroll again.
- Default: Helm generates one in the
-
ARCHESTRA_- Encrypts secrets stored in the database, such as API keys and tokens.SECRETS_ ENCRYPTION_ SECRET - Default: Helm generates one in the
<release>-authSecret undersecrets-encryption-secret. Without Helm, it falls back toARCHESTRA_.AUTH_ SECRET - Values: a random string of at least 32 characters
- Startup stops if this key cannot decrypt the stored secrets. To rotate it, set the old value in
ARCHESTRA_and restart. See Credentials and Secrets.SECRETS_ ENCRYPTION_ SECRET_ PREVIOUS
- Default: Helm generates one in the
-
ARCHESTRA_- Previous encryption secret, used on startup to re-encrypt stored secrets under the new one.SECRETS_ ENCRYPTION_ SECRET_ PREVIOUS - Default:
ARCHESTRA_AUTH_ SECRET - Unset it once re-encryption completes.
- Default:
-
ARCHESTRA_- Lets startup continue with an encryption secret that cannot decrypt the stored secrets.SECRETS_ ACCEPT_ NEW_ ENCRYPTION_ KEY - Default:
false - Values:
true,false - Set it for one boot, then unset it. Secrets encrypted with the old key stay unreadable. Enter them again.
- Default:
-
ARCHESTRA_- Combined secret used for bothAUTH_ SECRET ARCHESTRA_andAUTH_ SESSION_ SECRET ARCHESTRA_when either is unset.SECRETS_ ENCRYPTION_ SECRET - Default: generated on first start. Helm stores it in the
<release>-authSecret; the Docker image saves it to/app/data/.auth_secret. - Set the two dedicated secrets instead, so you can rotate them separately.
- Default: generated on first start. Helm stores it in the
-
ARCHESTRA_- Turns on encryption at rest for LLM Logs, chat messages, and MCP tool call arguments and results. Requires an enterprise license.CONTENT_ ENCRYPTION_ SECRET - Default: unset (content encryption off)
- Startup fails if you set it without an enterprise license. Once content is encrypted, startup also fails if the secret is missing or wrong. See Content Encryption at Rest.
-
ARCHESTRA_- Additional key that decrypts content but never encrypts it.CONTENT_ ENCRYPTION_ SECRET_ PREVIOUS - Default: unset
- Set it during key rotation or a rolling enablement, as Content Encryption at Rest describes. Unset it when re-encryption completes.
-
ARCHESTRA_- Turns on encrypted chats. Archestra escrows each chat key to this RSA public key for recovery.ENCRYPTED_ CHAT_ ESCROW_ PUBLIC_ KEY - Default: unset (encrypted chats unavailable)
- Values: an RSA public key of at least 2048 bits, as PEM or base64-encoded PEM. Startup fails on any other value.
- Set it in its own rollout, after the release is deployed. See Key Escrow for Encrypted Chats and Recovering an Encrypted Chat.
-
ARCHESTRA_- Where Archestra stores secrets such as API keys and tokens.SECRETS_ MANAGER - Default:
DB - Values:
DB,VAULT,READONLY_. Both Vault values require an enterprise license.VAULT - With an invalid Vault configuration or no license, Archestra logs a warning and uses
DB. See Credentials and Secrets.
- Default:
-
ARCHESTRA_- Address of the HashiCorp Vault server.HASHICORP_ VAULT_ ADDR - Required when:
ARCHESTRA_SECRETS_MANAGER=VAULTorREADONLY_VAULT - Values: a URL, for example
https://vault.example.com:8200
- Required when:
-
ARCHESTRA_- How Archestra authenticates to Vault.HASHICORP_ VAULT_ AUTH_ METHOD - Default:
TOKEN - Values:
TOKEN,K8S,AWS
- Default:
-
ARCHESTRA_- Vault token.HASHICORP_ VAULT_ TOKEN - Required when:
ARCHESTRA_HASHICORP_VAULT_AUTH_METHOD=TOKEN
- Required when:
-
ARCHESTRA_- Vault role bound to the Archestra Kubernetes service account.HASHICORP_ VAULT_ K8S_ ROLE - Required when:
ARCHESTRA_HASHICORP_VAULT_AUTH_METHOD=K8S
- Required when:
-
ARCHESTRA_- Path of the service account token used for Kubernetes auth.HASHICORP_ VAULT_ K8S_ TOKEN_ PATH - Default:
/var/run/secrets/kubernetes.io/serviceaccount/token
- Default:
-
ARCHESTRA_- Mount point of Vault's Kubernetes auth method.HASHICORP_ VAULT_ K8S_ MOUNT_ POINT - Default:
kubernetes
- Default:
-
ARCHESTRA_- Vault role bound to the AWS IAM principal Archestra runs as.HASHICORP_ VAULT_ AWS_ ROLE - Required when:
ARCHESTRA_HASHICORP_VAULT_AUTH_METHOD=AWS
- Required when:
-
ARCHESTRA_- Mount point of Vault's AWS auth method.HASHICORP_ VAULT_ AWS_ MOUNT_ POINT - Default:
aws
- Default:
-
ARCHESTRA_- AWS region used to sign the STS request.HASHICORP_ VAULT_ AWS_ REGION - Default:
us-east-1
- Default:
-
ARCHESTRA_- STS endpoint used for AWS auth.HASHICORP_ VAULT_ AWS_ STS_ ENDPOINT - Default:
https://sts.amazonaws.com
- Default:
-
ARCHESTRA_- Value of theHASHICORP_ VAULT_ AWS_ IAM_ SERVER_ ID X-Vault-AWS-IAM-Server-IDheader, when your Vault role requires one.- Default: unset
-
ARCHESTRA_- Version of Vault's KV secrets engine.HASHICORP_ VAULT_ KV_ VERSION - Default:
2 - Values:
1,2
- Default:
-
ARCHESTRA_- Path prefix under which Archestra stores its secrets.HASHICORP_ VAULT_ SECRET_ PATH - Default:
secret/data/archestra(KV v2) orsecret/archestra(KV v1) - A secret named
github_is stored attoken <prefix>/github_token.
- Default:
-
ARCHESTRA_- Path prefix for KV v2 list and delete operations.HASHICORP_ VAULT_ SECRET_ METADATA_ PATH - Default:
ARCHESTRA_withHASHICORP_ VAULT_ SECRET_ PATH /data/replaced by/metadata/ - Set it only when your paths do not follow that pattern.
- Default:
-
ARCHESTRA_- Reads the database connection string from Vault instead ofDATABASE_ URL_ VAULT_ REF ARCHESTRA_.DATABASE_ URL - Default: unset
- Values:
path:key, for examplesecret/data/archestra/database:connection_string - Used only when
ARCHESTRA_SECRETS_MANAGER=READONLY_VAULT.
LLM Providers
These variables set each provider's deployment-wide endpoint and authentication. A base URL saved on a key in Settings → LLM → Model providers overrides the variable for that key. See Supported LLM Providers for setup.
ARCHESTRA_- Deletes the automatic provider key of a keyless provider once that provider is no longer enabled in this deployment's environment, along with the key's virtual key mappings and model pool members. Keyless providers are Gemini on Vertex AI, Azure with Entra ID, keyless Anthropic and Bedrock with IAM.LLM_ SYSTEM_ KEYS_ AUTO_ DELETE_ ENABLED - Default:
true - Values:
true,false - Set it to
falseon every deployment that shares one database with another. Otherwise a deployment deletes the keys of providers that only the other one enables. - A deployment that does not enable a provider still lists that provider's key. Requests it sends with the key fail, and Refresh models reports the key as failed there. Send that provider's traffic to a deployment that enables it.
- While it is
false, the key of a provider you turn off everywhere stays listed and fails when used. Set it totruefor one restart to remove it.
- Default:
OpenAI
-
ARCHESTRA_- Base URL for OpenAI API requests.OPENAI_ BASE_ URL - Default:
https://api.openai.com/v1
- Default:
-
ARCHESTRA_- Codex backend that serves ChatGPT-subscription requests.OPENAI_ CODEX_ API_ BASE_ URL - Default:
https://chatgpt.com/backend-api/codex
- Default:
-
ARCHESTRA_- OAuth issuer for the ChatGPT subscription sign-in.OPENAI_ CODEX_ ISSUER - Default:
https://auth.openai.com
- Default:
-
ARCHESTRA_- OAuth client ID for the ChatGPT subscription sign-in.OPENAI_ CODEX_ CLIENT_ ID - Default: the Codex CLI client ID
-
ARCHESTRA_-OPENAI_ CODEX_ ORIGINATOR originatorheader sent to the Codex backend.- Default:
archestra - Set
codex_if the Codex backend rejects the default.cli_ rs
- Default:
Anthropic
-
ARCHESTRA_- Base URL for Anthropic API requests.ANTHROPIC_ BASE_ URL - Default:
https://api.anthropic.com - For Claude on Microsoft Foundry, use
https://<resource-name>.services.ai.azure.com/anthropic.
- Default:
-
ARCHESTRA_- Authenticates to Claude on Microsoft Foundry with Microsoft Entra ID instead of an API key.ANTHROPIC_ AZURE_ FOUNDRY_ ENTRA_ ID_ ENABLED - Default:
false - Values:
true,false - Requires
ARCHESTRA_set to a FoundryANTHROPIC_ BASE_ URL /anthropicURL. Credentials come from AzureDefaultAzureCredential.
- Default:
-
ARCHESTRA_- Google Cloud project ID that turns on Claude on Vertex AI.ANTHROPIC_ VERTEX_ AI_ PROJECT - Default: unset (Vertex AI off)
- Credentials come from
ARCHESTRA_or Application Default Credentials.ANTHROPIC_ VERTEX_ AI_ CREDENTIALS_ FILE - Turn on only one keyless Anthropic mode: Vertex AI, Workload Identity Federation, or Foundry Entra ID.
-
ARCHESTRA_- Vertex AI location for Claude requests.ANTHROPIC_ VERTEX_ AI_ LOCATION - Default:
global
- Default:
-
ARCHESTRA_- Path to a Google Cloud service account JSON key for Claude on Vertex AI.ANTHROPIC_ VERTEX_ AI_ CREDENTIALS_ FILE - Default: unset (uses Application Default Credentials)
-
ARCHESTRA_- Federation rule ID (ANTHROPIC_ FEDERATION_ RULE_ ID fdrl_...) for keyless Workload Identity Federation.- Default: unset
- Required with
ARCHESTRA_,ANTHROPIC_ ORGANIZATION_ ID ARCHESTRA_, and an identity token. If any of them is missing, federation stays off and Archestra logs a warning.ANTHROPIC_ SERVICE_ ACCOUNT_ ID - Create the rule in the Claude Console under Settings → Workload identity.
-
ARCHESTRA_- Anthropic organization ID for Workload Identity Federation.ANTHROPIC_ ORGANIZATION_ ID - Default: unset
-
ARCHESTRA_- Anthropic service account ID (ANTHROPIC_ SERVICE_ ACCOUNT_ ID svac_...) for Workload Identity Federation.- Default: unset
-
ARCHESTRA_- Anthropic workspace ID (ANTHROPIC_ WORKSPACE_ ID wrkspc_...) for Workload Identity Federation.- Default: unset
- Required only when the federation rule covers more than one workspace.
-
ARCHESTRA_- Path to the OIDC identity token file for Workload Identity Federation, such as a Kubernetes projected service account token.ANTHROPIC_ IDENTITY_ TOKEN_ FILE - Default: unset
- Values: a file path, for example
/var/run/secrets/anthropic.com/token - Rotated tokens apply without a restart. It overrides
ARCHESTRA_.ANTHROPIC_ IDENTITY_ TOKEN
-
ARCHESTRA_- Inline OIDC identity token for Workload Identity Federation.ANTHROPIC_ IDENTITY_ TOKEN - Default: unset
- Identity tokens are short-lived. Use this for testing, and the file variant in production.
Google Gemini
-
ARCHESTRA_- Base URL for Google AI Studio (Gemini API) requests.GEMINI_ BASE_ URL - Default:
https://generativelanguage.googleapis.com - Ignored when
ARCHESTRA_GEMINI_VERTEX_AI_ENABLED=true.
- Default:
-
ARCHESTRA_- Sends Gemini requests to Vertex AI instead of Google AI Studio, with Google Cloud credentials instead of API keys.GEMINI_ VERTEX_ AI_ ENABLED - Default:
false - Values:
true,false - See Using Vertex AI.
- Default:
-
ARCHESTRA_- Google Cloud project ID for Gemini on Vertex AI.GEMINI_ VERTEX_ AI_ PROJECT - Default: unset
- Required when:
ARCHESTRA_GEMINI_VERTEX_AI_ENABLED=true
-
ARCHESTRA_- Vertex AI region for Gemini requests.GEMINI_ VERTEX_ AI_ LOCATION - Default:
us-central1 - Values: a Vertex AI location, for example
europe-west1orglobal - Some regions, including
us-east1, list an incomplete model catalog.us-central1andgloballist the full catalog.
- Default:
-
ARCHESTRA_- Sends requests for models that Vertex AI serves only fromGEMINI_ VERTEX_ AI_ ALLOW_ GLOBAL_ ENDPOINT global, such as Gemini 3 and newer and Nano Banana 2.1, to the global endpoint.- Default:
false - Values:
true,false - With a regional location and this set to
false, those models do not appear in the model list. When enabled, their discovery and requests useglobal. Other models keep usingARCHESTRA_.GEMINI_ VERTEX_ AI_ LOCATION - A configured location of
globalalready sends all Gemini requests there, regardless of this setting. - Leave it
falsewhen your region is a data residency requirement. Google routes global-endpoint requests to any region.
- Default:
-
ARCHESTRA_- Path to a Google Cloud service account JSON key for Gemini on Vertex AI.GEMINI_ VERTEX_ AI_ CREDENTIALS_ FILE - Default: unset (uses Application Default Credentials)
- Needed only outside Google Cloud or without Workload Identity.
Amazon Bedrock
-
ARCHESTRA_- Custom Bedrock runtime endpoint.BEDROCK_ BASE_ URL - Default: unset (
https://bedrock-runtime.<region>.amazonaws.com)
- Default: unset (
-
ARCHESTRA_- AWS region for Bedrock requests.BEDROCK_ REGION - Default: the region in
ARCHESTRA_, otherwiseBEDROCK_ BASE_ URL us-east-1 - A region selected on a key overrides this.
- Default: the region in
-
ARCHESTRA_- Authenticates to Bedrock with the AWS credential chain (IRSA, instance profile, or AWS environment variables) instead of an API key.BEDROCK_ IAM_ AUTH_ ENABLED - Default:
false - Values:
true,false - See IAM Authentication Setup (IRSA).
- Default:
-
ARCHESTRA_- Lists only the Bedrock inference profiles from these model providers.BEDROCK_ ALLOWED_ PROVIDERS - Default: unset (all providers)
- Values: comma-separated provider prefixes, for example
anthropic,amazon
-
ARCHESTRA_- Lists only the Bedrock inference profiles for these regions.BEDROCK_ ALLOWED_ INFERENCE_ REGIONS - Default: unset (all regions)
- Values: comma-separated region prefixes, for example
us,global
Azure AI Foundry
-
ARCHESTRA_- Azure AI Foundry endpoint URL.AZURE_ OPENAI_ BASE_ URL - Default: unset
- Values: a deployment URL,
https://<resource-name>.openai.azure.com/openai/deployments/<deployment-name>, or a Foundry v1 URL,https://<resource-name>.services.ai.azure.com/openai/v1 - Use a Foundry v1 URL for Azure-sold OpenAI-compatible models such as Grok.
-
ARCHESTRA_- Azure OpenAI API version for Chat Completions and deployment discovery.AZURE_ OPENAI_ API_ VERSION - Default:
2024-02-01
- Default:
-
ARCHESTRA_- Azure OpenAI API version for Responses API requests.AZURE_ OPENAI_ RESPONSES_ API_ VERSION - Default:
2025-04-01-preview
- Default:
-
ARCHESTRA_- Authenticates to Azure AI Foundry with Microsoft Entra ID instead of an API key.AZURE_ OPENAI_ ENTRA_ ID_ ENABLED - Default:
false - Values:
true,false - Requires
ARCHESTRA_. Credentials come from AzureAZURE_ OPENAI_ BASE_ URL DefaultAzureCredential.
- Default:
xAI
-
ARCHESTRA_- Base URL for xAI API-key requests.XAI_ BASE_ URL - Default:
https://api.x.ai/v1
- Default:
-
ARCHESTRA_- Endpoint for SuperGrok subscription requests.XAI_ SUBSCRIPTION_ BASE_ URL - Default:
https://cli-chat-proxy.grok.com/v1
- Default:
-
ARCHESTRA_- OAuth issuer for the SuperGrok sign-in.XAI_ SUBSCRIPTION_ ISSUER - Default:
https://auth.x.ai
- Default:
-
ARCHESTRA_- Only browser origin accepted for the SuperGrok sign-in verification page.XAI_ SUBSCRIPTION_ VERIFICATION_ ORIGIN - Default:
https://accounts.x.ai
- Default:
-
ARCHESTRA_- OAuth client ID for the SuperGrok sign-in.XAI_ SUBSCRIPTION_ CLIENT_ ID - Default: the Grok CLI client ID
-
ARCHESTRA_- Grok CLI version reported to the SuperGrok endpoint.XAI_ SUBSCRIPTION_ CLIENT_ VERSION - Default: the Grok CLI version pinned in your Archestra release
- If SuperGrok chat fails with HTTP 426, set this to the version at
https://x.ai/cli/stable.
-
ARCHESTRA_- OAuth scopes requested at SuperGrok sign-in.XAI_ SUBSCRIPTION_ SCOPES - Default:
openid profile email offline_access api:access grok-cli:access - Values: space-separated scopes. Keep
offline_. Removeaccess grok-cli:accessif xAI refuses it for your accounts.
- Default:
GitHub Copilot
-
ARCHESTRA_- Base URL for GitHub Copilot API requests.GITHUB_ COPILOT_ BASE_ URL - Default:
https://api.githubcopilot.com - For GitHub Enterprise, use
https://copilot-api.<ghe-domain>.
- Default:
-
ARCHESTRA_- Endpoint that exchanges a user's GitHub OAuth token for a Copilot API token.GITHUB_ COPILOT_ TOKEN_ EXCHANGE_ URL - Default:
https://api.github.com/copilot_internal/v2/token - For GitHub Enterprise, use
https://copilot-api.<ghe-domain>/copilot_internal/v2/token.
- Default:
-
ARCHESTRA_- GitHub host for the Sign in with GitHub device flow.GITHUB_ COPILOT_ DEVICE_ AUTH_ BASE_ URL - Default:
https://github.com
- Default:
-
ARCHESTRA_- GitHub App client ID for the Sign in with GitHub device flow.GITHUB_ COPILOT_ CLIENT_ ID - Default:
Iv1.b507a08c87ecfe98(the VS Code Copilot client ID) - Set your own GitHub App's client ID if it has Copilot API access.
- Default:
Microsoft 365 Copilot
-
ARCHESTRA_- Application (client) ID of your Entra app registration for Sign in with Microsoft.MICROSOFT_ 365_ COPILOT_ CLIENT_ ID - Default: unset (sign-in unavailable)
- See Microsoft 365 Copilot for the app registration.
-
ARCHESTRA_- Entra tenant that users sign in to.MICROSOFT_ 365_ COPILOT_ TENANT_ ID - Default:
organizations(any work or school account) - Set your tenant ID to restrict sign-in to one directory.
- Default:
-
ARCHESTRA_- Microsoft Graph base URL for the Microsoft 365 Copilot Chat API.MICROSOFT_ 365_ COPILOT_ BASE_ URL - Default:
https://graph.microsoft.com/beta
- Default:
-
ARCHESTRA_- Entra ID host for the sign-in and token endpoints.MICROSOFT_ 365_ COPILOT_ AUTH_ BASE_ URL - Default:
https://login.microsoftonline.com - Change it for a sovereign cloud.
- Default:
OpenRouter
-
ARCHESTRA_- Base URL for OpenRouter API requests.OPENROUTER_ BASE_ URL - Default:
https://openrouter.ai/api/v1
- Default:
-
ARCHESTRA_-OPENROUTER_ REFERER HTTP-Refererattribution header sent to OpenRouter.- Default:
https://archestra.ai - A client's own header takes precedence.
- Default:
-
ARCHESTRA_- App title attribution header sent to OpenRouter.OPENROUTER_ TITLE - Default:
Archestra - A client's own header takes precedence.
- Default:
-
ARCHESTRA_- OpenRouter marketplace categories attribution header.OPENROUTER_ CATEGORIES - Default:
general-chat,personal-agent - Values: comma-separated categories
- Default:
Ollama
-
ARCHESTRA_- Base URL of your Ollama server's OpenAI-compatible API.OLLAMA_ BASE_ URL - Default:
http://localhost:11434/v1 - Ollama is always on. See Ollama.
- Default:
-
ARCHESTRA_- Root URL of your Ollama server for the Ollama (Native) provider, which uses Ollama'sOLLAMA_ NATIVE_ BASE_ URL /api/chatendpoint.- Default:
ARCHESTRA_without theOLLAMA_ BASE_ URL /v1suffix - Set it only when the native endpoint runs on another host. Omit
/v1.
- Default:
Other Providers
-
ARCHESTRA_- Full Jev decisions endpoint. See Jev.JEV_ BASE_ URL - Default:
https://api.typesafe.ai/v1/systemone
- Default:
-
ARCHESTRA_- Base URL of your OpenAI-compatible server (vLLM, llama.cpp, LM Studio, SGLang, TGI, LocalAI).VLLM_ BASE_ URL - Default: unset (provider off)
- Values: a URL, for example
http://localhost:8000/v1 - See OpenAI-Compatible Servers.
-
ARCHESTRA_- LLM proxy URL of another Archestra instance, for the Archestra provider.ARCHESTRA_ BASE_ URL - Default: unset
- Set the URL on each key instead. This variable only turns on raw passthrough at the
/v1/archestraproxy prefix. See Archestra.
-
ARCHESTRA_- Base URL for Cerebras API requests.CEREBRAS_ BASE_ URL - Default:
https://api.cerebras.ai/v1
- Default:
-
ARCHESTRA_- Base URL for Cohere API requests.COHERE_ BASE_ URL - Default:
https://api.cohere.ai
- Default:
-
ARCHESTRA_- Base URL for DeepSeek API requests.DEEPSEEK_ BASE_ URL - Default:
https://api.deepseek.com
- Default:
-
ARCHESTRA_- Base URL for Groq API requests.GROQ_ BASE_ URL - Default:
https://api.groq.com/openai/v1
- Default:
-
ARCHESTRA_- Base URL for Kimi (Moonshot AI) API requests.KIMI_ BASE_ URL - Default:
https://api.moonshot.ai/v1
- Default:
-
ARCHESTRA_- Base URL for MiniMax API requests.MINIMAX_ BASE_ URL - Default:
https://api.minimax.io/v1
- Default:
-
ARCHESTRA_- Base URL for Mistral AI API requests.MISTRAL_ BASE_ URL - Default:
https://api.mistral.ai/v1
- Default:
-
ARCHESTRA_- Base URL for Perplexity API requests.PERPLEXITY_ BASE_ URL - Default:
https://api.perplexity.ai
- Default:
-
ARCHESTRA_- Base URL for Voyage AI embedding requests.VOYAGE_ BASE_ URL - Default:
https://api.voyageai.com/v1
- Default:
-
ARCHESTRA_- Base URL for Zhipu AI API requests.ZHIPUAI_ BASE_ URL - Default:
https://api.z.ai/api/paas/v4
- Default:
LLM Proxy
-
ARCHESTRA_- Controls settlement of provider billing components, including advisor and compaction inference.LLM_ PROXY_ USAGE_ ACCOUNTING_ MODE - Default:
off - Values:
off(legacy accounting),shadow(record candidate charges while applying legacy usage),enforce(apply settled charges to budgets and reports) - Set it on both web and worker pods. Requests retain their starting mode. See Roll Out Usage Accounting.
- Default:
-
ARCHESTRA_- Maximum number of virtual keys per provider API key.LLM_ PROXY_ MAX_ VIRTUAL_ KEYS - Default:
10 - See LLM Proxy Authentication.
- Default:
-
ARCHESTRA_- Default lifetime of a new virtual key, in seconds.LLM_ PROXY_ VIRTUAL_ KEYS_ DEFAULT_ EXPIRATION_ SECONDS - Default:
2592000(30 days) - Values:
0(never expires) up to31536000(one year); larger values are capped at one year - Users can set a different expiration on each key.
- Default:
-
ARCHESTRA_- How long an LLM request waits for response headers or the next stream chunk, in milliseconds.LLM_ PROXY_ UPSTREAM_ TIMEOUT_ MS - Default: unset (5 minutes)
- Raise it when a model can take more than 5 minutes to start or continue a response.
- Keep it below your load balancer's request or idle timeout. For a 600-second load balancer timeout, use
540000.
-
ARCHESTRA_- Longest a streaming response stays silent before Archestra sends an SSE keep-alive comment, in milliseconds.LLM_ PROXY_ STREAM_ KEEPALIVE_ INTERVAL_ MS - Default:
10000(10 seconds) - Values:
0turns it off - Keep it below the shortest stall timeout of your clients. Claude Code reports a stall after 20 seconds.
- Bedrock and Ollama native streams get no keep-alive.
- OpenAI Chat Completions and Responses, OpenAI-compatible chat providers using the shared transport, and Anthropic Messages also receive comments before the first event, once the upstream has accepted the HTTP request. No additional setting is needed.
- Comments cannot cover a provider or ingress that delays its HTTP response headers. They do not extend upstream timeouts or absolute request deadlines; intervening proxies must forward streaming bytes without buffering.
- Buffered policy responses and connection probes keep their existing commit behavior. Other transports keep their existing behavior until the first client event.
- Default:
-
ARCHESTRA_- Records traffic sent with a subscription credential, such as a Claude Pro or Max login, as subscription usage with $0 billed spend.LLM_ COST_ SUBSCRIPTION_ AUTODETECT - Default:
true - Values:
true,false(all traffic is metered) - Archestra records Anthropic requests paid from extra usage credits, after the subscription allowance runs out, as metered. See Subscription vs Metered Cost.
- Default:
Chat
Provider API Keys
At startup, Archestra creates an organization-wide key from each ARCHESTRA_CHAT_<PROVIDER>_API_KEY unless one already exists for that provider. Changing a variable later does not update the existing key. Edit it in Settings → LLM → Model providers instead. The variable is also the last fallback when no stored key matches. A subscription credential, such as a Claude Pro or ChatGPT sign-in, is ignored here. Each user connects their own.
-
ARCHESTRA_- Anthropic API key.CHAT_ ANTHROPIC_ API_ KEY - Default: unset
-
ARCHESTRA_- OpenAI API key.CHAT_ OPENAI_ API_ KEY - Default: unset
-
ARCHESTRA_- Google AI Studio (Gemini) API key.CHAT_ GEMINI_ API_ KEY - Default: unset
-
ARCHESTRA_- Amazon Bedrock API key.CHAT_ BEDROCK_ API_ KEY - Default: unset
-
ARCHESTRA_- Azure AI Foundry API key.CHAT_ AZURE_ OPENAI_ API_ KEY - Default: unset
- Ignored unless
ARCHESTRA_is set.AZURE_ OPENAI_ BASE_ URL
-
ARCHESTRA_- OpenRouter API key.CHAT_ OPENROUTER_ API_ KEY - Default: unset
-
ARCHESTRA_- Cerebras API key.CHAT_ CEREBRAS_ API_ KEY - Default: unset
-
ARCHESTRA_- Cohere API key.CHAT_ COHERE_ API_ KEY - Default: unset
-
ARCHESTRA_- DeepSeek API key.CHAT_ DEEPSEEK_ API_ KEY - Default: unset
-
ARCHESTRA_- Groq API key.CHAT_ GROQ_ API_ KEY - Default: unset
-
ARCHESTRA_- Kimi (Moonshot AI) API key.CHAT_ KIMI_ API_ KEY - Default: unset
-
ARCHESTRA_- MiniMax API key.CHAT_ MINIMAX_ API_ KEY - Default: unset
-
ARCHESTRA_- Mistral AI API key.CHAT_ MISTRAL_ API_ KEY - Default: unset
-
ARCHESTRA_- Perplexity API key.CHAT_ PERPLEXITY_ API_ KEY - Default: unset
-
ARCHESTRA_- Voyage AI API key, used for knowledge base embeddings.CHAT_ VOYAGE_ API_ KEY - Default: unset
-
ARCHESTRA_- xAI API key.CHAT_ XAI_ API_ KEY - Default: unset
-
ARCHESTRA_- Zhipu AI API key.CHAT_ ZHIPUAI_ API_ KEY - Default: unset
-
ARCHESTRA_- API key for your OpenAI-compatible server.CHAT_ VLLM_ API_ KEY - Default: unset
- Ignored unless
ARCHESTRA_is set. Most servers need no key.VLLM_ BASE_ URL
-
ARCHESTRA_- API key for your Ollama server, used by both the Ollama and Ollama (Native) providers.CHAT_ OLLAMA_ API_ KEY - Default: unset
- Most Ollama servers need no key.
-
ARCHESTRA_- API key for another Archestra instance's LLM proxy.CHAT_ ARCHESTRA_ API_ KEY - Default: unset
- Ignored unless
ARCHESTRA_is set.ARCHESTRA_ BASE_ URL
Defaults and Limits
-
ARCHESTRA_- Provider of the last-resort default model, used when the organization has no default model, no synced models, and no provider API key variable.CHAT_ DEFAULT_ PROVIDER - Default:
anthropic - Values: a provider ID, for example
anthropic,openai,gemini,bedrock,azure,ollama. An unknown value falls back toanthropic.
- Default:
-
ARCHESTRA_- Model ID of the last-resort default model.CHAT_ DEFAULT_ MODEL - Default: the default Anthropic model of your Archestra release
- Set it together with
ARCHESTRA_.CHAT_ DEFAULT_ PROVIDER
-
ARCHESTRA_- Upper limit on output tokens for one agent turn, in chat and in A2A runs.CHAT_ MAX_ OUTPUT_ TOKENS - Default:
32768 - Values:
1to1000000 - A turn uses the lower of this value and the model's own output limit. Models without a known limit use
8192.
- Default:
-
ARCHESTRA_- Output token limit for Groq, which charges the requested output budget against a per-minute token allowance.CHAT_ RATE_ METERED_ MAX_ OUTPUT_ TOKENS - Default:
4096 - Values:
1to1000000 - On low Groq tiers, a larger request fails with HTTP 413 before generating anything. Raise it on higher tiers.
- Default:
-
ARCHESTRA_- How long a chat model response may go without sending data before Archestra ends the turn, in milliseconds.CHAT_ MODEL_ STREAM_ IDLE_ TIMEOUT_ MS - Default:
300000(5 minutes) - Keep-alive messages from the provider or a proxy do not count as data. Time spent running tools does not count either.
- The user sees an error with a retry option. Raise it for models that think for a long time before they answer.
- Default:
-
ARCHESTRA_- Largest file a user can attach to a chat message, in bytes.CHAT_ ATTACHMENT_ STORAGE_ BYTES_ LIMIT - Default:
52428800(50 MiB) - Raise
ARCHESTRA_with it. Archestra sends attachments base64-encoded, at about 4/3 of their size, in the same request as the conversation.API_ BODY_ LIMIT
- Default:
-
ARCHESTRA_- Largest attachment sent to the model in a request, in bytes.CHAT_ ATTACHMENT_ INLINE_ BYTES_ LIMIT - Default:
16777216(16 MiB) - A larger attachment is stored but never sent to the model. The provider's own request limit applies too: 32 MiB for Anthropic, 20 MiB for Bedrock.
- Default:
-
ARCHESTRA_- Asks for confirmation before sending a chat message that appears to contain a secret, such as an API key, token, password, or private key.CHAT_ SECRET_ SCAN_ ENABLED - Default:
true - Values:
true,false - The scan runs in the browser, and users can choose Send anyway. It is not a data loss prevention control.
- Default:
Active Run Updates
Chat streams and A2A task streams wake through PostgreSQL LISTEN/NOTIFY across replicas, with polling as a fallback. Change these only to tune database load or to work behind a connection pooler.
-
ARCHESTRA_- How often a reconnecting client checks for new events of a running chat, in milliseconds.CHAT_ ACTIVE_ RUN_ REPLAY_ POLL_ INTERVAL_ MS - Default:
500
- Default:
-
ARCHESTRA_- Fallback interval for checking whether a running chat was stopped, in milliseconds.CHAT_ ACTIVE_ RUN_ STOP_ POLL_ INTERVAL_ MS - Default:
30000
- Default:
-
ARCHESTRA_- PostgreSQL connection string used only forCHAT_ ACTIVE_ RUN_ NOTIFY_ DATABASE_ URL LISTEN/NOTIFY.- Default:
ARCHESTRA_DATABASE_ URL - Set it when regular traffic uses PgBouncer transaction pooling, which cannot hold a listener. Point it at a direct or session-pooled connection.
- Default:
-
ARCHESTRA_- Turns off theCHAT_ ACTIVE_ RUN_ POLLING_ COMPATIBILITY_ ENABLED LISTEN/NOTIFYlistener, so chat and A2A task streams use polling only.- Default:
false - Values:
true,false - Archestra detects an endpoint that cannot deliver notifications and polls faster on its own. Set this only to avoid opening a listener connection that cannot work.
- Default:
MCP Gateway
-
ARCHESTRA_- Timeout for one upstream MCP tool call made through the gateway, in milliseconds.MCP_ GATEWAY_ TOOL_ CALL_ TIMEOUT_ MS - Default:
60000(60 seconds) - Raise it for slow tools, such as a scraper or a report builder, that fail with a request-timeout error.
- A call from a client that supports MCP Tasks becomes a background task after half this value, capped at 10 seconds.
- Default:
-
ARCHESTRA_- Largest reply, in bytes, that Archestra accepts from a stdio MCP server that runs in Kubernetes.MCP_ GATEWAY_ STDIO_ MAX_ MESSAGE_ BYTES - Default:
10485760(10 MB) - A larger reply fails only the tool call that it answers. The model gets an error that names the limit, and the next call to the server works.
- Raise it only if a tool must return more data. Each reply up to this size is held in backend memory until it is complete.
- Default:
-
ARCHESTRA_- How long a tool call waits for a hibernated MCP server to wake before it returns a retryable "still starting" result, in milliseconds.MCP_ GATEWAY_ WAKE_ WAIT_ TIMEOUT_ MS - Default:
30000(30 seconds) - Keep it below your clients' own request timeouts. Otherwise the client aborts first and sees a transport error.
- Default:
-
ARCHESTRA_- Longest one notification stream stays open before the gateway ends it cleanly, in milliseconds.MCP_ GATEWAY_ SUBSCRIPTION_ MAX_ DURATION_ MS - Default:
0(open until the client disconnects) - Values:
0to2147483647. Any other value means0. - Set it below your proxy's maximum request duration, which Archestra cannot detect. A GKE Ingress backend without
timeoutSecallows 30 seconds. - Some clients stop reconnecting after repeated ends and then miss tool-list changes. Test your client first.
- Default:
MCP Servers
-
ARCHESTRA_- Enables optional hardening for backend requests to upstream MCP OAuth providers, for both remote and self-hosted MCP servers.MCP_ OAUTH_ ENFORCE_ OUTBOUND_ VALIDATION - Default:
false. Set exactlytrueto enforce validation. With the default, existing HTTP and private endpoints, redirects, discovery fallbacks and token refresh behavior remain unchanged. This protection is not active by default. - Enforcement covers metadata and scope discovery, dynamic client registration, authorization-code exchange (including proxy servers), refresh and client-credentials grants. Each destination must pass URL and DNS validation and the catalog's environment egress policy; the remote MCP server's base host must also be permitted. Missing organization context or a missing or foreign environment fails closed.
- Production requires HTTPS and public unicast addresses; private, loopback, link-local and reserved addresses are rejected, including mixed DNS answers. Connections use the validated address while retaining the original hostname for TLS. Development and test deployments retain the shared validator's HTTP and loopback exceptions.
- Metadata GETs may follow up to three redirects, validating every destination. Requests carrying credentials cannot follow redirects. Each fetch, including redirects and response reading, has a 30-second deadline and a 1 MiB response limit.
- Before enabling, check that your providers use supported endpoints and that the environment permits their metadata, registration and token hosts. HTTP/private production providers and providers redirecting token POSTs require compatibility mode. Disabling restores compatibility without rotating tokens, clearing credentials or forcing reconnection.
- This setting does not change incoming OAuth authentication to Archestra, the Connection page, LLM provider networking or other outbound URL consumers.
- Default:
-
ARCHESTRA_- Re-syncs every installed MCP server's tools and Skills from the live server at this interval, in minutes.MCP_ SERVER_ TOOLS_ REFRESH_ INTERVAL_ MINUTES - Default: unset (no periodic refresh)
- Values: a positive whole number, for example
30.0disables it. - To refresh one server on demand, use its Inspector tab in the MCP Registry.
-
ARCHESTRA_- API URL for the online MCP server catalog.MCP_ CATALOG_ API_ BASE_ URL - Default:
https://archestra.ai/mcp-catalog/api - Set it when your deployment uses a catalog mirror.
- Default:
MCP Server Orchestrator
-
ARCHESTRA_- Set toORCHESTRATOR_ ENABLED falseto turn the Kubernetes orchestrator off. Archestra then loads no Kubernetes credentials, including the in-cluster service account, and creates, changes or deletes nothing in the cluster.- Default:
true. The Helm chart sets it fromarchestra.orchestrator.enabled. - Use it for an install that shares its database with another install that runs the MCP servers. Self-hosted MCP servers, Agent Runtime and the code sandbox it provisions are unavailable on that install.
- Default:
-
ARCHESTRA_- Uses the in-cluster service account to reach Kubernetes.ORCHESTRATOR_ LOAD_ KUBECONFIG_ FROM_ CURRENT_ CLUSTER - Default:
false. The Helm chart setstrue. - When Archestra runs outside the target cluster, leave it
falseand setARCHESTRA_.ORCHESTRATOR_ KUBECONFIG
- Default:
-
ARCHESTRA_- Path to a kubeconfig file mounted in the container.ORCHESTRATOR_ KUBECONFIG - Default: unset (default kubeconfig locations)
- Example:
/etc/archestra/kubeconfig
-
ARCHESTRA_- Namespace that MCP server pods run in.ORCHESTRATOR_ K8S_ NAMESPACE - Default:
default. The Helm chart sets the release namespace.
- Default:
-
ARCHESTRA_- Namespaces the platform service account has permissions in, offered as a dropdown in the environment editor.ORCHESTRATOR_ ENVIRONMENT_ NAMESPACES - Default: unset (the editor takes free text)
- Values: comma-separated namespaces, for example
staging,production
-
ARCHESTRA_- Cluster resolver addresses that environment egress policies allow DNS to.ORCHESTRATOR_ K8S_ CLUSTER_ DNS_ IPS - Default: unset (discovery reads the
kube-system/kube-dnsService when permitted, then falls back to the platform pod's/etc/resolv.confwhen running in-cluster) - Values: comma-separated IP addresses, for example
172.20.0.10. Helm also accepts a list underarchestra.orchestrator.kubernetes.clusterDnsIps. - Set verified resolver addresses when discovery fails or workloads use a different resolver from the platform pod, such as custom or NodeLocal DNS. Explicit addresses bypass discovery.
- Default: unset (discovery reads the
-
ARCHESTRA_- Cluster DNS domain used to build in-cluster Service addresses.ORCHESTRATOR_ K8S_ CLUSTER_ DOMAIN - Default:
cluster.local
- Default:
-
ARCHESTRA_- Host Archestra uses to reach NodePort Services when it runs outside the cluster.ORCHESTRATOR_ K8S_ NODE_ HOST - Default:
localhost
- Default:
-
ARCHESTRA_- Base image for MCP servers that do not set their own image.ORCHESTRATOR_ MCP_ SERVER_ BASE_ IMAGE - Default:
ghcr.io/archestra-ai/mcp-server-base:<platform version>, pinned by digest on a released chart (seeARCHESTRA_)RELEASE_ IMAGE_ DIGESTS
- Default:
-
ARCHESTRA_- CPU request for each MCP server container.ORCHESTRATOR_ MCP_ SERVER_ CPU_ REQUEST - Default:
50m - Values: Kubernetes quantity
- Default:
-
ARCHESTRA_- Memory request for each MCP server container.ORCHESTRATOR_ MCP_ SERVER_ MEMORY_ REQUEST - Default:
128Mi - Values: Kubernetes quantity
- Default:
-
ARCHESTRA_- Memory limit for each MCP server container.ORCHESTRATOR_ MCP_ SERVER_ MEMORY_ LIMIT - Default:
512Mi - Values: Kubernetes quantity
- Default:
-
ARCHESTRA_- Ephemeral-storage request for each MCP server container.ORCHESTRATOR_ MCP_ SERVER_ EPHEMERAL_ STORAGE_ REQUEST - Default:
256Mi - Values: Kubernetes quantity
- Default:
-
ARCHESTRA_- Ephemeral-storage limit for each MCP server container.ORCHESTRATOR_ MCP_ SERVER_ EPHEMERAL_ STORAGE_ LIMIT - Default:
1Gi - Values: Kubernetes quantity
- Default:
-
ARCHESTRA_- How often Archestra deletes Failed or Evicted MCP server pods, in seconds.ORCHESTRATOR_ FAILED_ POD_ REAP_ INTERVAL_ SECONDS - Default:
600 - Values: a positive whole number.
0disables it.
- Default:
-
ARCHESTRA_- How often Archestra checks whether a running MCP server'sORCHESTRATOR_ MCP_ IMAGE_ UPDATE_ CHECK_ INTERVAL_ MINUTES :latestor untagged image points to a new build, and rolls the server onto it, in minutes.- Default:
15 - Values: a whole number.
0turns the check off. - Pin an image tag when a server must not change on its own.
- Default:
-
ARCHESTRA_- How long an MCP server pod sits unused before it hibernates, in seconds.ORCHESTRATOR_ MCP_ IDLE_ HIBERNATION_ SECONDS - Default:
1800(30 minutes) - Values:
0, or120and above. Lower values are raised to120. 0turns hibernation off for the whole deployment, whatever the organization setting.- Hibernation also needs
ARCHESTRA_BETA=true, an enterprise license, and the organization setting turned on.
- Default:
-
ARCHESTRA_- Caches MCP server images on every node with a DaemonSet, so hibernated servers wake without pulling from the registry.ORCHESTRATOR_ MCP_ IMAGE_ PREPULL_ ENABLED - Default:
true - Runs only while idle hibernation is on. Set
falseto keep hibernation without the DaemonSet, which takes a pod slot on every eligible node.
- Default:
-
ARCHESTRA_- Image for the pre-pull DaemonSet's own containers.ORCHESTRATOR_ MCP_ IMAGE_ PREPULL_ BOOTSTRAP_ IMAGE - Default:
docker.io/library/busybox:1.36-musl - The image must provide a statically linked
/bin/busybox. Point it at a mirror when your cluster cannot pull from Docker Hub.
- Default:
-
ARCHESTRA_- Image pull secrets for the bootstrap image.ORCHESTRATOR_ MCP_ IMAGE_ PREPULL_ BOOTSTRAP_ IMAGE_ PULL_ SECRETS - Default: unset
- Values: comma-separated secret names in the MCP server namespace
-
ARCHESTRA_- Priority class for the pre-pull DaemonSet pods.ORCHESTRATOR_ MCP_ IMAGE_ PREPULL_ PRIORITY_ CLASS_ NAME - Default: unset (namespace default)
- Use a low-priority class so caching images never preempts real workloads.
-
ARCHESTRA_- CPU request for each pre-pull pod.ORCHESTRATOR_ MCP_ IMAGE_ PREPULL_ CPU_ REQUEST - Default:
10m - Values: Kubernetes quantity
- Default:
-
ARCHESTRA_- Memory request for each pre-pull pod.ORCHESTRATOR_ MCP_ IMAGE_ PREPULL_ MEMORY_ REQUEST - Default:
16Mi - Values: Kubernetes quantity
- Default:
-
ARCHESTRA_- Memory limit for each pre-pull pod.ORCHESTRATOR_ MCP_ IMAGE_ PREPULL_ MEMORY_ LIMIT - Default:
64Mi - Values: Kubernetes quantity
- Default:
-
ARCHESTRA_- Role in each runtime namespace that Archestra uses to remove the MCP resources it created when the chart is uninstalled.ORCHESTRATOR_ MCP_ RUNTIME_ OWNER_ ROLE - Default: set by the Helm chart when it manages orchestrator permissions
- With your own RBAC, create a Role with this name in every runtime namespace, and delete each one during uninstall.
-
ARCHESTRA_- Release name used to name cluster objects Archestra creates outside the chart, such as the image pre-pull DaemonSet.ORCHESTRATOR_ HELM_ RELEASE_ NAME - Default: set by the Helm chart. Set it yourself only when you deploy without the chart.
- When unset, those objects are not created.
MCP Apps Sandbox
MCP Apps render in sandboxed iframes. Without a sandbox domain, apps still work. They cannot use localStorage, cookies, or origin-restricted APIs. See Deployment for setup.
ARCHESTRA_- Wildcard domain that gives each MCP server's apps their own origin.MCP_ SANDBOX_ DOMAIN - Default: unset (opaque iframe origin)
- Example:
mcp.example.com - Requires a wildcard DNS record and TLS certificate for
*.mcp.example.comthat route to the backend.
A2A Gateway
ARCHESTRA_- Days a finished A2A task is kept before it is deleted with its artifacts, stream events, and execution transcript.A2A_ TASK_ RETENTION_ DAYS - Default:
90 - Values: a whole number of days.
0keeps tasks forever. - Running tasks are never deleted. The conversation history the task belongs to is kept.
- Default:
Code Sandbox
Archestra creates one Dagger engine per organization and per environment. Each engine needs a node that admits privileged pods and a storage class for ReadWriteOnce volumes. See Deployment.
-
ARCHESTRA_- Enables the per-conversation code sandbox, where agents run shell commands and Python.CODE_ RUNTIME_ ENABLED - Default:
false. The Docker quickstart image and the Helm chart (archestra.codeRuntime.enabled) default totrue. - Values:
true,false.falseturns the sandbox off even whenARCHESTRA_is set.CODE_ RUNTIME_ DAGGER_ RUNNER_ HOST - Requires the orchestrator. When off,
run_and the other sandbox tools are unavailable and skill scripts cannot run.command
- Default:
-
ARCHESTRA_- Address of a Dagger engine you run yourself, used instead of an Archestra-managed engine.CODE_ RUNTIME_ DAGGER_ RUNNER_ HOST - Default: unset (Archestra manages every engine)
- Values: a
tcp://orkube-pod://URL, for exampletcp://dagger-engine:8080. Any other value turns the code sandbox off. - Setting it enables the code sandbox. Agents bound to an environment still run on that environment's managed engine.
-
ARCHESTRA_- Base image for sandbox containers.DAGGER_ RUNTIME_ IMAGE - Default:
ghcr.io/astral-sh/uv:0.13.4-python3.14-trixie-slim - Values: a Debian-based image
- Default:
-
ARCHESTRA_- Skips the per-sandbox package install becauseCODE_ RUNTIME_ BASE_ PREBUILT ARCHESTRA_is a pre-built sandbox base image.DAGGER_ RUNTIME_ IMAGE - Default:
false - Values:
true,false - With
true, engines with restricted egress need to reach only the base image's registry, notghcr.io, Debian mirrors, or PyPI. Sandboxes fail if the image is not the pre-built base.
- Default:
-
ARCHESTRA_- CPU request for each engine Archestra creates.DAGGER_ RUNTIME_ ENGINE_ CPU_ REQUEST - Default:
2 - Values: Kubernetes quantity
- Engine resource settings apply to new engines only. Delete an engine to resize it.
- Default:
-
ARCHESTRA_- Memory request for each engine Archestra creates. It reserves node capacity for the engine and its sandboxes.DAGGER_ RUNTIME_ ENGINE_ MEMORY_ REQUEST - Default:
6Gi - Values: Kubernetes quantity
- Default:
-
ARCHESTRA_- Memory limit for each engine process. It does not cover the sandboxes; seeDAGGER_ RUNTIME_ ENGINE_ MEMORY_ LIMIT ARCHESTRA_.DAGGER_ RUNTIME_ ENGINE_ SANDBOX_ MEMORY_ MAX - Default:
6Gi - Values: Kubernetes quantity
- Default:
-
ARCHESTRA_- Size of each engine's build-cache volume.DAGGER_ RUNTIME_ ENGINE_ CACHE_ STORAGE - Default:
50Gi - Values: Kubernetes quantity
- Default:
-
ARCHESTRA_- Total memory all of an engine's sandboxes can use at once. A run that exceeds it is killed; other runs continue.DAGGER_ RUNTIME_ ENGINE_ SANDBOX_ MEMORY_ MAX - Default:
5Gi - Values: Kubernetes quantity. Keep it below
ARCHESTRA_.DAGGER_ RUNTIME_ ENGINE_ MEMORY_ REQUEST - For heavy concurrent work, raise it with the memory request, or lower
ARCHESTRA_.DAGGER_ RUNTIME_ MAX_ CONCURRENT
- Default:
-
ARCHESTRA_- Extra IPv4 ranges that sandboxed code cannot reach.DAGGER_ RUNTIME_ ENGINE_ ADDITIONAL_ DENIED_ CIDRS - Default: unset
- Values: comma-separated CIDRs, for example
100.68.0.0/16,34.118.224.0/20. Invalid entries are ignored and logged. - Engines without a network policy already block private, link-local, and cloud-metadata ranges. Add your cluster's Service and Pod CIDRs when they fall outside those ranges.
-
ARCHESTRA_- Schedules engines onto a dedicated node pool.DAGGER_ RUNTIME_ ENGINE_ NODE_ SELECTOR - Default: unset (engines use the platform pod's
nodeSelectorandtolerations) - Values: comma-separated
key=valuepairs, for examplearchestra-sandbox=true. Each pair also adds a matchingNoScheduletoleration. - Applies to new engines only. Delete an engine to move it.
- Default: unset (engines use the platform pod's
-
ARCHESTRA_- Sandbox commands each backend process runs at once.DAGGER_ RUNTIME_ MAX_ CONCURRENT - Default:
10 - Raise it together with the engine's CPU and memory.
- Default:
-
ARCHESTRA_- Sandbox commands each backend process can queue for a free slot. Beyond this, a command fails with a runtime-at-capacity error.DAGGER_ RUNTIME_ MAX_ QUEUE_ LENGTH - Default:
50
- Default:
-
ARCHESTRA_- CPU time one sandbox command can use, in seconds.SKILLS_ SANDBOX_ CPU_ LIMIT_ SECONDS - Default:
30
- Default:
-
ARCHESTRA_- Memory one sandbox command can use, in bytes.SKILLS_ SANDBOX_ MEMORY_ LIMIT_ BYTES - Default:
1073741824(1 GiB)
- Default:
-
ARCHESTRA_- Wall-clock time one sandbox command can run, in seconds. Longer timeouts that callers request are lowered to this.SKILLS_ SANDBOX_ WALL_ CLOCK_ SECONDS - Default:
120
- Default:
-
ARCHESTRA_- Output (stdout and stderr) kept per command, in bytes. The rest is truncated.SKILLS_ SANDBOX_ OUTPUT_ BYTES_ LIMIT - Default:
262144(256 KiB)
- Default:
-
ARCHESTRA_- Largest file the sandbox can read, save, or export to the conversation's Files panel, and the largest chat attachment it can stage, in bytes.SKILLS_ SANDBOX_ ARTIFACT_ BYTES_ LIMIT - Default:
52428800(50 MiB), equal to theARCHESTRA_defaultCHAT_ ATTACHMENT_ STORAGE_ BYTES_ LIMIT - Chat still stores a larger attachment; it is not staged in the sandbox.
- Default:
-
ARCHESTRA_- Days a sandbox from a run without a conversation, such as an A2A task, is kept after its last command, upload or skill mount before it is deleted. Files it exported are kept.SKILLS_ SANDBOX_ HEADLESS_ RETENTION_ DAYS 0keeps them forever.- Default:
7
- Default:
-
ARCHESTRA_- Path to the Dagger CLI executable used by the sandbox.DAGGER_ RUNTIME_ CLI_ BIN - Default: unset (uses the bundled or discovered CLI)
Agent Runtime
Agent Runtime turns on when the orchestrator's cluster has the Agent Sandbox controller installed. Agents can override the settings described as defaults. See Agent Runtime for cluster setup.
-
ARCHESTRA_- Registry the maintained Claude Code, Codex, OpenCode, Hermes, and OpenClaw images are pulled from.AGENT_ RUNTIME_ IMAGE_ REGISTRY - Default:
ghcr.io/archestra-ai - Set it when you mirror these images to a private registry.
- Default:
-
ARCHESTRA_- Tag of the maintained images.AGENT_ RUNTIME_ IMAGE_ TAG - Default: the platform version, pinned by digest on a released chart (see
ARCHESTRA_)RELEASE_ IMAGE_ DIGESTS - Agents made from a catalog template run this tag, whatever tag was current when they were created. See Upgrades.
- Default: the platform version, pinned by digest on a released chart (see
-
ARCHESTRA_- Lets Agent administrators enable privileged runtime pods, which have node-level access.AGENT_ RUNTIME_ ALLOW_ PRIVILEGED - Default:
false - Values:
true,false
- Default:
-
ARCHESTRA_- URL a runtime pod uses to reach the LLM proxy and MCP gateway. It must be reachable from inside the cluster.AGENT_ RUNTIME_ PLATFORM_ BASE_ URL - Default:
ARCHESTRA_INTERNAL_ API_ BASE_ URL - When neither is set, runs fail to start.
- Default:
-
ARCHESTRA_- Default maximum lifetime of a run, in hours.AGENT_ RUNTIME_ DEFAULT_ TTL_ HOURS - Default:
72
- Default:
-
ARCHESTRA_- Default time an idle run waits for the next instruction before it stops, in minutes.AGENT_ RUNTIME_ DEFAULT_ IDLE_ TIMEOUT_ MINUTES - Default:
180 - Custom images must implement the wait, using the
ARCHESTRA_variable passed to the pod.AGENT_ RUNTIME_ IDLE_ TIMEOUT_ SECONDS
- Default:
-
ARCHESTRA_- Default CPU request for a run's pod. Runs have no CPU limit.AGENT_ RUNTIME_ CPU_ REQUEST - Default:
500m - Values: Kubernetes quantity
- Default:
-
ARCHESTRA_- Default memory request for a run's pod.AGENT_ RUNTIME_ MEMORY_ REQUEST - Default:
1Gi - Values: Kubernetes quantity
- Default:
-
ARCHESTRA_- Default memory limit for a run's pod.AGENT_ RUNTIME_ MEMORY_ LIMIT - Default:
4Gi - Values: Kubernetes quantity
- Default:
-
ARCHESTRA_- Size of each run's persistent volume, which holdsAGENT_ RUNTIME_ WORKSPACE_ STORAGE_ SIZE /home/nodeand, for privileged runs,/var/lib/docker.- Default:
20Gi - Values: Kubernetes quantity
- Default:
-
ARCHESTRA_- Storage class for run volumes.AGENT_ RUNTIME_ WORKSPACE_ STORAGE_ CLASS - Default: unset (the cluster's default storage class)
- Use a CSI-backed class with
WaitForFirstConsumerbinding when nodes span zones.
-
ARCHESTRA_- Spare containers kept ready per group of Agents with matching container settings, so new runs start faster.AGENT_ RUNTIME_ WARM_ POOL_ SIZE - Default:
0(warm pools off) - Spare containers reserve CPU, memory, and storage while idle. See Agent Runtime.
- Default:
-
ARCHESTRA_- Maximum number of warm pools. Agents outside them start containers on demand.AGENT_ RUNTIME_ WARM_ POOL_ MAX_ POOLS - Default:
4
- Default:
-
ARCHESTRA_- Pulls every catalog Agent image onto each runtime node at startup and after each upgrade, so the first run of an Agent does not wait for its image. Turn it off when node disk or registry bandwidth is tight; each run then pulls only its own image.AGENT_ RUNTIME_ IMAGE_ PREFETCH_ ENABLED - Default:
true
- Default:
-
ARCHESTRA_- Schedules runtime pods onto a dedicated node pool.AGENT_ RUNTIME_ NODE_ SELECTOR - Default: unset (scheduled like any other pod)
- Values: comma-separated
key=valuepairs, for examplearchestra-agent-runtime=true. Each pair also adds a matchingNoScheduletoleration.
-
ARCHESTRA_- RuntimeClass for unprivileged runtime pods, such asAGENT_ RUNTIME_ RUNTIME_ CLASS_ NAME gvisor, so a run does not share the node's kernel.- Default: unset (the cluster's default runtime)
- Privileged runtime pods ignore it, because gVisor cannot run privileged containers. The cluster needs nodes that serve the RuntimeClass, such as a GKE Sandbox node pool.
-
ARCHESTRA_- Label selector for the platform's API pods. Runtime pods may send traffic only to pods that match.AGENT_ RUNTIME_ PLATFORM_ POD_ SELECTOR - Default:
archestra.io/platform-api=true(set on API pods by the Helm chart) - Values: comma-separated
key=valuepairs - With custom manifests, add this label to the API pods or set a selector that matches them.
- Default:
-
ARCHESTRA_- How long a run's pod can stay pending before the run fails, in seconds.AGENT_ RUNTIME_ POD_ START_ TIMEOUT_ SECONDS - Default:
600 - Raise it for autoscaled node pools, where node creation and a large image pull can exceed the default.
- Default:
-
ARCHESTRA_- How often Archestra syncs run state and applies the lifetime and idle limits, in seconds.AGENT_ RUNTIME_ RECONCILE_ INTERVAL_ SECONDS - Default:
30
- Default:
-
ARCHESTRA_- Largest run output kept as a complete transcript, in uncompressed bytes.AGENT_ RUNTIME_ TRANSCRIPT_ MAX_ BYTES - Default:
262144000(250 MiB) - A larger run keeps only its last 1 MiB, labeled Retained tail only in the terminal. Transcripts are deleted with their A2A task; see
ARCHESTRA_.A2A_ TASK_ RETENTION_ DAYS
- Default:
Knowledge Base
Embedding, reranking, and OCR models for the Knowledge Base are chosen in Settings → Knowledge, not here.
-
ARCHESTRA_- Combines vector search with keyword (BM25) search and merges the results.KNOWLEDGE_ BASE_ HYBRID_ SEARCH_ ENABLED - Default:
true - Values:
true,false(vector search only)
- Default:
-
ARCHESTRA_- Deployment default for BM25 term saturation: how much a repeated word keeps raising a passage's score.KNOWLEDGE_ BASE_ BM25_ K1 - Default:
1.2 - Values:
0–10.0scores a word the same whether it appears once or many times. - An organization's value under Settings → Knowledge → Search ranking → Advanced options overrides it.
- Default:
-
ARCHESTRA_- Deployment default for BM25 length normalization: how much long passages are ranked below short ones that match the same words.KNOWLEDGE_ BASE_ BM25_ B - Default:
0.75 - Values:
0(length ignored) to1(full normalization) - An organization's value under Settings → Knowledge → Search ranking → Advanced options overrides it.
- Default:
-
ARCHESTRA_- Maximum number of keyword-matching chunks that BM25 rescores per query.KNOWLEDGE_ BASE_ BM25_ RECALL_ CAP - Default:
2000 - Values:
10–100000 - Query cost grows with the cap. Raise it when broad queries matter more than latency.
- Default:
-
ARCHESTRA_- How often the corpus statistics that BM25 ranks with are rebuilt.KNOWLEDGE_ BASE_ BM25_ STATS_ REFRESH_ INTERVAL_ SECONDS - Default:
3600 - Values:
60–86400 - Each rebuild reads every chunk. Keyword search uses a simpler ranking until the first rebuild succeeds.
- Default:
-
ARCHESTRA_- How long one BM25 statistics rebuild may run before it is cancelled.KNOWLEDGE_ BASE_ BM25_ STATS_ REFRESH_ TIMEOUT_ MS - Default:
900000(15 minutes) - Values:
30000–21600000 - Raise it if rebuilds on a very large corpus are cancelled.
- Default:
-
ARCHESTRA_- Timeout for each knowledge search query (vector and keyword run separately).KNOWLEDGE_ BASE_ SEARCH_ STATEMENT_ TIMEOUT_ MILLIS - Default:
8000 - Values:
0–120000.0usesARCHESTRA_.DATABASE_ STATEMENT_ TIMEOUT_ MILLIS - Archestra drops a timed-out search and returns the other results. The query fails only when all of them time out.
- Default:
-
ARCHESTRA_- In the built-in chat, asks the model to back claims with verbatim quotes and logs each quote that does not match the cited chunk.KNOWLEDGE_ BASE_ QUOTE_ VERIFICATION_ ENABLED - Default:
true - Values:
true,false - Log-only: it never blocks or changes an answer. Misses are counted in the
rag_metric.quote_ verification_ total
- Default:
-
ARCHESTRA_- Token budget for one chunk, including its title and metadata.KNOWLEDGE_ BASE_ CHUNK_ SIZE_ TOKENS - Default:
512 - Values:
128–2048 - Applies at ingest. Existing chunks keep their size until their connector re-syncs.
- Default:
-
ARCHESTRA_- Token budget for child chunks. Search matches the smaller children and returns their parent passage.KNOWLEDGE_ BASE_ CHILD_ CHUNK_ SIZE_ TOKENS - Default:
0(off) - Values:
0, or32–2048. Set it belowARCHESTRA_.KNOWLEDGE_ BASE_ CHUNK_ SIZE_ TOKENS - Stored vectors grow by about the ratio of the two sizes. Applies at ingest.
- Default:
-
ARCHESTRA_- Number of neighboring chunks on each side of a search hit that are returned with it.KNOWLEDGE_ BASE_ CONTEXT_ EXPANSION_ RADIUS - Default:
1 - Values:
0–4.0returns the hit alone. - Each step adds up to two chunks per result, so the model reads more tokens.
- Default:
-
ARCHESTRA_- Default contextual retrieval mode for organizations that have not chosen one in Settings → Knowledge.KNOWLEDGE_ BASE_ CONTEXTUAL_ RETRIEVAL_ ENABLED - Default:
false(no context) - Values:
true(per-document context),false - Per-document context makes one call to the reranking model per changed document.
- Default:
-
ARCHESTRA_- Maximum number of pages without text that Document OCR transcribes in one PDF.KNOWLEDGE_ BASE_ OCR_ MAX_ PAGES_ PER_ DOCUMENT - Default:
100 - Each page is one call to the OCR model. Pages past the limit stay untranscribed. The document shows a partial-extraction warning.
- Default:
-
ARCHESTRA_- Path to the Chromium executable that the Web Crawler uses to render JavaScript pages.KNOWLEDGE_ BASE_ CRAWLER_ CHROMIUM_ PATH - Default: unset (the default Chromium location)
- The standard image does not include Chromium. See Web Crawler.
-
ARCHESTRA_- Number of connector sync and embedding tasks each worker runs at once.KNOWLEDGE_ BASE_ TASK_ WORKER_ MAX_ CONCURRENT - Default:
2
- Default:
-
ARCHESTRA_- Number of permission sync tasks each worker runs at once.KNOWLEDGE_ BASE_ PERMISSION_ SYNC_ WORKER_ MAX_ CONCURRENT - Default:
1 - Permission sync has its own slots and never waits for content sync.
- Default:
-
ARCHESTRA_- How often a worker checks for new background tasks.KNOWLEDGE_ BASE_ TASK_ WORKER_ POLL_ INTERVAL_ SECONDS - Default:
5
- Default:
-
ARCHESTRA_- How long a stopping worker waits for running tasks to finish.KNOWLEDGE_ BASE_ TASK_ WORKER_ SHUTDOWN_ TIMEOUT_ SECONDS - Default:
30
- Default:
-
ARCHESTRA_- Maximum time one connector sync run works before it saves a checkpoint and continues in a new run.KNOWLEDGE_ BASE_ CONNECTOR_ SYNC_ MAX_ DURATION_ SECONDS - Default:
3300(55 minutes) - Values: seconds.
0lets a sync finish in one run.
- Default:
-
ARCHESTRA_- How long a sync run may go without a heartbeat before it is treated as crashed and resumed from its checkpoint.KNOWLEDGE_ BASE_ CONNECTOR_ RUN_ LEASE_ TTL_ SECONDS - Default:
300 - Keep it several times
ARCHESTRA_.KNOWLEDGE_ BASE_ CONNECTOR_ RUN_ HEARTBEAT_ INTERVAL_ SECONDS
- Default:
-
ARCHESTRA_- How often a running sync sends a heartbeat.KNOWLEDGE_ BASE_ CONNECTOR_ RUN_ HEARTBEAT_ INTERVAL_ SECONDS - Default:
90
- Default:
-
ARCHESTRA_- How long a document may wait for embedding before it is queued again.KNOWLEDGE_ BASE_ STALLED_ EMBEDDING_ AGE_ SECONDS - Default:
900(15 minutes) - Keep it above 8 minutes, the full retry span of an embedding task. A lower value re-embeds documents that are still in progress.
- Default:
-
ARCHESTRA_- Largest single file you can upload to Knowledge Files.KNOWLEDGE_ FILES_ MAX_ UPLOAD_ BYTES - Default:
26214400(25 MiB)
- Default:
-
ARCHESTRA_- Maximum number of files one directory selection expands to when you index Knowledge Files.KNOWLEDGE_ FILES_ MAX_ FILES_ PER_ INDEX_ REQUEST - Default:
500
- Default:
Google Drive
These configure the OAuth client for the Google Drive connector's individual auth mode. Service-account modes do not use them.
-
ARCHESTRA_- Client ID of the deployment's Google OAuth client.KNOWLEDGE_ BASE_ GOOGLE_ DRIVE_ OAUTH_ CLIENT_ ID - Default: unset (individual mode disabled)
- Changing it invalidates existing authorizations. Each affected connector must reconnect.
-
ARCHESTRA_- Client secret of the deployment's Google OAuth client.KNOWLEDGE_ BASE_ GOOGLE_ DRIVE_ OAUTH_ CLIENT_ SECRET - Default: unset (individual mode disabled)
- Rotating only the secret needs no reconnect.
M-Files
-
ARCHESTRA_- Turns on the beta M-Files connector.KNOWLEDGE_ BASE_ MFILES_ CONNECTOR_ ENABLED - Default: unset (follows
ARCHESTRA_)BETA - Values:
true,false. Existing M-Files connectors keep syncing while it is off.
- Default: unset (follows
-
ARCHESTRA_- Directory that serves the VAF Add On package to the install script and the connector form.KNOWLEDGE_ BASE_ MFILES_ VAF_ ADD_ ON_ PACKAGE_ DIR - Default:
/app/mfiles-vaf-add-on
- Default:
Perforce
Perforce permission sync runs the p4 CLI in a per-connector pod and needs the Kubernetes orchestrator. Archestra downloads the p4 binary from Perforce and checks its SHA-256. Air-gapped installs point the URLs at an internal mirror and set matching checksums.
-
ARCHESTRA_- Image of the pod that runsKNOWLEDGE_ BASE_ PERFORCE_ SHIM_ IMAGE p4for permission sync.- Default:
ghcr.io/archestra-ai/p4-shim:<platform version>, pinned by digest on a released chart (seeARCHESTRA_)RELEASE_ IMAGE_ DIGESTS
- Default:
-
ARCHESTRA_- Download URL of theKNOWLEDGE_ BASE_ PERFORCE_ P4_ URL_ AMD64 p4binary for x86-64 nodes.- Default:
https://cdist2.perforce.com/perforce/r25.2/bin.linux26x86_64/p4
- Default:
-
ARCHESTRA_- Expected SHA-256 of the x86-64KNOWLEDGE_ BASE_ PERFORCE_ P4_ SHA256_ AMD64 p4binary. A download that does not match is rejected.- Default: the checksum of the r25.2 build
-
ARCHESTRA_- Download URL of theKNOWLEDGE_ BASE_ PERFORCE_ P4_ URL_ ARM64 p4binary for ARM64 nodes.- Default:
https://cdist2.perforce.com/perforce/r25.2/bin.linux26aarch64/p4
- Default:
-
ARCHESTRA_- Expected SHA-256 of the ARM64KNOWLEDGE_ BASE_ PERFORCE_ P4_ SHA256_ ARM64 p4binary. A download that does not match is rejected.- Default: the checksum of the r25.2 build
File Storage
A change of ARCHESTRA_ applies to new files only. Existing files stay readable where they were written.
-
ARCHESTRA_- Storage backend for My Files contents.FILE_ STORAGE_ PROVIDER - Default:
db - Values:
db(PostgreSQL),filesystem(a mounted volume),s3(an S3-compatible object store)
- Default:
-
ARCHESTRA_- Absolute path of the directory that stores files, for example a persistent volume mount.FILE_ STORAGE_ FILESYSTEM_ ROOT - Required when:
ARCHESTRA_FILE_STORAGE_PROVIDER=filesystem - Example:
/var/archestra/files
- Required when:
-
ARCHESTRA_- Bucket that stores files.FILE_ STORAGE_ S3_ BUCKET - Required when:
ARCHESTRA_FILE_STORAGE_PROVIDER=s3
- Required when:
-
ARCHESTRA_- Region of the bucket.FILE_ STORAGE_ S3_ REGION - Default:
us-east-1
- Default:
-
ARCHESTRA_- Endpoint of an S3-compatible store such as MinIO or Cloudflare R2.FILE_ STORAGE_ S3_ ENDPOINT - Default: unset (AWS S3)
- Example:
http://minio:9000
-
ARCHESTRA_- Uses path-style bucket addressing instead of virtual-hosted style.FILE_ STORAGE_ S3_ FORCE_ PATH_ STYLE - Default:
false - Values:
true,false - MinIO requires
true.
- Default:
-
ARCHESTRA_- Access key ID for the bucket.FILE_ STORAGE_ S3_ ACCESS_ KEY_ ID - Default: unset (the AWS default credential chain, including instance profiles and IRSA)
- Startup fails if it is set without
ARCHESTRA_.FILE_ STORAGE_ S3_ SECRET_ ACCESS_ KEY
-
ARCHESTRA_- Secret access key for the bucket.FILE_ STORAGE_ S3_ SECRET_ ACCESS_ KEY - Default: unset
- Startup fails if it is set without
ARCHESTRA_.FILE_ STORAGE_ S3_ ACCESS_ KEY_ ID
-
ARCHESTRA_- Folder inside the bucket that stores files.FILE_ STORAGE_ S3_ KEY_ PREFIX - Default: unset (bucket root)
- Example:
archestra-prod/ - To share one bucket between instances, give each its own prefix.
Skills Marketplace
-
ARCHESTRA_- Path to theGIT_ BINARY_ PATH gitbinary that serves marketplace clones.- Default:
git
- Default:
-
ARCHESTRA_- Directory that caches the marketplace git repositories.SKILL_ MARKETPLACE_ CACHE_ DIR - Default:
~/.archestra/skill-marketplace-cache - Put it on a persistent volume in production.
- Default:
Incoming Email
These variables connect an Outlook mailbox so people can email agents.
-
ARCHESTRA_- Provider of the agent mailbox.AGENTS_ INCOMING_ EMAIL_ PROVIDER - Default: unset (incoming email off)
- Values:
outlook
-
ARCHESTRA_- Microsoft Entra tenant ID of the app registration that reads the mailbox.AGENTS_ INCOMING_ EMAIL_ OUTLOOK_ TENANT_ ID - Required when:
ARCHESTRA_AGENTS_INCOMING_EMAIL_PROVIDER=outlook
- Required when:
-
ARCHESTRA_- Application (client) ID of that app registration.AGENTS_ INCOMING_ EMAIL_ OUTLOOK_ CLIENT_ ID - Required when:
ARCHESTRA_AGENTS_INCOMING_EMAIL_PROVIDER=outlook
- Required when:
-
ARCHESTRA_- Client secret of that app registration.AGENTS_ INCOMING_ EMAIL_ OUTLOOK_ CLIENT_ SECRET - Required when:
ARCHESTRA_AGENTS_INCOMING_EMAIL_PROVIDER=outlook
- Required when:
-
ARCHESTRA_- Mailbox that receives agent email through plus-addressing.AGENTS_ INCOMING_ EMAIL_ OUTLOOK_ MAILBOX_ ADDRESS - Required when:
ARCHESTRA_AGENTS_INCOMING_EMAIL_PROVIDER=outlook - Values: an email address, for example
agents@example.com
- Required when:
-
ARCHESTRA_- Domain used in agent email addresses.AGENTS_ INCOMING_ EMAIL_ OUTLOOK_ EMAIL_ DOMAIN - Default: the domain of
ARCHESTRA_AGENTS_ INCOMING_ EMAIL_ OUTLOOK_ MAILBOX_ ADDRESS
- Default: the domain of
-
ARCHESTRA_- Public URL that receives new-mail notifications. When set, Archestra creates the subscription on startup.AGENTS_ INCOMING_ EMAIL_ OUTLOOK_ WEBHOOK_ URL - Default: unset (create the subscription in Settings → Messaging Channels → Email)
- Values: a URL ending in
/api/webhooks/incoming-email, for examplehttps://archestra.example.com/api/webhooks/incoming-email
ChatOps
The Microsoft Teams, Slack, and Telegram variables apply only on first startup, when no channel settings exist yet. After that, change a channel in Settings → Messaging Channels.
-
ARCHESTRA_- Sends a welcome message to users who are created automatically when they first message an agent.CHATOPS_ SIGNUP_ WELCOME_ ENABLED - Default:
true - Values:
true,false. Withfalse, users are still created. - With SSO configured, the welcome links to sign-in. Without SSO, it is skipped when
ARCHESTRA_orAUTH_ DISABLE_ INVITATIONS ARCHESTRA_isAUTH_ DISABLE_ BASIC_ AUTH true.
- Default:
-
ARCHESTRA_- Maximum number of Slack attachment downloads each backend process handles at once.CHATOPS_ MAX_ CONCURRENT_ FILE_ TRANSFERS - Default:
4 - Lower it on memory-constrained deployments.
- Default:
Microsoft Teams
See Microsoft Teams for setup.
-
ARCHESTRA_- Turns on the Microsoft Teams channel.CHATOPS_ MS_ TEAMS_ ENABLED - Default:
false - Values:
true,false
- Default:
-
ARCHESTRA_- Application (client) ID of the Azure Bot registration.CHATOPS_ MS_ TEAMS_ APP_ ID - Required when:
ARCHESTRA_CHATOPS_MS_TEAMS_ENABLED=true
- Required when:
-
ARCHESTRA_- Client secret of the Azure Bot registration.CHATOPS_ MS_ TEAMS_ APP_ SECRET - Required when:
ARCHESTRA_CHATOPS_MS_TEAMS_ENABLED=true
- Required when:
-
ARCHESTRA_- Microsoft Entra tenant ID of a single-tenant bot.CHATOPS_ MS_ TEAMS_ TENANT_ ID - Default: unset (multi-tenant bot)
-
ARCHESTRA_- Tenant ID for reading thread history and files through Microsoft Graph.CHATOPS_ MS_ TEAMS_ GRAPH_ TENANT_ ID - Default:
ARCHESTRA_CHATOPS_ MS_ TEAMS_ TENANT_ ID
- Default:
-
ARCHESTRA_- Client ID for reading thread history and files through Microsoft Graph.CHATOPS_ MS_ TEAMS_ GRAPH_ CLIENT_ ID - Default:
ARCHESTRA_CHATOPS_ MS_ TEAMS_ APP_ ID
- Default:
-
ARCHESTRA_- Client secret for reading thread history and files through Microsoft Graph.CHATOPS_ MS_ TEAMS_ GRAPH_ CLIENT_ SECRET
Slack
See Slack for setup.
-
ARCHESTRA_- Turns on the Slack channel.CHATOPS_ SLACK_ ENABLED - Default:
false - Values:
true,false
- Default:
-
ARCHESTRA_- How Slack delivers events to Archestra.CHATOPS_ SLACK_ CONNECTION_ MODE - Default:
socket - Values:
socket(no public URL needed),webhook(needs a public URL)
- Default:
-
ARCHESTRA_- Bot User OAuth Token, from the app's OAuth & Permissions page.CHATOPS_ SLACK_ BOT_ TOKEN - Required when:
ARCHESTRA_CHATOPS_SLACK_ENABLED=true - Values: starts with
xoxb-
- Required when:
-
ARCHESTRA_- App-Level Token with theCHATOPS_ SLACK_ APP_ LEVEL_ TOKEN connections:writescope, from the app's Basic Information page.- Required when:
ARCHESTRA_CHATOPS_SLACK_CONNECTION_MODE=socket - Values: starts with
xapp-
- Required when:
-
ARCHESTRA_- Signing secret that verifies webhook requests, from the app's Basic Information page.CHATOPS_ SLACK_ SIGNING_ SECRET - Required when:
ARCHESTRA_CHATOPS_SLACK_CONNECTION_MODE=webhook
- Required when:
-
ARCHESTRA_- Slack App ID, used for direct-message deep links.CHATOPS_ SLACK_ APP_ ID - Default: unset (no deep links)
Telegram
See Telegram for setup. Telegram needs no public URL.
-
ARCHESTRA_- Makes the Telegram channel available.CHATOPS_ TELEGRAM_ ENABLED - Default:
true - Values:
true,false. Withfalse, the channel is hidden and never starts.
- Default:
-
ARCHESTRA_- Bot token from @BotFather.CHATOPS_ TELEGRAM_ BOT_ TOKEN - Default: unset (save the token on the Telegram channel page instead)
- Values:
123456789:ABC...format
Public URL
Microsoft Teams and Slack webhook mode need Archestra reachable from the internet. These variables open an ngrok tunnel to Archestra on startup.
-
ARCHESTRA_- ngrok auth token.NGROK_ AUTH_ TOKEN - Default: unset (no tunnel)
-
ARCHESTRA_- Reserved ngrok domain for a stable public URL.NGROK_ DOMAIN - Default: unset (a new random domain on each restart)
- Set it for Microsoft Teams: its messaging endpoint is registered in Azure and breaks when the domain changes.
Observability
See Observability for metrics, tracing, and dashboards.
-
ARCHESTRA_- OTLP/HTTP endpoint that receives traces and logs.OTEL_ EXPORTER_ OTLP_ ENDPOINT - Default:
http://localhost:4318 - Values: a collector URL. Archestra adds
/v1/tracesfor traces and/v1/logsfor logs.
- Default:
-
ARCHESTRA_- Username for basic authentication to the OTLP endpoint.OTEL_ EXPORTER_ OTLP_ AUTH_ USERNAME - Default: unset. Used only together with
ARCHESTRA_.OTEL_ EXPORTER_ OTLP_ AUTH_ PASSWORD
- Default: unset. Used only together with
-
ARCHESTRA_- Password for basic authentication to the OTLP endpoint.OTEL_ EXPORTER_ OTLP_ AUTH_ PASSWORD - Default: unset. Used only together with
ARCHESTRA_.OTEL_ EXPORTER_ OTLP_ AUTH_ USERNAME
- Default: unset. Used only together with
-
ARCHESTRA_- Bearer token for the OTLP endpoint.OTEL_ EXPORTER_ OTLP_ AUTH_ BEARER - Default: unset
- Takes precedence over basic authentication.
-
ARCHESTRA_- Records prompts, completions, and tool arguments and results in trace spans.OTEL_ CAPTURE_ CONTENT - Default:
true, orfalsewhenARCHESTRA_is setCONTENT_ ENCRYPTION_ SECRET - Values:
true,false - With content encryption on,
truesends that content to your telemetry backend in plaintext and logs a startup warning.
- Default:
-
ARCHESTRA_- Maximum characters of each captured content field. Longer content is truncated and ends withOTEL_ CONTENT_ MAX_ LENGTH ...[truncated].- Default:
10000
- Default:
-
ARCHESTRA_- Fraction of traces to record.OTEL_ TRACES_ SAMPLE_ RATE - Default:
1.0(all traces) - Values:
0–1. Child spans follow their parent's decision.
- Default:
-
ARCHESTRA_- Adds infrastructure spans (HTTP routes and outgoing requests) to traces.OTEL_ VERBOSE_ TRACING - Default:
false(LLM and MCP tool call spans only) - Values:
true,false
- Default:
-
ARCHESTRA_- Port of the Prometheus metrics server, which servesMETRICS_ PORT /metrics.- Default:
9050 - Values:
1–65535
- Default:
-
ARCHESTRA_- Bearer token that clients must send to readMETRICS_ SECRET /metrics.- Default: unset (no authentication)
- Clients send
Authorization: Bearer <token>.
-
ARCHESTRA_- How often theMETRICS_ ACTIVE_ USERS_ REFRESH_ INTERVAL_ MS llm_gauge is recomputed.active_ users - Default:
300000(5 minutes) - Values:
0(off), or30000and above
- Default:
-
ARCHESTRA_- OTLP/HTTP endpoint that receives Real User Monitoring events from the web UI. Setting it turns RUM on.RUM_ EXPORTER_ OTLP_ ENDPOINT - Default: unset (RUM off)
- Requires an Enterprise license. The backend does not start when this is set without one.
-
ARCHESTRA_- Username for basic authentication to the RUM endpoint.RUM_ EXPORTER_ OTLP_ AUTH_ USERNAME - Default: unset. Used only together with
ARCHESTRA_.RUM_ EXPORTER_ OTLP_ AUTH_ PASSWORD
- Default: unset. Used only together with
-
ARCHESTRA_- Password for basic authentication to the RUM endpoint.RUM_ EXPORTER_ OTLP_ AUTH_ PASSWORD - Default: unset. Used only together with
ARCHESTRA_.RUM_ EXPORTER_ OTLP_ AUTH_ USERNAME
- Default: unset. Used only together with
-
ARCHESTRA_- Bearer token for the RUM endpoint.RUM_ EXPORTER_ OTLP_ AUTH_ BEARER - Default: unset
- Takes precedence over basic authentication.
-
ARCHESTRA_- Fraction of user sessions RUM records. Whole sessions are kept or skipped; client errors are always reported.RUM_ SAMPLE_ RATE - Default:
1(all sessions) - Values:
0–1
- Default:
-
ARCHESTRA_- Maximum RUM events held in memory while they wait for export.RUM_ EXPORTER_ MAX_ QUEUE_ SIZE - Default:
2048
- Default:
-
ARCHESTRA_- Maximum RUM events sent in one export request.RUM_ EXPORTER_ MAX_ EXPORT_ BATCH_ SIZE - Default:
512 - Raise it for deployments with thousands of concurrent users.
- Default:
-
ARCHESTRA_- Delay between RUM export requests.RUM_ EXPORTER_ SCHEDULE_ DELAY_ MS - Default:
5000 - Lower it for deployments with thousands of concurrent users.
- Default:
-
ARCHESTRA_- Maximum RUM event batches one user may submit per minute. Batches over the limit are dropped.RUM_ INGEST_ MAX_ BATCHES_ PER_ MINUTE - Default:
120
- Default:
-
ARCHESTRA_- Enables screenshot-related debug logging for browser streaming.BROWSER_ STREAM_ LOG_ SCREENSHOTS - Default:
false - Values:
trueorfalse
- Default:
-
ARCHESTRA_- Enables tab-synchronization debug logging for browser streaming.BROWSER_ STREAM_ LOG_ TAB_ SYNC - Default:
false - Values:
trueorfalse
- Default:
Log Content
Choose whether stored LLM proxy logs, MCP gateway logs, and Guardrails consult records include prompts and tool data.
ARCHESTRA_- What LLM proxy logs, MCP gateway logs, and Guardrails consult records store.LOGS_ CONTENT_ MODE - Default:
full - Values:
fullstores prompts, responses, tool arguments, and tool results.metadata_stores who, when, the model or tool, tokens, cost, and whether the call failed. Any other value stores metadata only.only - Applies to records written after a restart. Stored records keep their content.
- Metadata-only mode also omits captured prompt/response and tool argument/result fields from LLM proxy and MCP tool-call trace spans.
- Default:
Application error logs omit attached SDK request bodies, including those in retry histories. In metadata_ mode, logged errors keep type, status and retry metadata; free-text messages, stacks, attached payloads and raw provider error diagnostics are withheld from stdout and OTLP logs. In full mode, error messages and provider responses can still contain sensitive content.
To disable captured prompt/response and tool argument/result fields on trace spans independently, set ARCHESTRA_ to false. MCP trace error messages can still contain sensitive content.
Data Retention
Retention is an Enterprise feature: the backend does not start when a window is set without an Enterprise license. Each value is a whole number of days; any other value turns that window off.
-
ARCHESTRA_- Days to keep LLM proxy logs and Guardrails consult records.LLM_ LOGS_ RETENTION_ DAYS - Default:
0(keep forever) - Under 32 days logs a startup warning: monthly cost limits count these records, so usage can be under-counted.
- Default:
-
ARCHESTRA_- Days to keep MCP gateway tool call logs.MCP_ LOGS_ RETENTION_ DAYS - Default:
0(keep forever)
- Default:
-
ARCHESTRA_- Days without a new message before a conversation is deleted with its messages, attachments, files, and code sandboxes.CHAT_ CONVERSATIONS_ RETENTION_ DAYS - Default:
0(keep forever)
- Default:
-
ARCHESTRA_- Days to keep audit log records.AUDIT_ LOG_ RETENTION_ DAYS - Default:
0(keep forever)
- Default:
Guardrails
Guardrails are available on every deployment. Enforcement is a separate switch on the Guardrails page and starts off.
-
ARCHESTRA_- Key that signs Guardrails delegation between agents and agent-to-agent messages.OPENAPPA_ OFFER_ SIGNING_ SECRET - Default: Helm generates one and keeps it across upgrades. Without Helm, it derives from
ARCHESTRA_.AUTH_ SESSION_ SECRET - Values: at least 32 characters, the same on every replica. A shorter value stops startup.
- Set it to rotate this key separately from the session secret.
- Default: Helm generates one and keeps it across upgrades. Without Helm, it derives from
-
ARCHESTRA_- Name of the check Archestra posts on the policy repository's pull requests with Git sync, and of the branch ruleset you import to require it.OPENAPPA_ POLICY_ CHECK_ NAME - Default:
Check OpenAPPA Guardrails. - Values: up to 100 characters. After a rename, edit the imported ruleset so it requires the check under the new name.
- Default:
-
ARCHESTRA_- Whether the people who can edit an MCP server change its Guardrails rules themselves, through pull requests on the Git sync repository. See MCP Guardrails Self-Service. Shown read-only under Git sync in Settings → Guardrails.OPENAPPA_ SELF_ SERVICE - Default:
disabled - Values:
disabled,enabled. Other values stop startup. - Later releases make this an editable setting with the same default. While this variable is set they use it instead and lock the setting, so keep it set when you upgrade to keep the same behaviour.
- Default:
-
ARCHESTRA_- The folder beside the policy file that holds one rules file per MCP server, which the policy includes asOPENAPPA_ SELF_ SERVICE_ DIRECTORY <folder>/*.toml. Shown read-only under Git sync in Settings → Guardrails.- Default:
mcp - Values: a folder path such as
mcporrules/servers: no.., no*, not underbatteries/. Other values stop startup.
- Default:
-
ARCHESTRA_- Whether the GitHub App merges each MCP server's rules pull request once its policy check passes, so MCP owners need no access to the policy repository. See Auto-merge. Shown read-only under Git sync in Settings → Guardrails.OPENAPPA_ SELF_ SERVICE_ AUTO_ MERGE - Default:
disabled - Values:
disabled,enabled. Other values stop startup. - Later releases make this an editable setting with the same default. While this variable is set they use it instead and lock the setting, so keep it set when you upgrade to keep the same behaviour.
- Default:
-
ARCHESTRA_- Whether a call or remedy plan waiting for human approval runs anyway, with a yell. Shown read-only under Break the glass in Settings → Guardrails.OPENAPPA_ HUMAN_ APPROVAL_ MODE - Default:
block - Values:
block(wait for a person),unattended(waive in Agent Runtime runs, Scheduled task runs, and clients sendingX-Archestra-Unattended: 1; a remedy plan a workload runs counts too),everywhere. Other values stop startup. - With the default Yell tool setting, each waiver's yell also turns Guardrails off for the rest of that session.
- Later releases make this an editable setting with the same default. While this variable is set they use it instead and lock the setting, so keep it set when you upgrade to keep the same behaviour.
- Default:
-
ARCHESTRA_- Emergency override for soft refusals, including tool calls and results, child returns, runtime exports, peer messages, failed helpers, and fork or compaction admission.OPENAPPA_ SOFT_ BLOCK_ MODE allowreleases the original operation and turns Guardrails off for that session, even at its first refusal and even if yell reporting is disabled or fails. Explicit policyblockedmarks and platform authentication and access checks remain enforced. Shown read-only as Other blocked calls under Break the glass in Settings → Guardrails.- Default:
refuse - Values:
refuse(keep the block),allow(waive it). Other values stop startup. - Later releases make this an editable setting with the same default. While this variable is set they use it instead and lock the setting, so keep it set when you upgrade to keep the same behaviour.
- Default:
-
ARCHESTRA_- Lets agents report confusing blocks with theOPENAPPA_ YELL_ ENABLED yelltool. Reports are stored locally.- Default:
true - Values:
true,false - With reports off, no yell is recorded.
ARCHESTRA_OPENAPPA_SOFT_BLOCK_MODE=allowstill waives soft refusals and turns session enforcement off.
- Default:
-
ARCHESTRA_- Forwards agent reports to the shared OpenAPPA reporting service, independently ofOPENAPPA_ YELL_ FORWARDING_ ENABLED ARCHESTRA_. RequiresANALYTICS ARCHESTRA_.OPENAPPA_ YELL_ ENABLED - Default:
false, including after upgrades. Values:true,false; unset or empty means off, and invalid values stop startup. - Encrypted-chat and automatic client-failure reports stay local. Messages are sent verbatim; exclude secrets and conversation content.
- Default:
-
ARCHESTRA_- PostgreSQL connections each backend process opens for guardrail checks.OPENAPPA_ POSTGRES_ MAX_ CONNECTIONS - Default:
4 - Values:
1–64 - A step that waits more than 30 seconds for a free connection fails.
- Default:
-
ARCHESTRA_- Provider of the model that writes a short summary on each Guardrails approval request.OPENAPPA_ REVIEW_ SUMMARY_ PROVIDER - Default: unset (no summaries)
- Values: a chat provider ID, such as
anthropic,openai, orkimi. Its key must be set in that provider'sARCHESTRA_CHAT_<PROVIDER>_API_KEYvariable. A key saved in Settings is not used. - Set it with
ARCHESTRA_. Setting only one stops startup.OPENAPPA_ REVIEW_ SUMMARY_ MODEL - Summaries are limited to five per user and twenty per organization per minute. Past the limit, the review shows without a summary.
-
ARCHESTRA_- Model name for review summaries, served byOPENAPPA_ REVIEW_ SUMMARY_ MODEL ARCHESTRA_.OPENAPPA_ REVIEW_ SUMMARY_ PROVIDER - Default: unset (summaries disabled)
- Must be set together with
ARCHESTRA_; a partial value stops startup.OPENAPPA_ REVIEW_ SUMMARY_ PROVIDER