AdminConfiguration

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 Helm for Kubernetes installation.

Shutdown

Give long model requests and MCP tool calls time to finish when a replica stops.

  • ARCHESTRA_SERVER_REQUEST_DRAIN_SECONDS — Seconds after a stop signal for admitted requests, handlers and background persistence to finish. Default 60; integer 1–86400.

  • ARCHESTRA_SERVER_SHUTDOWN_CLEANUP_SECONDS — Extra time for persistence, dependency cleanup and telemetry. Default 20; integer 5–86400. The backend deadline is max(request drain, worker task shutdown timeout) + cleanup. The unified container gives the backend another 10 seconds before forcing it to stop.

  • ARCHESTRA_SERVER_POD_GRACE_SECONDS — Injected by Helm from the rendered pod grace period. At server startup, checks the resolved environment values, including Secret and ConfigMap imports, against 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_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 Connection Capacity.
  • 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.
  • ARCHESTRA_DATABASE_IAM_AUTH_ENABLED - Signs a fresh 15-minute Amazon RDS or Aurora IAM token for each new PostgreSQL connection in the query pool, cache pool, LISTEN/NOTIFY client, and migration Job, keeping TLS certificate and hostname verification with the RDS CA bundle.

    • Default: false
    • Values: true, false
    • In Helm, set archestra.database.iamAuth.enabled: true. See Amazon RDS and Aurora.
  • ARCHESTRA_DATABASE_ENTRA_AUTH_ENABLED - Signs in to Azure Database for PostgreSQL flexible server with a Microsoft Entra ID access token for the pod's Azure identity on each new PostgreSQL connection in the query pool, cache pool, LISTEN/NOTIFY client, and migration Job, keeping TLS certificate and hostname verification.

  • ARCHESTRA_DATABASE_AWS_REGION - AWS region used to sign RDS IAM database authentication tokens.

    • Default: derived from an *.rds.amazonaws.com database hostname, falling back to AWS_REGION or AWS_DEFAULT_REGION
    • Set it when connecting to RDS or Aurora through a custom DNS name without AWS_REGION set.

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.

  • 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.
    • See Public Webhook Endpoints.
  • 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 10.0.0.0/23,10.0.2.2
    • Prefer the IP list. With true, any caller can set X-Forwarded-For and 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.
  • 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 Streaming 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_RELEASE_IMAGE_DIGESTS - 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. To check their signatures, or admit only those images, see Verify Releases.

  • 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 Run Archestra.
  • ARCHESTRA_NODE_SOURCE_MAPS - Shows TypeScript files and lines in the stack traces the backend logs.

    • Default: true, or false with ARCHESTRA_QUICKSTART
    • Values: true, false
    • Costs about 250 MB of backend memory. Error reports show source lines either way.
  • ARCHESTRA_ENTERPRISE_LICENSE_ACTIVATED - Activates the enterprise license.

    • Default: false
    • Values: true, false
    • See Pricing 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_ANALYTICS off unless that variable is set.
  • 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 usage analytics and telemetry to Archestra. Guardrails diagnostic forwarding has a separate opt-in.

    • Default: on in production builds, including the released Docker images. Off in development, and off when ARCHESTRA_ENTERPRISE_LICENSE_ACTIVATED is true.
    • Values: disabled turns it off. Any other value turns it on.
  • ARCHESTRA_ANALYTICS_POSTHOG_KEY - PostHog project key for analytics.

  • 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. It applies only when the admin is created; to change the password later, see Default Admin Password.
  • 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_SERVICE_ACCOUNT_BOOTSTRAP - Service accounts and federated credentials to create on startup, as a JSON array. Requires an Enterprise license.

    • Default: unset (nothing is created)
    • With the Helm chart, set archestra.bootstrap.serviceAccounts instead. See Declare Accounts in the Helm Chart.
    • Only missing accounts and credentials are created, matched by name. A malformed value stops startup.
  • 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.

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

  • 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, auth, and MCP gateway endpoints. Credentials and permissions are still checked.

    • 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.
    • If the MCP gateway returns HTTP 429 or 503, wait before retrying and follow Retry-After when provided.
    • 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.
  • ARCHESTRA_AGENT_IDENTITY_SPIFFE_TRUST_DOMAIN - SPIFFE trust domain of agents' SPIFFE IDs (spiffe://<trust domain>/agent/<agent ID>). See SPIFFE Agent Identities.

    • Default: the hostname of ARCHESTRA_FRONTEND_URL
    • Values: lowercase letters, digits, dots, dashes, and underscores
    • Changing it changes every agent's SPIFFE ID, so update the policies that name them.

Encryption and Secrets

To change any of these secrets, follow Secret Rotation.

  • 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 and makes users with two-factor authentication set up their authenticator again. See Session Secret.
  • ARCHESTRA_SECRETS_ENCRYPTION_SECRET - Encrypts secrets stored in the database, such as API keys and tokens.

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

  • 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. To change it safely, see Legacy Combined Secret.

    • 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.
    • Once both are set, Archestra uses this secret only as ARCHESTRA_SECRETS_ENCRYPTION_SECRET_PREVIOUS when that is unset.
  • 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.

  • ARCHESTRA_SECRETS_MANAGER - Where Archestra stores secrets such as API keys and tokens.

    • Default: DB
    • Values: DB, VAULT. Vault requires 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.

  • ARCHESTRA_HASHICORP_VAULT_AUTH_METHOD - How Archestra authenticates to Vault.

    • Default: TOKEN
    • Values: TOKEN, K8S, AWS
  • ARCHESTRA_HASHICORP_VAULT_TOKEN - Vault token.

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

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

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

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_LLM_SYSTEM_KEYS_AUTO_DELETE_ENABLED - 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.
    • Default: true
    • Values: true, false
    • Set it to false on 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 to true for one restart to remove it.

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.

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

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

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

  • 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 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 use global. Other models keep using ARCHESTRA_GEMINI_VERTEX_AI_LOCATION.
    • A configured location of global already sends all Gemini requests there, regardless of this setting.
    • 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.

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.

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

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

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.

  • 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_AUTO_ROUTING_SCORER_TIMEOUT_MS - How long the session scorer may take before the router falls back to the normal model.

    • Default: 2000
  • ARCHESTRA_AUTO_ROUTING_MIN_SESSIONS - Finished sessions needed before auto routing publishes a plan instead of using the normal model. Scored past sessions count toward it.

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

  • 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_KIMI_CODE_BASE_URL - Base URL for Kimi Code API requests. Set it to https://api.kimi.com/coding/v1 to use the endpoint for China.

    • Default: https://api.kimi.ai/coding/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_MAX_VIRTUAL_KEYS - Maximum number of virtual keys per provider API key.

  • 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.
    • 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.
    • Model pools wait until a member is selected so failover and final pool headers remain accurate. Buffered policy responses keep their existing commit behavior. Other transports keep their existing behavior until the first client event.
  • 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.

  • 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_KIMI_CODE_API_KEY - Kimi Code membership 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.

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

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.
    • In Chat, Nova 2 Lite High reasoning omits the automatic output cap. Setting this variable explicitly, even to 32768, or setting a custom model output limit blocks High; use Low or Medium instead.
  • 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, A2A task streams and LLM proxy settings stay in sync across replicas through PostgreSQL LISTEN/NOTIFY, with polling as a fallback. While notifications arrive, the LLM proxy keeps gateway, credential and limit settings in memory, so a revoked key or a changed limit reaches every replica within seconds. 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 and the LLM proxy reads its settings from the database on every request.

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

  • ARCHESTRA_MCP_BRIDGE_POLL_MAX_WAIT_MS - Longest time Archestra holds one poll of a user's MCP bridge open while it has no work, in milliseconds.

    • Default: 8000 (8 seconds)
    • Keep it below the request timeout of the load balancer in front of the API. Otherwise the load balancer ends every idle poll with an error.
  • ARCHESTRA_MCP_BRIDGE_AUTO_UPDATE_ENABLED - Lets the MCP bridge on a user's computer update by itself when Archestra serves another version. Set it to false to make each user run archestra update.

    • Default: true
    • On macOS and Linux the MCP bridge does not update by itself. The user runs archestra update.
  • ARCHESTRA_CLI_DIR - Folder that holds the archestra programs that the Device tab of Personal Settings offers for download. Users run archestra bridge start to start the MCP bridge.

    • Default: /app/archestra-cli, where the platform image keeps the programs. If the folder does not exist, the download answers "not found".
    • One file per system and CPU, named archestra-<system>-<cpu>: archestra-darwin-arm64, archestra-darwin-x86_64, archestra-linux-x86_64, archestra-linux-arm64, archestra-windows-x86_64.exe, archestra-windows-arm64.exe. A system with no file gets no download.
    • manifest.json in the folder holds the version of the programs, as { "version": "0.2.0" }. The Device tab of Personal Settings shows it when a device needs an update.

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_ENABLED - Set to false to 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 from archestra.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.
  • ARCHESTRA_ORCHESTRATOR_LOAD_KUBECONFIG_FROM_CURRENT_CLUSTER - Uses the in-cluster service account to reach Kubernetes.

  • 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 servers, Agent Runtime sessions, and code sandbox engines run in, unless an environment names another one.

    • Default: default. The Helm chart sets archestra.orchestrator.kubernetes.namespace, or the release namespace.
    • To run them in a namespace of their own, follow Cluster Security.
  • 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_RETIRED_NAMESPACES - Namespaces workloads ran in before a namespace change. The platform cleans up what it left there.

    • Default: unset
    • Values: comma-separated namespaces, for example archestra-mcp-old. A namespace that is still in use is ignored.
    • Removes MCP servers, warm pools, and code sandbox engines with their disks at once. Agent Runtime sessions there keep running until they end. Then it deletes its runtime owner Role there, so Kubernetes removes the rest, and logs that the namespace is clean. Only objects this install created are deleted.
    • The Helm chart sets it from archestra.orchestrator.kubernetes.rbac.retiredNamespaces and keeps the platform's Roles in those namespaces. Remove a namespace from the list after the platform logs that it is clean. See Cluster Security.
  • ARCHESTRA_ORCHESTRATOR_K8S_CLUSTER_DNS_IPS - Cluster resolver addresses that environment egress policies allow DNS to.

    • Default: unset (discovery reads the kube-system/kube-dns Service when permitted, then falls back to the platform pod's /etc/resolv.conf when running in-cluster)
    • Values: comma-separated IP addresses, for example 172.20.0.10. Helm also accepts a list under archestra.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.
  • 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.

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

SRE Agent

The SRE agent investigates the installation's pods, logs, and events through a read-only Kubernetes MCP server. The Helm chart sets these from archestra.sre.

  • ARCHESTRA_SRE_AGENT_ENABLED - Installs the read-only Kubernetes MCP server, its SRE environment, and the SRE agent.

    • Default: false
    • Setting it back to false removes all three.
  • ARCHESTRA_SRE_K8S_SERVICE_ACCOUNT - ServiceAccount the MCP server pod runs as.

    • Default: unset. The Helm chart creates a read-only -sre account for it and sets it when archestra.orchestrator.kubernetes.mcpServerRbac.create is true.
    • Required: without it, nothing is installed.
  • ARCHESTRA_SRE_APISERVER_CIDRS - Kubernetes API server endpoint CIDRs the MCP server may reach, added to the organization's default egress policy.

    • Default: unset (the environment uses the organization's default egress policy)
    • Values: comma-separated IPv4 or IPv6 CIDRs, for example 172.16.0.2/32. Invalid entries are ignored and logged.

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

  • 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_K8S_NAMESPACE - Runs every code sandbox engine in its own namespace, apart from MCP servers. Engines run privileged, so this lets the MCP namespaces enforce a stricter Pod Security level.

    • Default: unset (each engine runs in its environment's namespace, or else ARCHESTRA_ORCHESTRATOR_K8S_NAMESPACE)
    • When set, it wins over environment namespaces. Each environment still gets its own engine and egress policy there. At startup, the platform removes engines from the namespaces they ran in before.
    • The Helm chart sets it from archestra.orchestrator.kubernetes.daggerRuntimeNamespace and grants the platform ServiceAccount access there. Create the namespace first.
  • 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.

  • ARCHESTRA_SKILLS_SANDBOX_HEADLESS_RETENTION_DAYS - 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. 0 keeps them forever.

    • Default: 7
  • 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, OpenClaw, Grok Build, and Kimi Code images are pulled from.

    • Default: ghcr.io/archestra-ai
    • Set it when you mirror these images to a private registry.
  • ARCHESTRA_AGENT_RUNTIME_IMAGE_TAG - Tag of the maintained images.

    • 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.
  • ARCHESTRA_AGENT_RUNTIME_ALLOW_PRIVILEGED - Lets Agent administrators enable privileged runtime pods, which have node-level access.

    • Default: false
    • Values: true, false
    • Turning it off also stops Agents already set to privileged: their new runs and follow-up turns fail until an Agent administrator turns privileged mode off.
  • 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.

  • ARCHESTRA_AGENT_RUNTIME_DEFAULT_TTL_HOURS - Default maximum duration of a run, in hours. A run's files are kept for the same time.

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

    • Default: 60
    • Custom images must implement the wait, using the ARCHESTRA_AGENT_RUNTIME_IDLE_TIMEOUT_SECONDS variable passed to the pod.
  • Runtime tiers - A run's pod gets the CPU and memory of its runtime tier. The tiers are stored with the organization, not in environment variables. The pod sees its tier in ARCHESTRA_AGENT_RUNTIME_TIER, the agent's scaleup tier in ARCHESTRA_AGENT_RUNTIME_MAX_TIER, the tiers it may move to with their sizes as JSON in ARCHESTRA_AGENT_RUNTIME_TIERS, and its size in ARCHESTRA_AGENT_RUNTIME_POD_CPU_REQUEST, ARCHESTRA_AGENT_RUNTIME_POD_CPU_LIMIT (set only when the tier has a CPU limit), ARCHESTRA_AGENT_RUNTIME_POD_MEMORY_REQUEST and ARCHESTRA_AGENT_RUNTIME_POD_MEMORY_LIMIT. ARCHESTRA_AGENT_RUNTIME_POD_CPUS is the number of whole CPUs to work in parallel: the CPU limit, else the request, rounded up. A pod with no CPU limit sees every CPU of its node, so the pod also gets GOMAXPROCS, CARGO_BUILD_JOBS and RAYON_NUM_THREADS set to that number, for Go programs such as the TypeScript 7 compiler, and for Cargo and Rayon. An agent's own environment can set these three to other values; ARCHESTRA_AGENT_RUNTIME_SIZED_ENV lists the ones the platform set. When a run is served from a larger tier's warm pool, the pod's values and the listed toolchain values follow the larger tier, and the agent's own values stay. The former ARCHESTRA_AGENT_RUNTIME_CPU_REQUEST, ARCHESTRA_AGENT_RUNTIME_MEMORY_REQUEST and ARCHESTRA_AGENT_RUNTIME_MEMORY_LIMIT variables are no longer read.

  • ARCHESTRA_AGENT_RUNTIME_WORKSPACE_STORAGE_SIZE - Size of a run's persistent volume, which holds /home/node and, for privileged runs, /var/lib/docker. A runtime tier with a Workspace size of its own overrides it for that tier's runs.

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

    • Default: true
  • ARCHESTRA_AGENT_RUNTIME_K8S_NAMESPACE - Runs Agent Runtime sessions and warm pools in their own namespace, apart from MCP servers, so each can get its own Pod Security, NetworkPolicy, and RBAC. An Agent whose environment names a namespace still runs there.

    • Default: unset (the default environment's namespace, or else ARCHESTRA_ORCHESTRATOR_K8S_NAMESPACE)
    • The Helm chart sets it from archestra.orchestrator.kubernetes.agentRuntimeNamespace and grants the platform ServiceAccount access there. Create the namespace first.
  • 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_PRIVILEGED_NODE_SELECTOR - Schedules privileged runtime pods onto their own node pool, away from unprivileged runs and other workloads.

  • ARCHESTRA_AGENT_RUNTIME_RUNTIME_CLASS_NAME - RuntimeClass for unprivileged runtime pods, such as 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. See Sandboxed Runtime.
    • If the RuntimeClass does not exist, unprivileged runs fail at once with a reason that names it. The platform checks with a dry-run pod create in the Agent Runtime namespace, so it needs no extra permissions.
  • 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).

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

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

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

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

  • ARCHESTRA_FILE_STORAGE_S3_BUCKET - Bucket that stores files.

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

  • ARCHESTRA_FILE_STORAGE_S3_SECRET_ACCESS_KEY - Secret access key for the bucket.

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

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

  • ARCHESTRA_AGENTS_INCOMING_EMAIL_OUTLOOK_CLIENT_SECRET - Client secret of that app registration.

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

  • ARCHESTRA_AGENTS_INCOMING_EMAIL_OUTLOOK_EMAIL_DOMAIN - Domain used in agent email addresses.

  • 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
    • See Public Webhook Endpoints.

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_WEBHOOK_BASE_URL - Public base URL for Slack events, interactive actions, and slash commands when the web app is private.

    • Default: the ngrok tunnel URL, or the frontend URL when no tunnel is active.
    • Values: an HTTP(S) base URL, for example https://hooks.example.com.
    • Used when creating or retargeting Slack apps. Existing app URLs require a separate update. Browser OAuth redirects keep using the frontend or tunnel URL.
    • See Public Webhook Endpoints.
  • ARCHESTRA_CHATOPS_SIGNUP_WELCOME_ENABLED - Sends a welcome message to users who are created automatically when they first message an agent.

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

  • ARCHESTRA_CHATOPS_MS_TEAMS_APP_SECRET - Client secret of the Azure Bot registration.

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

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

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

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.

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

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

  • 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

These variables open an ngrok tunnel to Archestra on startup, for a local instance. Public Webhook Endpoints lists what must be reachable from the internet.

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

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

  • 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>. To change it, see Metrics 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.

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

  • 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

Choose whether stored LLM proxy logs, MCP gateway logs, and Guardrails consult records include prompts and tool data.

  • 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.
    • Metadata-only mode also omits captured prompt/response and tool argument/result fields from LLM proxy and MCP tool-call trace spans.

Application error logs omit attached SDK request bodies, including those in retry histories. In metadata_only 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_OTEL_CAPTURE_CONTENT 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_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_OTEL_ENABLED - Set to true to export persisted administrative audit event metadata as OTLP logs through the configured OpenTelemetry endpoint. Default: false. Delivery is best-effort; see Audit log export.

  • ARCHESTRA_AUDIT_LOG_OTEL_ENDPOINT - OTLP/HTTP endpoint that receives the audit export instead of ARCHESTRA_OTEL_EXPORTER_OTLP_ENDPOINT. Set it to keep audit records apart from backend logs and traces, such as in a collector only your security team reads.

    • Default: unset (audit records use the shared endpoint)
    • Records go to /v1/logs. The shared endpoint's credentials are never sent here.
  • ARCHESTRA_AUDIT_LOG_OTEL_INCLUDE_ACTOR_IDENTITY - Set to true to add the actor's email and display name to each exported audit record, so security alerts can name who acted without looking up the actor ID.

    • Default: false
    • The collector then receives personal data; restrict who can read it.
  • ARCHESTRA_AUDIT_LOG_OTEL_AUTH_USERNAME - Username for basic authentication to the audit endpoint.

  • ARCHESTRA_AUDIT_LOG_OTEL_AUTH_PASSWORD - Password for basic authentication to the audit endpoint.

  • ARCHESTRA_AUDIT_LOG_OTEL_AUTH_BEARER - Bearer token for the audit endpoint.

    • Default: unset
    • Takes precedence over basic authentication.
  • 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. See Guardrails Signing Key.
  • ARCHESTRA_OPENAPPA_POLICY_CHECK_NAME - 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.

    • 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.
  • ARCHESTRA_OPENAPPA_SELF_SERVICE - Controls the MCP Guardrails Self-Service feature - whether the MCP owners can edit Guardrail policies for these MCPs themselves. Overrides related configuration from Settings.

    • Default: unset.
    • Values: enabled, disabled.
  • ARCHESTRA_OPENAPPA_SELF_SERVICE_AUTO_MERGE - Sets Auto-merge for MCP Guardrails Self-Service: the GitHub App merges each MCP server's rules pull request once its policy check passes. While it is set, it overrides the setting saved in Git sync setup, which cannot be edited there.

    • Default: unset (the saved setting applies, off unless changed).
    • Values: enabled, disabled. Other values stop startup.
  • ARCHESTRA_OPENAPPA_HUMAN_APPROVAL_MODE - Sets Human approval under Break the glass for the whole deployment. While it is set, it overrides the value saved in Settings → Guardrails, and the setting cannot be edited there. Unset it to edit the setting again.

    • Default: unset (the saved setting applies, block unless changed)
    • Values: block, unattended, everywhere. Other values stop startup.
    • Release 1.4 configures this setting only with this variable. Keep it set when you upgrade from 1.4 to keep the same behaviour.
  • ARCHESTRA_OPENAPPA_SOFT_BLOCK_MODE - Sets Other blocked calls under Break the glass: an emergency override for soft refusals across tool calls and results, child returns, runtime exports, peer messages, failed helpers, and fork or compaction admission. allow releases the operation and turns Guardrails off for the session, even at its first refusal and even if yell reporting is disabled or fails. Platform authentication and access checks remain enforced. While it is set, it overrides the value saved in Settings → Guardrails, and the setting cannot be edited there. An explicit blocked refusal cannot trigger a waiver. After a soft refusal turns Guardrails off, subsequent operations bypass all policy checks, including explicit blocked marks.

    • Default: unset (the saved setting applies, refuse unless changed)
    • Values: refuse, allow. Other values stop startup.
    • Release 1.4 configures this setting only with this variable. Keep it set when you upgrade from 1.4 to keep the same behaviour.
  • ARCHESTRA_OPENAPPA_YELL_ENABLED - Lets agents report confusing blocks with the yell tool. Reports are stored locally.

  • ARCHESTRA_OPENAPPA_YELL_FORWARDING_ENABLED - Forwards agent reports to the shared OpenAPPA reporting service, independently of ARCHESTRA_ANALYTICS. Requires 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.
  • 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.