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