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.

Database

• ARCHESTRA_DATABASE_URL - PostgreSQL connection string.

  • Default: the bundled PostgreSQL (Docker quickstart and Helm)
  • Values: postgresql://user:password@host:5432/database
  • Required when you use an external database.

• ARCHESTRA_DATABASE_RUN_MIGRATIONS_ON_STARTUP - Runs database migrations before the backend starts.

  • Default: true
  • Set false only when your deployment pipeline applies migrations before rollout.

• ARCHESTRA_DATABASE_POOL_MAX - Maximum PostgreSQL connections per backend process.

  • Default: 50
  • Values: 1–500
  • In Helm, archestra.database.connectionBudget sizes the pool across all pods. This variable and archestra.database.poolMax override it. See Database Configuration.

• ARCHESTRA_DATABASE_STATEMENT_TIMEOUT_MILLIS - PostgreSQL statement_timeout for every pooled connection, in milliseconds.

  • Default: 30000
  • Values: 0 disables the timeout.
  • Raise it if you run legitimate long queries.

Server and Network

• ARCHESTRA_API_BASE_URL - Public URL of the Archestra API, shown in the connection instructions for the LLM Proxy, MCP Gateway, and A2A Gateway.

  • 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_INTERNAL_API_BASE_URL - URL the backend listens on inside the container. In-cluster workloads use it to reach the backend.

  • 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_AGENT_RUNTIME_PLATFORM_BASE_URL is set.

• ARCHESTRA_FRONTEND_URL - Public URL of the Archestra web app. Setting it restricts CORS and sign-in to the configured origins.

  • 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_PUBLIC_ENDPOINTS_PORT - Extra port that serves only the endpoints meant for the Internet: the Microsoft Teams webhook (/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_TRUST_PROXY - Trusts the 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 example 35.191.0.0/16,130.211.0.0/22
  • Prefer the IP list. With true, any caller can set X-Forwarded-For and pick the IP it is rate-limited and audited under.

• ARCHESTRA_HTTP_KEEP_ALIVE_TIMEOUT_MS - How long the API and web servers keep an idle keep-alive connection open, in milliseconds.

  • 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.

• ARCHESTRA_API_BODY_LIMIT - Maximum HTTP request body size for LLM Proxy and chat requests.

  • Default: 70MB
  • Values: bytes (73400320) or a size with KB, MB, or GB (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_CHAT_ATTACHMENT_STORAGE_BYTES_LIMIT, or for very long conversations.

• ARCHESTRA_PROCESS_TYPE - Which part of the backend this process runs.

  • 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.

General

• ARCHESTRA_BETA - Turns on beta features.

  • Default: false
  • Values: true, false
  • Also turns on ARCHESTRA_KNOWLEDGE_BASE_MFILES_CONNECTOR_ENABLED when it is left blank. Set to false, it stays off.

• ARCHESTRA_QUICKSTART - Runs MCP servers in a small Kubernetes (KinD) cluster inside the Docker container.

  • Default: false
  • Values: true, false
  • Requires the Docker socket mounted into the container. For evaluation only. See Quickstart Deployment.

• ARCHESTRA_ENTERPRISE_LICENSE_ACTIVATED - Activates the enterprise license.

  • 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.

• ARCHESTRA_ENTERPRISE_LICENSE_KNOWLEDGE_BASE_ACTIVATED - Activates the enterprise Knowledge Base features, such as team-scoped connectors.

  • Default: false
  • Values: true, false
  • Instances with fewer than 30 users get these features without it.

• ARCHESTRA_ENTERPRISE_LICENSE_AI_SECURITY_ACTIVATED - Activates the Platform + AI Security tier: the OpenAPPA integration behind Guardrails. Instances with fewer than 30 users get it without this flag.

  • Default: false
  • Values: true, false

• ARCHESTRA_ENTERPRISE_LICENSE_FULL_WHITE_LABELING - Removes the "Powered by Archestra" branding and the community links.

  • Default: false
  • Values: true, false

• ARCHESTRA_LOGGING_LEVEL - Minimum level of log messages.

  • Default: info
  • Values: trace, debug, info, warn, error, fatal

• ARCHESTRA_LOGGING_FORMAT - Format of the logs written to stdout.

  • Default: json. The Docker quickstart uses pretty.
  • Values: json (one JSON object per line), pretty (colorized text)
  • The OTLP log exporter always receives structured records.

• ARCHESTRA_ANALYTICS - Sends product analytics to Archestra, and forwards Guardrails diagnostic reports to the shared OpenAPPA reporting service.

  • Default: on in production builds, including the released Docker images; off in development
  • Values: disabled turns it off. Any other value turns it on.

• ARCHESTRA_ANALYTICS_POSTHOG_KEY - PostHog project key for analytics.

  • Default: Archestra's PostHog project
  • Set it with ARCHESTRA_ANALYTICS_POSTHOG_HOST to send analytics to your own PostHog.

• ARCHESTRA_ANALYTICS_POSTHOG_HOST - PostHog API host for analytics.

  • Default: https://eu.i.posthog.com

• ARCHESTRA_MAINTENANCE_MODE_MESSAGE - Blocks the app for all users with a full-screen message.

  • Default: unset (maintenance mode off)
  • Values: the message text
  • While it is set, the container skips database migrations on startup.

• ARCHESTRA_SITE_NOTIFICATION_MESSAGE - Shows a banner at the top of every page, including the sign-in page. The app stays usable.

  • Default: unset (no banner)
  • Values: Markdown text
  • Users can dismiss the banner. A changed message shows again.

Authentication

• ARCHESTRA_AUTH_ADMIN_EMAIL - Email of the default admin user, created on first startup.

  • Default: admin@example.com

• ARCHESTRA_AUTH_ADMIN_PASSWORD - Password of the default admin user, set on first startup.

  • Default: password
  • Change it for any deployment other people can reach.

• ARCHESTRA_AUTH_ADDITIONAL_TRUSTED_ORIGINS - Extra origins allowed for CORS and sign-in, besides 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_FRONTEND_URL. Add your SSO identity provider and any other URL users open the app on.

• ARCHESTRA_AUTH_COOKIE_DOMAIN - Domain the session cookie is scoped to. Set it when the frontend and backend run on different subdomains.

  • Default: unset (the cookie stays on the exact frontend host)
  • Values: the narrowest domain covering both hosts. For frontend.example.com and backend.example.com, use example.com.
  • The cookie then reaches every subdomain. Give each other Archestra instance on that domain its own ARCHESTRA_AUTH_COOKIE_PREFIX. Otherwise sign-in loops back to the sign-in page.

• ARCHESTRA_AUTH_COOKIE_PREFIX - Prefix of the auth cookie names, for example 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.

• ARCHESTRA_AUTH_DISABLE_BASIC_AUTH - Turns off email and password sign-in. Users sign in only through SSO.

  • Default: false
  • Values: true, false
  • Configure an identity provider before you set it to true.

• ARCHESTRA_AUTH_DISABLE_INVITATIONS - Turns off user invitations in the UI and the API.

  • Default: false
  • Values: true, false
  • Use it when an identity provider provisions users.

• ARCHESTRA_AUTH_DISABLE_IMPERSONATION - Turns off View as user, so nobody can start an impersonated session.

  • Default: false
  • Values: true, false
  • With false, impersonation still requires the member:impersonate permission. See Available Permissions.

• ARCHESTRA_AUTH_DCR_ENABLED - Allows OAuth clients to register themselves (Dynamic Client Registration and CIMD).

  • Default: true
  • Values: true, false
  • With false, only OAuth clients you register can run OAuth flows.

• ARCHESTRA_AUTH_REFRESH_TOKEN_REUSE_GRACE_SECONDS - Window, in seconds, in which a replayed OAuth refresh token gets a fresh token pair instead of revoking the grant.

  • Default: 60
  • Values: 0 or more. 0 treats every replay as reuse.
  • The window lets a client retry after a lost token response.

• ARCHESTRA_AUTH_RATE_LIMIT_DISABLED - Turns off rate limiting on the sign-in and auth endpoints.

  • 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 the Retry-After delay. IP resolution follows ARCHESTRA_TRUST_PROXY.
  • Use it only for load tests or automated test runs.

• ARCHESTRA_AUTH_DEV_AUTO_AUTHENTICATE_EMAIL - Skips the sign-in page in development by signing in as the user with this email.

  • Default: unset
  • Ignored in production builds. The session has that user's normal permissions.

Encryption and Secrets

• ARCHESTRA_AUTH_SESSION_SECRET - Signs session cookies and encrypts JWT signing keys and two-factor secrets.

  • Default: Helm generates one in the <release>-auth Secret under session-secret. Without Helm, it falls back to ARCHESTRA_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.

• ARCHESTRA_SECRETS_ENCRYPTION_SECRET - Encrypts secrets stored in the database, such as API keys and tokens.

  • Default: Helm generates one in the <release>-auth Secret under secrets-encryption-secret. Without Helm, it falls back to ARCHESTRA_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_SECRETS_ENCRYPTION_SECRET_PREVIOUS and restart. See Credentials and Secrets.

• ARCHESTRA_SECRETS_ENCRYPTION_SECRET_PREVIOUS - Previous encryption secret, used on startup to re-encrypt stored secrets under the new one.

  • Default: ARCHESTRA_AUTH_SECRET
  • Unset it once re-encryption completes.

• ARCHESTRA_SECRETS_ACCEPT_NEW_ENCRYPTION_KEY - Lets startup continue with an encryption secret that cannot decrypt the stored secrets.

  • Default: false
  • Values: true, false
  • Set it for one boot, then unset it. Secrets encrypted with the old key stay unreadable. Enter them again.

• ARCHESTRA_AUTH_SECRET - Combined secret used for both ARCHESTRA_AUTH_SESSION_SECRET and ARCHESTRA_SECRETS_ENCRYPTION_SECRET when either is unset.

  • Default: generated on first start. Helm stores it in the <release>-auth Secret; the Docker image saves it to /app/data/.auth_secret.
  • Set the two dedicated secrets instead, so you can rotate them separately.

• ARCHESTRA_CONTENT_ENCRYPTION_SECRET - Turns on encryption at rest for LLM Logs, chat messages, and MCP tool call arguments and results. Requires an enterprise license.

  • 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_CONTENT_ENCRYPTION_SECRET_PREVIOUS - Additional key that decrypts content but never encrypts it.

  • Default: unset
  • Set it during key rotation or a rolling enablement, as Content Encryption at Rest describes. Unset it when re-encryption completes.

• ARCHESTRA_ENCRYPTED_CHAT_ESCROW_PUBLIC_KEY - Turns on encrypted chats. Archestra escrows each chat key to this RSA public key for recovery.

  • 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_SECRETS_MANAGER - Where Archestra stores secrets such as API keys and tokens.

  • Default: DB
  • Values: DB, VAULT, READONLY_VAULT. Both Vault values require an enterprise license.
  • With an invalid Vault configuration or no license, Archestra logs a warning and uses DB. See Credentials and Secrets.

• ARCHESTRA_HASHICORP_VAULT_ADDR - Address of the HashiCorp Vault server.

  • Required when: ARCHESTRA_SECRETS_MANAGER=VAULT or READONLY_VAULT
  • Values: a URL, for example https://vault.example.com:8200

• ARCHESTRA_HASHICORP_VAULT_AUTH_METHOD - How Archestra authenticates to Vault.

  • Default: TOKEN
  • Values: TOKEN, K8S, AWS

• ARCHESTRA_HASHICORP_VAULT_TOKEN - Vault token.

  • Required when: ARCHESTRA_HASHICORP_VAULT_AUTH_METHOD=TOKEN

• ARCHESTRA_HASHICORP_VAULT_K8S_ROLE - Vault role bound to the Archestra Kubernetes service account.

  • Required when: ARCHESTRA_HASHICORP_VAULT_AUTH_METHOD=K8S

• ARCHESTRA_HASHICORP_VAULT_K8S_TOKEN_PATH - Path of the service account token used for Kubernetes auth.

  • Default: /var/run/secrets/kubernetes.io/serviceaccount/token

• ARCHESTRA_HASHICORP_VAULT_K8S_MOUNT_POINT - Mount point of Vault's Kubernetes auth method.

  • Default: kubernetes

• ARCHESTRA_HASHICORP_VAULT_AWS_ROLE - Vault role bound to the AWS IAM principal Archestra runs as.

  • Required when: ARCHESTRA_HASHICORP_VAULT_AUTH_METHOD=AWS

• ARCHESTRA_HASHICORP_VAULT_AWS_MOUNT_POINT - Mount point of Vault's AWS auth method.

  • Default: aws

• ARCHESTRA_HASHICORP_VAULT_AWS_REGION - AWS region used to sign the STS request.

  • Default: us-east-1

• ARCHESTRA_HASHICORP_VAULT_AWS_STS_ENDPOINT - STS endpoint used for AWS auth.

  • Default: https://sts.amazonaws.com

• ARCHESTRA_HASHICORP_VAULT_AWS_IAM_SERVER_ID - Value of the X-Vault-AWS-IAM-Server-ID header, when your Vault role requires one.

  • Default: unset

• ARCHESTRA_HASHICORP_VAULT_KV_VERSION - Version of Vault's KV secrets engine.

  • Default: 2
  • Values: 1, 2

• ARCHESTRA_HASHICORP_VAULT_SECRET_PATH - Path prefix under which Archestra stores its secrets.

  • Default: secret/data/archestra (KV v2) or secret/archestra (KV v1)
  • A secret named github_token is stored at <prefix>/github_token.

• ARCHESTRA_HASHICORP_VAULT_SECRET_METADATA_PATH - Path prefix for KV v2 list and delete operations.

  • Default: ARCHESTRA_HASHICORP_VAULT_SECRET_PATH with /data/ replaced by /metadata/
  • Set it only when your paths do not follow that pattern.

• ARCHESTRA_DATABASE_URL_VAULT_REF - Reads the database connection string from Vault instead of ARCHESTRA_DATABASE_URL.

  • Default: unset
  • Values: path:key, for example secret/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.

OpenAI

• ARCHESTRA_OPENAI_BASE_URL - Base URL for OpenAI API requests.

  • Default: https://api.openai.com/v1

• ARCHESTRA_OPENAI_CODEX_API_BASE_URL - Codex backend that serves ChatGPT-subscription requests.

  • Default: https://chatgpt.com/backend-api/codex

• ARCHESTRA_OPENAI_CODEX_ISSUER - OAuth issuer for the ChatGPT subscription sign-in.

  • Default: https://auth.openai.com

• ARCHESTRA_OPENAI_CODEX_CLIENT_ID - OAuth client ID for the ChatGPT subscription sign-in.

  • Default: the Codex CLI client ID

• ARCHESTRA_OPENAI_CODEX_ORIGINATOR - originator header sent to the Codex backend.

  • Default: archestra
  • Set codex_cli_rs if the Codex backend rejects the default.

Anthropic

• ARCHESTRA_ANTHROPIC_BASE_URL - Base URL for Anthropic API requests.

  • Default: https://api.anthropic.com
  • For Claude on Microsoft Foundry, use https://<resource-name>.services.ai.azure.com/anthropic.

• ARCHESTRA_ANTHROPIC_AZURE_FOUNDRY_ENTRA_ID_ENABLED - Authenticates to Claude on Microsoft Foundry with Microsoft Entra ID instead of an API key.

  • Default: false
  • Values: true, false
  • Requires ARCHESTRA_ANTHROPIC_BASE_URL set to a Foundry /anthropic URL. Credentials come from Azure DefaultAzureCredential.

• ARCHESTRA_ANTHROPIC_VERTEX_AI_PROJECT - Google Cloud project ID that turns on Claude on Vertex AI.

  • Default: unset (Vertex AI off)
  • Credentials come from ARCHESTRA_ANTHROPIC_VERTEX_AI_CREDENTIALS_FILE or Application Default Credentials.
  • Turn on only one keyless Anthropic mode: Vertex AI, Workload Identity Federation, or Foundry Entra ID.

• ARCHESTRA_ANTHROPIC_VERTEX_AI_LOCATION - Vertex AI location for Claude requests.

  • Default: global

• ARCHESTRA_ANTHROPIC_VERTEX_AI_CREDENTIALS_FILE - Path to a Google Cloud service account JSON key for Claude on Vertex AI.

  • Default: unset (uses Application Default Credentials)

• ARCHESTRA_ANTHROPIC_FEDERATION_RULE_ID - Federation rule ID (fdrl_...) for keyless Workload Identity Federation.

  • Default: unset
  • Required with ARCHESTRA_ANTHROPIC_ORGANIZATION_ID, ARCHESTRA_ANTHROPIC_SERVICE_ACCOUNT_ID, and an identity token. If any of them is missing, federation stays off and Archestra logs a warning.
  • Create the rule in the Claude Console under Settings → Workload identity.

• ARCHESTRA_ANTHROPIC_ORGANIZATION_ID - Anthropic organization ID for Workload Identity Federation.

  • 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_ANTHROPIC_IDENTITY_TOKEN_FILE - Path to the OIDC identity token file for Workload Identity Federation, such as a Kubernetes projected service account token.

  • 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_ANTHROPIC_IDENTITY_TOKEN - Inline OIDC identity token for Workload Identity Federation.

  • Default: unset
  • Identity tokens are short-lived. Use this for testing, and the file variant in production.

Google Gemini

• ARCHESTRA_GEMINI_BASE_URL - Base URL for Google AI Studio (Gemini API) requests.

  • Default: https://generativelanguage.googleapis.com
  • Ignored when ARCHESTRA_GEMINI_VERTEX_AI_ENABLED=true.

• ARCHESTRA_GEMINI_VERTEX_AI_ENABLED - Sends Gemini requests to Vertex AI instead of Google AI Studio, with Google Cloud credentials instead of API keys.

  • Default: false
  • Values: true, false
  • See Using Vertex AI.

• ARCHESTRA_GEMINI_VERTEX_AI_PROJECT - Google Cloud project ID for Gemini on Vertex AI.

  • Default: unset
  • Required when: ARCHESTRA_GEMINI_VERTEX_AI_ENABLED=true

• ARCHESTRA_GEMINI_VERTEX_AI_LOCATION - Vertex AI region for Gemini requests.

  • Default: us-central1
  • Values: a Vertex AI location, for example europe-west1 or global
  • Some regions, including us-east1, list an incomplete model catalog. us-central1 and global list the full catalog.

• ARCHESTRA_GEMINI_VERTEX_AI_ALLOW_GLOBAL_ENDPOINT - Sends requests for models that Vertex AI serves only from global, such as Gemini 3 and newer, to the global endpoint.

  • Default: false
  • Values: true, false
  • While false, those models do not appear in the model list. Other models keep using ARCHESTRA_GEMINI_VERTEX_AI_LOCATION.
  • Leave it false when your region is a data residency requirement. Google routes global-endpoint requests to any region.

• ARCHESTRA_GEMINI_VERTEX_AI_CREDENTIALS_FILE - Path to a Google Cloud service account JSON key for Gemini on Vertex AI.

  • Default: unset (uses Application Default Credentials)
  • Needed only outside Google Cloud or without Workload Identity.

Amazon Bedrock

• ARCHESTRA_BEDROCK_BASE_URL - Custom Bedrock runtime endpoint.

  • Default: unset (https://bedrock-runtime.<region>.amazonaws.com)

• ARCHESTRA_BEDROCK_REGION - AWS region for Bedrock requests.

  • Default: the region in ARCHESTRA_BEDROCK_BASE_URL, otherwise us-east-1
  • A region selected on a key overrides this.

• ARCHESTRA_BEDROCK_IAM_AUTH_ENABLED - Authenticates to Bedrock with the AWS credential chain (IRSA, instance profile, or AWS environment variables) instead of an API key.

  • Default: false
  • Values: true, false
  • See IAM Authentication Setup (IRSA).

• ARCHESTRA_BEDROCK_ALLOWED_PROVIDERS - Lists only the Bedrock inference profiles from these model providers.

  • Default: unset (all providers)
  • Values: comma-separated provider prefixes, for example anthropic,amazon

• ARCHESTRA_BEDROCK_ALLOWED_INFERENCE_REGIONS - Lists only the Bedrock inference profiles for these regions.

  • Default: unset (all regions)
  • Values: comma-separated region prefixes, for example us,global

Azure AI Foundry

• ARCHESTRA_AZURE_OPENAI_BASE_URL - Azure AI Foundry endpoint 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 - Azure OpenAI API version for Chat Completions and deployment discovery.

  • Default: 2024-02-01

• ARCHESTRA_AZURE_OPENAI_RESPONSES_API_VERSION - Azure OpenAI API version for Responses API requests.

  • Default: 2025-04-01-preview

• ARCHESTRA_AZURE_OPENAI_ENTRA_ID_ENABLED - Authenticates to Azure AI Foundry with Microsoft Entra ID instead of an API key.

  • Default: false
  • Values: true, false
  • Requires ARCHESTRA_AZURE_OPENAI_BASE_URL. Credentials come from Azure DefaultAzureCredential.

xAI

• ARCHESTRA_XAI_BASE_URL - Base URL for xAI API-key requests.

  • Default: https://api.x.ai/v1

• ARCHESTRA_XAI_SUBSCRIPTION_BASE_URL - Endpoint for SuperGrok subscription requests.

  • Default: https://cli-chat-proxy.grok.com/v1

• ARCHESTRA_XAI_SUBSCRIPTION_ISSUER - OAuth issuer for the SuperGrok sign-in.

  • Default: https://auth.x.ai

• ARCHESTRA_XAI_SUBSCRIPTION_VERIFICATION_ORIGIN - Only browser origin accepted for the SuperGrok sign-in verification page.

  • Default: https://accounts.x.ai

• ARCHESTRA_XAI_SUBSCRIPTION_CLIENT_ID - OAuth client ID for the SuperGrok sign-in.

  • Default: the Grok CLI client ID

• ARCHESTRA_XAI_SUBSCRIPTION_CLIENT_VERSION - Grok CLI version reported to the SuperGrok endpoint.

  • 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_XAI_SUBSCRIPTION_SCOPES - OAuth scopes requested at SuperGrok sign-in.

  • Default: openid profile email offline_access api:access grok-cli:access
  • Values: space-separated scopes. Keep offline_access. Remove grok-cli:access if xAI refuses it for your accounts.

GitHub Copilot

• ARCHESTRA_GITHUB_COPILOT_BASE_URL - Base URL for GitHub Copilot API requests.

  • Default: https://api.githubcopilot.com
  • For GitHub Enterprise, use https://copilot-api.<ghe-domain>.

• ARCHESTRA_GITHUB_COPILOT_TOKEN_EXCHANGE_URL - Endpoint that exchanges a user's GitHub OAuth token for a Copilot API token.

  • Default: https://api.github.com/copilot_internal/v2/token
  • For GitHub Enterprise, use https://copilot-api.<ghe-domain>/copilot_internal/v2/token.

• ARCHESTRA_GITHUB_COPILOT_DEVICE_AUTH_BASE_URL - GitHub host for the Sign in with GitHub device flow.

  • Default: https://github.com

• ARCHESTRA_GITHUB_COPILOT_CLIENT_ID - GitHub App client ID for the Sign in with GitHub device flow.

  • Default: Iv1.b507a08c87ecfe98 (the VS Code Copilot client ID)
  • Set your own GitHub App's client ID if it has Copilot API access.

Microsoft 365 Copilot

• ARCHESTRA_MICROSOFT_365_COPILOT_CLIENT_ID - Application (client) ID of your Entra app registration for Sign in with Microsoft.

  • Default: unset (sign-in unavailable)
  • See Microsoft 365 Copilot for the app registration.

• ARCHESTRA_MICROSOFT_365_COPILOT_TENANT_ID - Entra tenant that users sign in to.

  • Default: organizations (any work or school account)
  • Set your tenant ID to restrict sign-in to one directory.

• ARCHESTRA_MICROSOFT_365_COPILOT_BASE_URL - Microsoft Graph base URL for the Microsoft 365 Copilot Chat API.

  • Default: https://graph.microsoft.com/beta

• ARCHESTRA_MICROSOFT_365_COPILOT_AUTH_BASE_URL - Entra ID host for the sign-in and token endpoints.

  • Default: https://login.microsoftonline.com
  • Change it for a sovereign cloud.

OpenRouter

• ARCHESTRA_OPENROUTER_BASE_URL - Base URL for OpenRouter API requests.

  • Default: https://openrouter.ai/api/v1

• ARCHESTRA_OPENROUTER_REFERER - HTTP-Referer attribution header sent to OpenRouter.

  • Default: https://archestra.ai
  • A client's own header takes precedence.

• ARCHESTRA_OPENROUTER_TITLE - App title attribution header sent to OpenRouter.

  • Default: Archestra
  • A client's own header takes precedence.

• ARCHESTRA_OPENROUTER_CATEGORIES - OpenRouter marketplace categories attribution header.

  • Default: general-chat,personal-agent
  • Values: comma-separated categories

Ollama

• ARCHESTRA_OLLAMA_BASE_URL - Base URL of your Ollama server's OpenAI-compatible API.

  • Default: http://localhost:11434/v1
  • Ollama is always on. See Ollama.

• ARCHESTRA_OLLAMA_NATIVE_BASE_URL - Root URL of your Ollama server for the Ollama (Native) provider, which uses Ollama's /api/chat endpoint.

  • Default: ARCHESTRA_OLLAMA_BASE_URL without the /v1 suffix
  • Set it only when the native endpoint runs on another host. Omit /v1.

Other Providers

• ARCHESTRA_JEV_BASE_URL - Full Jev decisions endpoint. See Jev.

  • Default: https://api.typesafe.ai/v1/systemone

• ARCHESTRA_VLLM_BASE_URL - Base URL of your OpenAI-compatible server (vLLM, llama.cpp, LM Studio, SGLang, TGI, LocalAI).

  • Default: unset (provider off)
  • Values: a URL, for example http://localhost:8000/v1
  • See OpenAI-Compatible Servers.

• ARCHESTRA_ARCHESTRA_BASE_URL - LLM proxy URL of another Archestra instance, for the Archestra provider.

  • Default: unset
  • Set the URL on each key instead. This variable only turns on raw passthrough at the /v1/archestra proxy prefix. See Archestra.

• ARCHESTRA_CEREBRAS_BASE_URL - Base URL for Cerebras API requests.

  • Default: https://api.cerebras.ai/v1

• ARCHESTRA_COHERE_BASE_URL - Base URL for Cohere API requests.

  • Default: https://api.cohere.ai

• ARCHESTRA_DEEPSEEK_BASE_URL - Base URL for DeepSeek API requests.

  • Default: https://api.deepseek.com

• ARCHESTRA_GROQ_BASE_URL - Base URL for Groq API requests.

  • Default: https://api.groq.com/openai/v1

• ARCHESTRA_KIMI_BASE_URL - Base URL for Kimi (Moonshot AI) API requests.

  • Default: https://api.moonshot.ai/v1

• ARCHESTRA_MINIMAX_BASE_URL - Base URL for MiniMax API requests.

  • Default: https://api.minimax.io/v1

• ARCHESTRA_MISTRAL_BASE_URL - Base URL for Mistral AI API requests.

  • Default: https://api.mistral.ai/v1

• ARCHESTRA_PERPLEXITY_BASE_URL - Base URL for Perplexity API requests.

  • Default: https://api.perplexity.ai

• ARCHESTRA_VOYAGE_BASE_URL - Base URL for Voyage AI embedding requests.

  • Default: https://api.voyageai.com/v1

• ARCHESTRA_ZHIPUAI_BASE_URL - Base URL for Zhipu AI API requests.

  • Default: https://api.z.ai/api/paas/v4

LLM Proxy

• ARCHESTRA_LLM_PROXY_USAGE_ACCOUNTING_MODE - Controls settlement of provider billing components, including advisor and compaction inference.

  • 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 Component Cost Accounting.

• ARCHESTRA_LLM_PROXY_MAX_VIRTUAL_KEYS - Maximum number of virtual keys per provider API key.

  • Default: 10
  • See LLM Proxy Authentication.

• ARCHESTRA_LLM_PROXY_VIRTUAL_KEYS_DEFAULT_EXPIRATION_SECONDS - Default lifetime of a new virtual key, in seconds.

  • Default: 2592000 (30 days)
  • Values: 0 (never expires) up to 31536000 (one year); larger values are capped at one year
  • Users can set a different expiration on each key.

• ARCHESTRA_LLM_PROXY_UPSTREAM_TIMEOUT_MS - How long an LLM request waits for response headers or the next stream chunk, in milliseconds.

  • 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_LLM_PROXY_STREAM_KEEPALIVE_INTERVAL_MS - Longest a streaming response stays silent before Archestra sends an SSE keep-alive comment, in milliseconds.

  • Default: 10000 (10 seconds)
  • Values: 0 turns 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.

• ARCHESTRA_LLM_COST_SUBSCRIPTION_AUTODETECT - Records traffic sent with a subscription credential, such as a Claude Pro or Max login, as subscription usage with $0 billed spend.

  • 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.

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_CHAT_ANTHROPIC_API_KEY - Anthropic API key.

  • Default: unset

• ARCHESTRA_CHAT_OPENAI_API_KEY - OpenAI API key.

  • Default: unset

• ARCHESTRA_CHAT_GEMINI_API_KEY - Google AI Studio (Gemini) API key.

  • Default: unset

• ARCHESTRA_CHAT_BEDROCK_API_KEY - Amazon Bedrock API key.

  • Default: unset

• ARCHESTRA_CHAT_AZURE_OPENAI_API_KEY - Azure AI Foundry API key.

  • Default: unset
  • Ignored unless ARCHESTRA_AZURE_OPENAI_BASE_URL is set.

• ARCHESTRA_CHAT_OPENROUTER_API_KEY - OpenRouter API key.

  • Default: unset

• ARCHESTRA_CHAT_CEREBRAS_API_KEY - Cerebras API key.

  • Default: unset

• ARCHESTRA_CHAT_COHERE_API_KEY - Cohere API key.

  • Default: unset

• ARCHESTRA_CHAT_DEEPSEEK_API_KEY - DeepSeek API key.

  • Default: unset

• ARCHESTRA_CHAT_GROQ_API_KEY - Groq API key.

  • Default: unset

• ARCHESTRA_CHAT_KIMI_API_KEY - Kimi (Moonshot AI) API key.

  • Default: unset

• ARCHESTRA_CHAT_MINIMAX_API_KEY - MiniMax API key.

  • Default: unset

• ARCHESTRA_CHAT_MISTRAL_API_KEY - Mistral AI API key.

  • Default: unset

• ARCHESTRA_CHAT_PERPLEXITY_API_KEY - Perplexity API key.

  • Default: unset

• ARCHESTRA_CHAT_VOYAGE_API_KEY - Voyage AI API key, used for knowledge base embeddings.

  • Default: unset

• ARCHESTRA_CHAT_XAI_API_KEY - xAI API key.

  • Default: unset

• ARCHESTRA_CHAT_ZHIPUAI_API_KEY - Zhipu AI API key.

  • Default: unset

• ARCHESTRA_CHAT_VLLM_API_KEY - API key for your OpenAI-compatible server.

  • Default: unset
  • Ignored unless ARCHESTRA_VLLM_BASE_URL is set. Most servers need no key.

• ARCHESTRA_CHAT_OLLAMA_API_KEY - API key for your Ollama server, used by both the Ollama and Ollama (Native) providers.

  • Default: unset
  • Most Ollama servers need no key.

• ARCHESTRA_CHAT_ARCHESTRA_API_KEY - API key for another Archestra instance's LLM proxy.

  • Default: unset
  • Ignored unless ARCHESTRA_ARCHESTRA_BASE_URL is set.

Defaults and Limits

• ARCHESTRA_CHAT_MAX_OUTPUT_TOKENS - Upper limit on output tokens for one agent turn, in chat and in A2A runs.

  • Default: 32768
  • Values: 1 to 1000000
  • A turn uses the lower of this value and the model's own output limit. Models without a known limit use 8192.

• ARCHESTRA_CHAT_RATE_METERED_MAX_OUTPUT_TOKENS - Output token limit for Groq, which charges the requested output budget against a per-minute token allowance.

  • Default: 4096
  • Values: 1 to 1000000
  • On low Groq tiers, a larger request fails with HTTP 413 before generating anything. Raise it on higher tiers.

• ARCHESTRA_CHAT_MODEL_STREAM_IDLE_TIMEOUT_MS - How long a chat model response may go without sending data before Archestra ends the turn, in milliseconds.

  • 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.

• ARCHESTRA_CHAT_ATTACHMENT_STORAGE_BYTES_LIMIT - Largest file a user can attach to a chat message, in bytes.

  • Default: 52428800 (50 MiB)
  • Raise ARCHESTRA_API_BODY_LIMIT with it. Archestra sends attachments base64-encoded, at about 4/3 of their size, in the same request as the conversation.

• ARCHESTRA_CHAT_ATTACHMENT_INLINE_BYTES_LIMIT - Largest attachment sent to the model in a request, in bytes.

  • 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.

• ARCHESTRA_CHAT_SECRET_SCAN_ENABLED - Asks for confirmation before sending a chat message that appears to contain a secret, such as an API key, token, password, or private key.

  • 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.

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_CHAT_ACTIVE_RUN_REPLAY_POLL_INTERVAL_MS - How often a reconnecting client checks for new events of a running chat, in milliseconds.

  • Default: 500

• ARCHESTRA_CHAT_ACTIVE_RUN_STOP_POLL_INTERVAL_MS - Fallback interval for checking whether a running chat was stopped, in milliseconds.

  • Default: 30000

• ARCHESTRA_CHAT_ACTIVE_RUN_NOTIFY_DATABASE_URL - PostgreSQL connection string used only for 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.

• ARCHESTRA_CHAT_ACTIVE_RUN_POLLING_COMPATIBILITY_ENABLED - Turns off the LISTEN/NOTIFY listener, 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.

MCP Gateway

• ARCHESTRA_MCP_GATEWAY_TOOL_CALL_TIMEOUT_MS - Timeout for one upstream MCP tool call made through the gateway, in milliseconds.

  • 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.

• ARCHESTRA_MCP_GATEWAY_STDIO_MAX_MESSAGE_BYTES - Largest reply, in bytes, that Archestra accepts from a stdio MCP server that runs in Kubernetes.

  • 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.

• ARCHESTRA_MCP_GATEWAY_WAKE_WAIT_TIMEOUT_MS - How long a tool call waits for a hibernated MCP server to wake before it returns a retryable "still starting" result, in milliseconds.

  • Default: 30000 (30 seconds)
  • Keep it below your clients' own request timeouts. Otherwise the client aborts first and sees a transport error.

• ARCHESTRA_MCP_GATEWAY_SUBSCRIPTION_MAX_DURATION_MS - Longest one notification stream stays open before the gateway ends it cleanly, in milliseconds.

  • Default: 0 (open until the client disconnects)
  • Values: 0 to 2147483647. Any other value means 0.
  • Set it below your proxy's maximum request duration, which Archestra cannot detect. A GKE Ingress backend without timeoutSec allows 30 seconds.
  • Some clients stop reconnecting after repeated ends and then miss tool-list changes. Test your client first.

MCP Servers

• ARCHESTRA_MCP_OAUTH_ENFORCE_OUTBOUND_VALIDATION - Enables optional hardening for backend requests to upstream MCP OAuth providers, for both remote and self-hosted MCP servers.

  • Default: false. Set exactly true to 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.

• ARCHESTRA_MCP_SERVER_TOOLS_REFRESH_INTERVAL_MINUTES - Re-syncs every installed MCP server's tools and Skills from the live server at this interval, in minutes.

  • Default: unset (no periodic refresh)
  • Values: a positive whole number, for example 30. 0 disables it.
  • To refresh one server on demand, use its Inspector tab in the MCP Registry.

• ARCHESTRA_MCP_CATALOG_API_BASE_URL - API URL for the online MCP server catalog.

  • Default: https://archestra.ai/mcp-catalog/api
  • Set it when your deployment uses a catalog mirror.

MCP Server Orchestrator

• ARCHESTRA_ORCHESTRATOR_LOAD_KUBECONFIG_FROM_CURRENT_CLUSTER - Uses the in-cluster service account to reach Kubernetes.

  • Default: false. The Helm chart sets true.
  • When Archestra runs outside the target cluster, leave it false and set ARCHESTRA_ORCHESTRATOR_KUBECONFIG.

• ARCHESTRA_ORCHESTRATOR_KUBECONFIG - Path to a kubeconfig file mounted in the container.

  • Default: unset (default kubeconfig locations)
  • Example: /etc/archestra/kubeconfig

• ARCHESTRA_ORCHESTRATOR_K8S_NAMESPACE - Namespace that MCP server pods run in.

  • Default: default. The Helm chart sets the release namespace.

• ARCHESTRA_ORCHESTRATOR_ENVIRONMENT_NAMESPACES - Namespaces the platform service account has permissions in, offered as a dropdown in the environment editor.

  • Default: unset (the editor takes free text)
  • Values: comma-separated namespaces, for example staging,production

• ARCHESTRA_ORCHESTRATOR_K8S_CLUSTER_DOMAIN - Cluster DNS domain used to build in-cluster Service addresses.

  • Default: cluster.local

• ARCHESTRA_ORCHESTRATOR_K8S_NODE_HOST - Host Archestra uses to reach NodePort Services when it runs outside the cluster.

  • Default: localhost

• ARCHESTRA_ORCHESTRATOR_MCP_SERVER_BASE_IMAGE - Base image for MCP servers that do not set their own image.

  • Default: europe-west1-docker.pkg.dev/friendly-path-465518-r6/archestra-public/mcp-server-base:<platform version>

• ARCHESTRA_ORCHESTRATOR_MCP_SERVER_CPU_REQUEST - CPU request for each MCP server container.

  • Default: 50m
  • Values: Kubernetes quantity

• ARCHESTRA_ORCHESTRATOR_MCP_SERVER_MEMORY_REQUEST - Memory request for each MCP server container.

  • Default: 128Mi
  • Values: Kubernetes quantity

• ARCHESTRA_ORCHESTRATOR_MCP_SERVER_MEMORY_LIMIT - Memory limit for each MCP server container.

  • Default: 512Mi
  • Values: Kubernetes quantity

• ARCHESTRA_ORCHESTRATOR_MCP_SERVER_EPHEMERAL_STORAGE_REQUEST - Ephemeral-storage request for each MCP server container.

  • Default: 256Mi
  • Values: Kubernetes quantity

• ARCHESTRA_ORCHESTRATOR_MCP_SERVER_EPHEMERAL_STORAGE_LIMIT - Ephemeral-storage limit for each MCP server container.

  • Default: 1Gi
  • Values: Kubernetes quantity

• ARCHESTRA_ORCHESTRATOR_FAILED_POD_REAP_INTERVAL_SECONDS - How often Archestra deletes Failed or Evicted MCP server pods, in seconds.

  • Default: 600
  • Values: a positive whole number. 0 disables it.

• ARCHESTRA_ORCHESTRATOR_MCP_IMAGE_UPDATE_CHECK_INTERVAL_MINUTES - How often Archestra checks whether a running MCP server's :latest or untagged image points to a new build, and rolls the server onto it, in minutes.

  • Default: 15
  • Values: a whole number. 0 turns the check off.
  • Pin an image tag when a server must not change on its own.

• ARCHESTRA_ORCHESTRATOR_MCP_IDLE_HIBERNATION_SECONDS - How long an MCP server pod sits unused before it hibernates, in seconds.

  • Default: 1800 (30 minutes)
  • Values: 0, or 120 and above. Lower values are raised to 120.
  • 0 turns 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.

• ARCHESTRA_ORCHESTRATOR_MCP_IMAGE_PREPULL_ENABLED - Caches MCP server images on every node with a DaemonSet, so hibernated servers wake without pulling from the registry.

  • Default: true
  • Runs only while idle hibernation is on. Set false to keep hibernation without the DaemonSet, which takes a pod slot on every eligible node.

• ARCHESTRA_ORCHESTRATOR_MCP_IMAGE_PREPULL_BOOTSTRAP_IMAGE - Image for the pre-pull DaemonSet's own containers.

  • 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.

• ARCHESTRA_ORCHESTRATOR_MCP_IMAGE_PREPULL_BOOTSTRAP_IMAGE_PULL_SECRETS - Image pull secrets for the bootstrap image.

  • Default: unset
  • Values: comma-separated secret names in the MCP server namespace

• ARCHESTRA_ORCHESTRATOR_MCP_IMAGE_PREPULL_PRIORITY_CLASS_NAME - Priority class for the pre-pull DaemonSet pods.

  • Default: unset (namespace default)
  • Use a low-priority class so caching images never preempts real workloads.

• ARCHESTRA_ORCHESTRATOR_MCP_IMAGE_PREPULL_CPU_REQUEST - CPU request for each pre-pull pod.

  • Default: 10m
  • Values: Kubernetes quantity

• ARCHESTRA_ORCHESTRATOR_MCP_IMAGE_PREPULL_MEMORY_REQUEST - Memory request for each pre-pull pod.

  • Default: 16Mi
  • Values: Kubernetes quantity

• ARCHESTRA_ORCHESTRATOR_MCP_IMAGE_PREPULL_MEMORY_LIMIT - Memory limit for each pre-pull pod.

  • Default: 64Mi
  • Values: Kubernetes quantity

• ARCHESTRA_ORCHESTRATOR_MCP_RUNTIME_OWNER_ROLE - Role in each runtime namespace that Archestra uses to remove the MCP resources it created when the chart is uninstalled.

  • 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_ORCHESTRATOR_HELM_RELEASE_NAME - Release name used to name cluster objects Archestra creates outside the chart, such as the image pre-pull DaemonSet.

  • 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_MCP_SANDBOX_DOMAIN - Wildcard domain that gives each MCP server's apps their own origin.
  • Default: unset (opaque iframe origin)
  • Example: mcp.example.com
  • Requires a wildcard DNS record and TLS certificate for *.mcp.example.com that route to the backend.

A2A Gateway

• ARCHESTRA_A2A_TASK_RETENTION_DAYS - Days a finished A2A task is kept before it is deleted with its artifacts, stream events, and execution transcript.
  • Default: 90
  • Values: a whole number of days. 0 keeps tasks forever.
  • Running tasks are never deleted. The conversation history the task belongs to is kept.

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_CODE_RUNTIME_ENABLED - Enables the per-conversation code sandbox, where agents run shell commands and Python.

  • Default: false. The Docker quickstart image and the Helm chart (archestra.codeRuntime.enabled) default to true.
  • Values: true, false. false turns the sandbox off even when ARCHESTRA_CODE_RUNTIME_DAGGER_RUNNER_HOST is set.
  • Requires the orchestrator. When off, run_command and the other sandbox tools are unavailable and skill scripts cannot run.

• ARCHESTRA_CODE_RUNTIME_DAGGER_RUNNER_HOST - Address of a Dagger engine you run yourself, used instead of an Archestra-managed engine.

  • Default: unset (Archestra manages every engine)
  • Values: a tcp:// or kube-pod:// URL, for example tcp://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_DAGGER_RUNTIME_IMAGE - Base image for sandbox containers.

  • Default: ghcr.io/astral-sh/uv:0.13.4-python3.14-trixie-slim
  • Values: a Debian-based image

• ARCHESTRA_CODE_RUNTIME_BASE_PREBUILT - Skips the per-sandbox package install because ARCHESTRA_DAGGER_RUNTIME_IMAGE is a pre-built sandbox base image.

  • Default: false
  • Values: true, false
  • With true, engines with restricted egress need to reach only the base image's registry, not ghcr.io, Debian mirrors, or PyPI. Sandboxes fail if the image is not the pre-built base.

• ARCHESTRA_DAGGER_RUNTIME_ENGINE_CPU_REQUEST - CPU request for each engine Archestra creates.

  • Default: 2
  • Values: Kubernetes quantity
  • Engine resource settings apply to new engines only. Delete an engine to resize it.

• ARCHESTRA_DAGGER_RUNTIME_ENGINE_MEMORY_REQUEST - Memory request for each engine Archestra creates. It reserves node capacity for the engine and its sandboxes.

  • Default: 6Gi
  • Values: Kubernetes quantity

• ARCHESTRA_DAGGER_RUNTIME_ENGINE_MEMORY_LIMIT - Memory limit for each engine process. It does not cover the sandboxes; see ARCHESTRA_DAGGER_RUNTIME_ENGINE_SANDBOX_MEMORY_MAX.

  • Default: 6Gi
  • Values: Kubernetes quantity

• ARCHESTRA_DAGGER_RUNTIME_ENGINE_CACHE_STORAGE - Size of each engine's build-cache volume.

  • Default: 50Gi
  • Values: Kubernetes quantity

• ARCHESTRA_DAGGER_RUNTIME_ENGINE_SANDBOX_MEMORY_MAX - Total memory all of an engine's sandboxes can use at once. A run that exceeds it is killed; other runs continue.

  • 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.

• ARCHESTRA_DAGGER_RUNTIME_ENGINE_ADDITIONAL_DENIED_CIDRS - Extra IPv4 ranges that sandboxed code cannot reach.

  • 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_DAGGER_RUNTIME_ENGINE_NODE_SELECTOR - Schedules engines onto a dedicated node pool.

  • Default: unset (engines use the platform pod's nodeSelector and tolerations)
  • Values: comma-separated key=value pairs, for example archestra-sandbox=true. Each pair also adds a matching NoSchedule toleration.
  • Applies to new engines only. Delete an engine to move it.

• ARCHESTRA_DAGGER_RUNTIME_MAX_CONCURRENT - Sandbox commands each backend process runs at once.

  • Default: 10
  • Raise it together with the engine's CPU and memory.

• ARCHESTRA_DAGGER_RUNTIME_MAX_QUEUE_LENGTH - Sandbox commands each backend process can queue for a free slot. Beyond this, a command fails with a runtime-at-capacity error.

  • Default: 50

• ARCHESTRA_SKILLS_SANDBOX_CPU_LIMIT_SECONDS - CPU time one sandbox command can use, in seconds.

  • Default: 30

• ARCHESTRA_SKILLS_SANDBOX_MEMORY_LIMIT_BYTES - Memory one sandbox command can use, in bytes.

  • Default: 1073741824 (1 GiB)

• ARCHESTRA_SKILLS_SANDBOX_WALL_CLOCK_SECONDS - Wall-clock time one sandbox command can run, in seconds. Longer timeouts that callers request are lowered to this.

  • Default: 120

• ARCHESTRA_SKILLS_SANDBOX_OUTPUT_BYTES_LIMIT - Output (stdout and stderr) kept per command, in bytes. The rest is truncated.

  • Default: 262144 (256 KiB)

• ARCHESTRA_SKILLS_SANDBOX_ARTIFACT_BYTES_LIMIT - 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.

  • Default: 52428800 (50 MiB), equal to the ARCHESTRA_CHAT_ATTACHMENT_STORAGE_BYTES_LIMIT default
  • Chat still stores a larger attachment; it is not staged in the sandbox.

• ARCHESTRA_DAGGER_RUNTIME_CLI_BIN - Path to the Dagger CLI executable used by the sandbox.

  • 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_AGENT_RUNTIME_IMAGE_REGISTRY - Registry the maintained Claude Code, Codex, OpenCode, Hermes, and OpenClaw images are pulled from.

  • Default: europe-west1-docker.pkg.dev/friendly-path-465518-r6/archestra-public
  • Set it when you mirror these images to a private registry.

• ARCHESTRA_AGENT_RUNTIME_IMAGE_TAG - Tag of the maintained images.

  • Default: latest on stable releases, otherwise the platform version
  • Agents made from a catalog template run this tag, whatever tag was current when they were created. See Upgrades.

• ARCHESTRA_AGENT_RUNTIME_ALLOW_PRIVILEGED - Lets Agent administrators enable privileged runtime pods, which have node-level access.

  • Default: false
  • Values: true, false

• ARCHESTRA_AGENT_RUNTIME_PLATFORM_BASE_URL - URL a runtime pod uses to reach the LLM proxy and MCP gateway. It must be reachable from inside the cluster.

  • Default: ARCHESTRA_INTERNAL_API_BASE_URL
  • When neither is set, runs fail to start.

• ARCHESTRA_AGENT_RUNTIME_DEFAULT_TTL_HOURS - Default maximum lifetime of a run, in hours.

  • Default: 72

• ARCHESTRA_AGENT_RUNTIME_DEFAULT_IDLE_TIMEOUT_MINUTES - Default time an idle run waits for the next instruction before it stops, in minutes.

  • Default: 180
  • Custom images must implement the wait, using the ARCHESTRA_AGENT_RUNTIME_IDLE_TIMEOUT_SECONDS variable passed to the pod.

• ARCHESTRA_AGENT_RUNTIME_CPU_REQUEST - Default CPU request for a run's pod. Runs have no CPU limit.

  • Default: 500m
  • Values: Kubernetes quantity

• ARCHESTRA_AGENT_RUNTIME_MEMORY_REQUEST - Default memory request for a run's pod.

  • Default: 1Gi
  • Values: Kubernetes quantity

• ARCHESTRA_AGENT_RUNTIME_MEMORY_LIMIT - Default memory limit for a run's pod.

  • Default: 4Gi
  • Values: Kubernetes quantity

• ARCHESTRA_AGENT_RUNTIME_WORKSPACE_STORAGE_SIZE - Size of each run's persistent volume, which holds /home/node and, for privileged runs, /var/lib/docker.

  • Default: 20Gi
  • Values: Kubernetes quantity

• ARCHESTRA_AGENT_RUNTIME_WORKSPACE_STORAGE_CLASS - Storage class for run volumes.

  • Default: unset (the cluster's default storage class)
  • Use a CSI-backed class with WaitForFirstConsumer binding when nodes span zones.

• ARCHESTRA_AGENT_RUNTIME_WARM_POOL_SIZE - Spare containers kept ready per group of Agents with matching container settings, so new runs start faster.

  • Default: 0 (warm pools off)
  • Spare containers reserve CPU, memory, and storage while idle. See Agent Runtime.

• ARCHESTRA_AGENT_RUNTIME_WARM_POOL_MAX_POOLS - Maximum number of warm pools. Agents outside them start containers on demand.

  • Default: 4

• ARCHESTRA_AGENT_RUNTIME_NODE_SELECTOR - Schedules runtime pods onto a dedicated node pool.

  • Default: unset (scheduled like any other pod)
  • Values: comma-separated key=value pairs, for example archestra-agent-runtime=true. Each pair also adds a matching NoSchedule toleration.

• ARCHESTRA_AGENT_RUNTIME_PLATFORM_POD_SELECTOR - Label selector for the platform's API pods. Runtime pods may send traffic only to pods that match.

  • Default: archestra.io/platform-api=true (set on API pods by the Helm chart)
  • Values: comma-separated key=value pairs
  • With custom manifests, add this label to the API pods or set a selector that matches them.

• ARCHESTRA_AGENT_RUNTIME_POD_START_TIMEOUT_SECONDS - How long a run's pod can stay pending before the run fails, in seconds.

  • Default: 600
  • Raise it for autoscaled node pools, where node creation and a large image pull can exceed the default.

• ARCHESTRA_AGENT_RUNTIME_RECONCILE_INTERVAL_SECONDS - How often Archestra syncs run state and applies the lifetime and idle limits, in seconds.

  • Default: 30

• ARCHESTRA_AGENT_RUNTIME_TRANSCRIPT_MAX_BYTES - Largest run output kept as a complete transcript, in uncompressed 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.

Knowledge Base

Embedding, reranking, and OCR models for the Knowledge Base are chosen in Settings → Knowledge, not here.

• ARCHESTRA_KNOWLEDGE_BASE_HYBRID_SEARCH_ENABLED - Combines vector search with keyword (BM25) search and merges the results.

  • Default: true
  • Values: true, false (vector search only)

• ARCHESTRA_KNOWLEDGE_BASE_BM25_K1 - Deployment default for BM25 term saturation: how much a repeated word keeps raising a passage's score.

  • Default: 1.2
  • Values: 0–10. 0 scores a word the same whether it appears once or many times.
  • An organization's value under Settings → Knowledge → Search ranking → Advanced options overrides it.

• ARCHESTRA_KNOWLEDGE_BASE_BM25_B - Deployment default for BM25 length normalization: how much long passages are ranked below short ones that match the same words.

  • Default: 0.75
  • Values: 0 (length ignored) to 1 (full normalization)
  • An organization's value under Settings → Knowledge → Search ranking → Advanced options overrides it.

• ARCHESTRA_KNOWLEDGE_BASE_BM25_RECALL_CAP - Maximum number of keyword-matching chunks that BM25 rescores per query.

  • Default: 2000
  • Values: 10–100000
  • Query cost grows with the cap. Raise it when broad queries matter more than latency.

• ARCHESTRA_KNOWLEDGE_BASE_BM25_STATS_REFRESH_INTERVAL_SECONDS - How often the corpus statistics that BM25 ranks with are rebuilt.

  • Default: 3600
  • Values: 60–86400
  • Each rebuild reads every chunk. Keyword search uses a simpler ranking until the first rebuild succeeds.

• ARCHESTRA_KNOWLEDGE_BASE_BM25_STATS_REFRESH_TIMEOUT_MS - How long one BM25 statistics rebuild may run before it is cancelled.

  • Default: 900000 (15 minutes)
  • Values: 30000–21600000
  • Raise it if rebuilds on a very large corpus are cancelled.

• ARCHESTRA_KNOWLEDGE_BASE_SEARCH_STATEMENT_TIMEOUT_MILLIS - Timeout for each knowledge search query (vector and keyword run separately).

  • Default: 8000
  • Values: 0–120000. 0 uses ARCHESTRA_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.

• ARCHESTRA_KNOWLEDGE_BASE_QUOTE_VERIFICATION_ENABLED - 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.

  • Default: true
  • Values: true, false
  • Log-only: it never blocks or changes an answer. Misses are counted in the rag_quote_verification_total metric.

• ARCHESTRA_KNOWLEDGE_BASE_CHUNK_SIZE_TOKENS - Token budget for one chunk, including its title and metadata.

  • Default: 512
  • Values: 128–2048
  • Applies at ingest. Existing chunks keep their size until their connector re-syncs.

• ARCHESTRA_KNOWLEDGE_BASE_CHILD_CHUNK_SIZE_TOKENS - Token budget for child chunks. Search matches the smaller children and returns their parent passage.

  • Default: 0 (off)
  • Values: 0, or 32–2048. Set it below ARCHESTRA_KNOWLEDGE_BASE_CHUNK_SIZE_TOKENS.
  • Stored vectors grow by about the ratio of the two sizes. Applies at ingest.

• ARCHESTRA_KNOWLEDGE_BASE_CONTEXT_EXPANSION_RADIUS - Number of neighboring chunks on each side of a search hit that are returned with it.

  • Default: 1
  • Values: 0–4. 0 returns the hit alone.
  • Each step adds up to two chunks per result, so the model reads more tokens.

• ARCHESTRA_KNOWLEDGE_BASE_CONTEXTUAL_RETRIEVAL_ENABLED - Default contextual retrieval mode for organizations that have not chosen one in Settings → Knowledge.

  • Default: false (no context)
  • Values: true (per-document context), false
  • Per-document context makes one call to the reranking model per changed document.

• ARCHESTRA_KNOWLEDGE_BASE_OCR_MAX_PAGES_PER_DOCUMENT - Maximum number of pages without text that Document OCR transcribes in one PDF.

  • Default: 100
  • Each page is one call to the OCR model. Pages past the limit stay untranscribed. The document shows a partial-extraction warning.

• ARCHESTRA_KNOWLEDGE_BASE_CRAWLER_CHROMIUM_PATH - Path to the Chromium executable that the Web Crawler uses to render JavaScript pages.

  • Default: unset (the default Chromium location)
  • The standard image does not include Chromium. See Web Crawler.

• ARCHESTRA_KNOWLEDGE_BASE_TASK_WORKER_MAX_CONCURRENT - Number of connector sync and embedding tasks each worker runs at once.

  • Default: 2

• ARCHESTRA_KNOWLEDGE_BASE_PERMISSION_SYNC_WORKER_MAX_CONCURRENT - Number of permission sync tasks each worker runs at once.

  • Default: 1
  • Permission sync has its own slots and never waits for content sync.

• ARCHESTRA_KNOWLEDGE_BASE_TASK_WORKER_POLL_INTERVAL_SECONDS - How often a worker checks for new background tasks.

  • Default: 5

• ARCHESTRA_KNOWLEDGE_BASE_TASK_WORKER_SHUTDOWN_TIMEOUT_SECONDS - How long a stopping worker waits for running tasks to finish.

  • Default: 30

• ARCHESTRA_KNOWLEDGE_BASE_CONNECTOR_SYNC_MAX_DURATION_SECONDS - Maximum time one connector sync run works before it saves a checkpoint and continues in a new run.

  • Default: 3300 (55 minutes)
  • Values: seconds. 0 lets a sync finish in one run.

• ARCHESTRA_KNOWLEDGE_BASE_CONNECTOR_RUN_LEASE_TTL_SECONDS - How long a sync run may go without a heartbeat before it is treated as crashed and resumed from its checkpoint.

  • Default: 300
  • Keep it several times ARCHESTRA_KNOWLEDGE_BASE_CONNECTOR_RUN_HEARTBEAT_INTERVAL_SECONDS.

• ARCHESTRA_KNOWLEDGE_BASE_CONNECTOR_RUN_HEARTBEAT_INTERVAL_SECONDS - How often a running sync sends a heartbeat.

  • Default: 90

• ARCHESTRA_KNOWLEDGE_BASE_STALLED_EMBEDDING_AGE_SECONDS - How long a document may wait for embedding before it is queued again.

  • 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.

• ARCHESTRA_KNOWLEDGE_FILES_MAX_UPLOAD_BYTES - Largest single file you can upload to Knowledge Files.

  • Default: 26214400 (25 MiB)

• ARCHESTRA_KNOWLEDGE_FILES_MAX_FILES_PER_INDEX_REQUEST - Maximum number of files one directory selection expands to when you index Knowledge Files.

  • Default: 500

Google Drive

These configure the OAuth client for the Google Drive connector's individual auth mode. Service-account modes do not use them.

• ARCHESTRA_KNOWLEDGE_BASE_GOOGLE_DRIVE_OAUTH_CLIENT_ID - Client ID of the deployment's Google OAuth client.

  • Default: unset (individual mode disabled)
  • Changing it invalidates existing authorizations. Each affected connector must reconnect.

• ARCHESTRA_KNOWLEDGE_BASE_GOOGLE_DRIVE_OAUTH_CLIENT_SECRET - Client secret of the deployment's Google OAuth client.

  • Default: unset (individual mode disabled)
  • Rotating only the secret needs no reconnect.

M-Files

• ARCHESTRA_KNOWLEDGE_BASE_MFILES_CONNECTOR_ENABLED - Turns on the beta M-Files connector.

  • Default: unset (follows ARCHESTRA_BETA)
  • Values: true, false. Existing M-Files connectors keep syncing while it is off.

• ARCHESTRA_KNOWLEDGE_BASE_MFILES_VAF_ADD_ON_PACKAGE_DIR - Directory that serves the VAF Add On package to the install script and the connector form.

  • Default: /app/mfiles-vaf-add-on

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_KNOWLEDGE_BASE_PERFORCE_SHIM_IMAGE - Image of the pod that runs p4 for permission sync.

  • Default: europe-west1-docker.pkg.dev/friendly-path-465518-r6/archestra-public/p4-shim:<platform version>

• ARCHESTRA_KNOWLEDGE_BASE_PERFORCE_P4_URL_AMD64 - Download URL of the p4 binary for x86-64 nodes.

  • Default: https://cdist2.perforce.com/perforce/r25.2/bin.linux26x86_64/p4

• ARCHESTRA_KNOWLEDGE_BASE_PERFORCE_P4_SHA256_AMD64 - Expected SHA-256 of the x86-64 p4 binary. A download that does not match is rejected.

  • Default: the checksum of the r25.2 build

• ARCHESTRA_KNOWLEDGE_BASE_PERFORCE_P4_URL_ARM64 - Download URL of the p4 binary for ARM64 nodes.

  • Default: https://cdist2.perforce.com/perforce/r25.2/bin.linux26aarch64/p4

• ARCHESTRA_KNOWLEDGE_BASE_PERFORCE_P4_SHA256_ARM64 - Expected SHA-256 of the ARM64 p4 binary. A download that does not match is rejected.

  • Default: the checksum of the r25.2 build

File Storage

A change of ARCHESTRA_FILE_STORAGE_PROVIDER applies to new files only. Existing files stay readable where they were written.

• ARCHESTRA_FILE_STORAGE_PROVIDER - Storage backend for My Files contents.

  • Default: db
  • Values: db (PostgreSQL), filesystem (a mounted volume), s3 (an S3-compatible object store)

• ARCHESTRA_FILE_STORAGE_FILESYSTEM_ROOT - Absolute path of the directory that stores files, for example a persistent volume mount.

  • Required when: ARCHESTRA_FILE_STORAGE_PROVIDER=filesystem
  • Example: /var/archestra/files

• ARCHESTRA_FILE_STORAGE_S3_BUCKET - Bucket that stores files.

  • Required when: ARCHESTRA_FILE_STORAGE_PROVIDER=s3

• ARCHESTRA_FILE_STORAGE_S3_REGION - Region of the bucket.

  • Default: us-east-1

• ARCHESTRA_FILE_STORAGE_S3_ENDPOINT - Endpoint of an S3-compatible store such as MinIO or Cloudflare R2.

  • Default: unset (AWS S3)
  • Example: http://minio:9000

• ARCHESTRA_FILE_STORAGE_S3_FORCE_PATH_STYLE - Uses path-style bucket addressing instead of virtual-hosted style.

  • Default: false
  • Values: true, false
  • MinIO requires true.

• ARCHESTRA_FILE_STORAGE_S3_ACCESS_KEY_ID - Access key ID for the bucket.

  • 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_FILE_STORAGE_S3_SECRET_ACCESS_KEY - Secret access key for the bucket.

  • Default: unset
  • Startup fails if it is set without ARCHESTRA_FILE_STORAGE_S3_ACCESS_KEY_ID.

• ARCHESTRA_FILE_STORAGE_S3_KEY_PREFIX - Folder inside the bucket that stores files.

  • Default: unset (bucket root)
  • Example: archestra-prod/
  • To share one bucket between instances, give each its own prefix.

Skills Marketplace

• ARCHESTRA_GIT_BINARY_PATH - Path to the git binary that serves marketplace clones.

  • Default: git

• ARCHESTRA_SKILL_MARKETPLACE_CACHE_DIR - Directory that caches the marketplace git repositories.

  • Default: ~/.archestra/skill-marketplace-cache
  • Put it on a persistent volume in production.

Incoming Email

These variables connect an Outlook mailbox so people can email agents.

• ARCHESTRA_AGENTS_INCOMING_EMAIL_PROVIDER - Provider of the agent mailbox.

  • Default: unset (incoming email off)
  • Values: outlook

• ARCHESTRA_AGENTS_INCOMING_EMAIL_OUTLOOK_TENANT_ID - Microsoft Entra tenant ID of the app registration that reads the mailbox.

  • Required when: ARCHESTRA_AGENTS_INCOMING_EMAIL_PROVIDER=outlook

• ARCHESTRA_AGENTS_INCOMING_EMAIL_OUTLOOK_CLIENT_ID - Application (client) ID of that app registration.

  • Required when: ARCHESTRA_AGENTS_INCOMING_EMAIL_PROVIDER=outlook

• ARCHESTRA_AGENTS_INCOMING_EMAIL_OUTLOOK_CLIENT_SECRET - Client secret of that app registration.

  • Required when: ARCHESTRA_AGENTS_INCOMING_EMAIL_PROVIDER=outlook

• ARCHESTRA_AGENTS_INCOMING_EMAIL_OUTLOOK_MAILBOX_ADDRESS - Mailbox that receives agent email through plus-addressing.

  • Required when: ARCHESTRA_AGENTS_INCOMING_EMAIL_PROVIDER=outlook
  • Values: an email address, for example agents@example.com

• ARCHESTRA_AGENTS_INCOMING_EMAIL_OUTLOOK_EMAIL_DOMAIN - Domain used in agent email addresses.

  • Default: the domain of ARCHESTRA_AGENTS_INCOMING_EMAIL_OUTLOOK_MAILBOX_ADDRESS

• ARCHESTRA_AGENTS_INCOMING_EMAIL_OUTLOOK_WEBHOOK_URL - Public URL that receives new-mail notifications. When set, Archestra creates the subscription on startup.

  • Default: unset (create the subscription in Settings → Messaging Channels → Email)
  • Values: a URL ending in /api/webhooks/incoming-email, for example https://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_CHATOPS_SIGNUP_WELCOME_ENABLED - Sends a welcome message to users who are created automatically when they first message an agent.

  • Default: true
  • Values: true, false. With false, users are still created.
  • With SSO configured, the welcome links to sign-in. Without SSO, it is skipped when ARCHESTRA_AUTH_DISABLE_INVITATIONS or ARCHESTRA_AUTH_DISABLE_BASIC_AUTH is true.

• ARCHESTRA_CHATOPS_MAX_CONCURRENT_FILE_TRANSFERS - Maximum number of Slack attachment downloads each backend process handles at once.

  • Default: 4
  • Lower it on memory-constrained deployments.

Microsoft Teams

See Microsoft Teams for setup.

• ARCHESTRA_CHATOPS_MS_TEAMS_ENABLED - Turns on the Microsoft Teams channel.

  • Default: false
  • Values: true, false

• ARCHESTRA_CHATOPS_MS_TEAMS_APP_ID - Application (client) ID of the Azure Bot registration.

  • Required when: ARCHESTRA_CHATOPS_MS_TEAMS_ENABLED=true

• ARCHESTRA_CHATOPS_MS_TEAMS_APP_SECRET - Client secret of the Azure Bot registration.

  • Required when: ARCHESTRA_CHATOPS_MS_TEAMS_ENABLED=true

• ARCHESTRA_CHATOPS_MS_TEAMS_TENANT_ID - Microsoft Entra tenant ID of a single-tenant bot.

  • Default: unset (multi-tenant bot)

• ARCHESTRA_CHATOPS_MS_TEAMS_GRAPH_TENANT_ID - Tenant ID for reading thread history and files through Microsoft Graph.

  • Default: ARCHESTRA_CHATOPS_MS_TEAMS_TENANT_ID

• ARCHESTRA_CHATOPS_MS_TEAMS_GRAPH_CLIENT_ID - Client ID for reading thread history and files through Microsoft Graph.

  • Default: ARCHESTRA_CHATOPS_MS_TEAMS_APP_ID

• ARCHESTRA_CHATOPS_MS_TEAMS_GRAPH_CLIENT_SECRET - Client secret for reading thread history and files through Microsoft Graph.

  • Default: ARCHESTRA_CHATOPS_MS_TEAMS_APP_SECRET

Slack

See Slack for setup.

• ARCHESTRA_CHATOPS_SLACK_ENABLED - Turns on the Slack channel.

  • Default: false
  • Values: true, false

• ARCHESTRA_CHATOPS_SLACK_CONNECTION_MODE - How Slack delivers events to Archestra.

  • Default: socket
  • Values: socket (no public URL needed), webhook (needs a public URL)

• ARCHESTRA_CHATOPS_SLACK_BOT_TOKEN - Bot User OAuth Token, from the app's OAuth & Permissions page.

  • Required when: ARCHESTRA_CHATOPS_SLACK_ENABLED=true
  • Values: starts with xoxb-

• ARCHESTRA_CHATOPS_SLACK_APP_LEVEL_TOKEN - App-Level Token with the connections:write scope, from the app's Basic Information page.

  • Required when: ARCHESTRA_CHATOPS_SLACK_CONNECTION_MODE=socket
  • Values: starts with xapp-

• ARCHESTRA_CHATOPS_SLACK_SIGNING_SECRET - Signing secret that verifies webhook requests, from the app's Basic Information page.

  • Required when: ARCHESTRA_CHATOPS_SLACK_CONNECTION_MODE=webhook

• ARCHESTRA_CHATOPS_SLACK_APP_ID - Slack App ID, used for direct-message deep links.

  • Default: unset (no deep links)

Telegram

See Telegram for setup. Telegram needs no public URL.

• ARCHESTRA_CHATOPS_TELEGRAM_ENABLED - Makes the Telegram channel available.

  • Default: true
  • Values: true, false. With false, the channel is hidden and never starts.

• ARCHESTRA_CHATOPS_TELEGRAM_BOT_TOKEN - Bot token from @BotFather.

  • 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_NGROK_DOMAIN - Reserved ngrok domain for a stable public URL.

  • 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_OTEL_EXPORTER_OTLP_ENDPOINT - OTLP/HTTP endpoint that receives traces and logs.

  • Default: http://localhost:4318
  • Values: a collector URL. Archestra adds /v1/traces for traces and /v1/logs for logs.

• ARCHESTRA_OTEL_EXPORTER_OTLP_AUTH_USERNAME - Username for basic authentication to the OTLP endpoint.

  • Default: unset. Used only together with ARCHESTRA_OTEL_EXPORTER_OTLP_AUTH_PASSWORD.

• ARCHESTRA_OTEL_EXPORTER_OTLP_AUTH_PASSWORD - Password for basic authentication to the OTLP endpoint.

  • Default: unset. Used only together with ARCHESTRA_OTEL_EXPORTER_OTLP_AUTH_USERNAME.

• ARCHESTRA_OTEL_EXPORTER_OTLP_AUTH_BEARER - Bearer token for the OTLP endpoint.

  • Default: unset
  • Takes precedence over basic authentication.

• ARCHESTRA_OTEL_CAPTURE_CONTENT - Records prompts, completions, and tool arguments and results in trace spans.

  • Default: true, or false when ARCHESTRA_CONTENT_ENCRYPTION_SECRET is set
  • Values: true, false
  • With content encryption on, true sends that content to your telemetry backend in plaintext and logs a startup warning.

• ARCHESTRA_OTEL_CONTENT_MAX_LENGTH - Maximum characters of each captured content field. Longer content is truncated and ends with ...[truncated].

  • Default: 10000

• ARCHESTRA_OTEL_TRACES_SAMPLE_RATE - Fraction of traces to record.

  • Default: 1.0 (all traces)
  • Values: 0–1. Child spans follow their parent's decision.

• ARCHESTRA_OTEL_VERBOSE_TRACING - Adds infrastructure spans (HTTP routes and outgoing requests) to traces.

  • Default: false (LLM and MCP tool call spans only)
  • Values: true, false

• ARCHESTRA_METRICS_PORT - Port of the Prometheus metrics server, which serves /metrics.

  • Default: 9050
  • Values: 1–65535

• ARCHESTRA_METRICS_SECRET - Bearer token that clients must send to read /metrics.

  • Default: unset (no authentication)
  • Clients send Authorization: Bearer <token>.

• ARCHESTRA_METRICS_ACTIVE_USERS_REFRESH_INTERVAL_MS - How often the llm_active_users gauge is recomputed.

  • Default: 300000 (5 minutes)
  • Values: 0 (off), or 30000 and above

• ARCHESTRA_RUM_EXPORTER_OTLP_ENDPOINT - OTLP/HTTP endpoint that receives Real User Monitoring events from the web UI. Setting it turns RUM on.

  • Default: unset (RUM off)
  • Requires an Enterprise license. The backend does not start when this is set without one.

• ARCHESTRA_RUM_EXPORTER_OTLP_AUTH_USERNAME - Username for basic authentication to the RUM endpoint.

  • Default: unset. Used only together with ARCHESTRA_RUM_EXPORTER_OTLP_AUTH_PASSWORD.

• ARCHESTRA_RUM_EXPORTER_OTLP_AUTH_PASSWORD - Password for basic authentication to the RUM endpoint.

  • Default: unset. Used only together with ARCHESTRA_RUM_EXPORTER_OTLP_AUTH_USERNAME.

• ARCHESTRA_RUM_EXPORTER_OTLP_AUTH_BEARER - Bearer token for the RUM endpoint.

  • Default: unset
  • Takes precedence over basic authentication.

• ARCHESTRA_RUM_SAMPLE_RATE - Fraction of user sessions RUM records. Whole sessions are kept or skipped; client errors are always reported.

  • Default: 1 (all sessions)
  • Values: 0–1

• ARCHESTRA_RUM_EXPORTER_MAX_QUEUE_SIZE - Maximum RUM events held in memory while they wait for export.

  • Default: 2048

• ARCHESTRA_RUM_EXPORTER_MAX_EXPORT_BATCH_SIZE - Maximum RUM events sent in one export request.

  • Default: 512
  • Raise it for deployments with thousands of concurrent users.

• ARCHESTRA_RUM_EXPORTER_SCHEDULE_DELAY_MS - Delay between RUM export requests.

  • Default: 5000
  • Lower it for deployments with thousands of concurrent users.

• ARCHESTRA_RUM_INGEST_MAX_BATCHES_PER_MINUTE - Maximum RUM event batches one user may submit per minute. Batches over the limit are dropped.

  • Default: 120

• ARCHESTRA_BROWSER_STREAM_LOG_SCREENSHOTS - Enables screenshot-related debug logging for browser streaming.

  • Default: false
  • Values: true or false

• ARCHESTRA_BROWSER_STREAM_LOG_TAB_SYNC - Enables tab-synchronization debug logging for browser streaming.

  • Default: false
  • Values: true or false

Log Content

Keep prompts and tool data out of the logs while usage, cost, and the audit trail stay complete.

• ARCHESTRA_LOGS_CONTENT_MODE - What LLM proxy logs, MCP gateway logs, and Guardrails consult records store.
  • Default: full
  • Values: full stores prompts, responses, tool arguments, and tool results. metadata_only stores who, when, the model or tool, tokens, cost, and whether the call failed. Any other value stores metadata only.
  • Applies to records written after a restart. Stored records keep their 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_LLM_LOGS_RETENTION_DAYS - Days to keep LLM proxy logs and Guardrails consult records.

  • Default: 0 (keep forever)
  • Under 32 days logs a startup warning: monthly cost limits count these records, so usage can be under-counted.

• ARCHESTRA_MCP_LOGS_RETENTION_DAYS - Days to keep MCP gateway tool call logs.

  • Default: 0 (keep forever)

• ARCHESTRA_CHAT_CONVERSATIONS_RETENTION_DAYS - Days without a new message before a conversation is deleted with its messages, attachments, files, and code sandboxes.

  • Default: 0 (keep forever)

• ARCHESTRA_AUDIT_LOG_RETENTION_DAYS - Days to keep audit log records.

  • Default: 0 (keep forever)

Guardrails

Guardrails are available on every deployment. Enforcement is a separate switch on the Guardrails page and starts off.

• ARCHESTRA_OPENAPPA_OFFER_SIGNING_SECRET - Key that signs Guardrails delegation between agents and agent-to-agent messages.

  • 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.

• ARCHESTRA_OPENAPPA_YELL_ENABLED - Lets agents report confusing blocks with the yell tool. Reports are stored locally. They also go to the shared OpenAPPA reporting service when ARCHESTRA_ANALYTICS is enabled.

  • Default: true
  • Values: true, false

• ARCHESTRA_OPENAPPA_POSTGRES_MAX_CONNECTIONS - PostgreSQL connections each backend process opens for guardrail checks.

  • Default: 4
  • Values: 1–64
  • A step that waits more than 30 seconds for a free connection fails.

• ARCHESTRA_OPENAPPA_REVIEW_SUMMARY_PROVIDER - Provider of the model that writes a short summary on each Guardrails approval request.

  • Default: unset (no summaries)
  • Values: a chat provider ID, such as anthropic, openai, or kimi. Its key must be set in that provider's ARCHESTRA_CHAT_<PROVIDER>_API_KEY variable. A key saved in Settings is not used.
  • Set it with ARCHESTRA_OPENAPPA_REVIEW_SUMMARY_MODEL. Setting only one stops startup.
  • Summaries are limited to five per user and twenty per organization per minute. Past the limit, the review shows without a summary.

• ARCHESTRA_OPENAPPA_REVIEW_SUMMARY_MODEL - Model name for review summaries, served by ARCHESTRA_OPENAPPA_REVIEW_SUMMARY_PROVIDER.

  • Default: unset (summaries disabled)
  • Must be set together with ARCHESTRA_OPENAPPA_REVIEW_SUMMARY_PROVIDER; a partial value stops startup.