You are viewing the docs for Archestra v1.4. View the latest docs
Deployment
Use Docker to try Archestra locally. Use Helm to run it in Kubernetes with a persistent database, workers, and MCP server workloads. The UI listens on port 3000; the backend listens on port 9000.
Docker Deployment
Quickstart Deployment
Install Docker, then use the command in Run Archestra. Its named volumes preserve database and application data. The Docker socket mount enables the embedded Kubernetes cluster for self-hosted MCP servers.
Open http://localhost:3000 to confirm the UI loads. Keep the loopback port bindings for a local instance. For production, use Helm and a database with backups.
Using External PostgreSQL
Set ARCHESTRA_ to use an external database. Without an external URL, the container starts PostgreSQL internally; preserve /var/lib/postgresql/data with a volume. Keep /app/data persistent for automatically generated secrets.
Helm Deployment
You need a Kubernetes cluster, Helm 3 or later, and kubectl access. Self-hosted MCP workloads need the chart's orchestration permissions. Network restrictions require a policy-enforcing cluster dataplane; see Environment network policies.
Installation
Pin the chart version and review its defaults:
export ARCHESTRA_VERSION="1.4.36" # x-release-please-version
helm show values \
oci://europe-west1-docker.pkg.dev/friendly-path-465518-r6/archestra-public/helm-charts/archestra-platform \
--version "$ARCHESTRA_VERSION" > values.yaml
Edit values.yaml for your database, secrets, and ingress, then install:
helm upgrade archestra-platform \
oci://europe-west1-docker.pkg.dev/friendly-path-465518-r6/archestra-public/helm-charts/archestra-platform \
--version "$ARCHESTRA_VERSION" \
--install --namespace archestra --create-namespace \
--values values.yaml --wait
Core Configuration
Use archestra.env for non-secret environment variables. Use archestra.envWithValueFrom, archestra.envFromSecrets, or archestra.envFrom for Kubernetes Secret references. The full environment-variable list is in Configuration.
The chart generates and preserves authentication and credential-encryption keys. To supply existing keys, set archestra.authSecret.existingSecretName; the default key names are auth-secret, session-secret, secrets-encryption-secret, and offer-signing-secret.
Configure different key names explicitly. Environment-variable-safe names also let you load the same Secret through archestra.envFrom on clusters that reject hyphens in environment variable names:
archestra:
authSecret:
existingSecretName: archestra-auth
existingSecretKey: ARCHESTRA_AUTH_SECRET
existingSessionSecretKey: ARCHESTRA_AUTH_SESSION_SECRET
existingSecretsEncryptionSecretKey: ARCHESTRA_SECRETS_ENCRYPTION_SECRET
existingOfferSigningSecretKey: ARCHESTRA_OPENAPPA_OFFER_SIGNING_SECRET
Preserve these keys across upgrades and restores. Use the key rotation procedure when changing encryption keys.
DNS Discovery
In-cluster installations can discover the DNS resolver from the platform pod's DNS configuration without creating resources in kube-system. Environment egress policies use that resolver to allow DNS lookups for MCP servers, agents, and sandboxes.
If workloads use a different resolver or discovery fails, configure verified addresses:
archestra:
orchestrator:
kubernetes:
clusterDnsIps:
- 172.20.0.10 # Replace with your cluster's resolver IP.
Alternatively, set archestra.orchestrator.kubernetes.rbac.kubeDnsServiceRead: true to grant the platform service account get on the kube-system/kube-dns Service. This creates a Role and RoleBinding in kube-system; the installer and any GitOps project must permit managing both resources there. Creating the platform service account alone does not grant the installer this access.
Disabling an existing DNS reader grant does not guarantee Helm removes its Role and RoleBinding when the installer lacks access to kube-system. Have an operator with access to that namespace remove the release's DNS reader objects.
On EKS Auto Mode, check that workload DNS lookups succeed after deployment. If no resolver can be determined, egress policies omit the DNS bootstrap exception rather than allowing port 53 to arbitrary destinations.
Database Configuration
Use an external PostgreSQL database when availability or managed backups matter. The bundled database runs one replica. Store the complete external URL in a Kubernetes Secret rather than Helm values. With a Secret named archestra-database containing a url key:
postgresql:
enabled: false
archestra:
envWithValueFrom:
- name: ARCHESTRA_DATABASE_URL
valueFrom:
secretKeyRef:
name: archestra-database
key: url
migrationJob:
envWithValueFrom:
- name: ARCHESTRA_DATABASE_URL
valueFrom:
secretKeyRef:
name: archestra-database
key: url
Provide the same database URL to the migration Job and application. The chart runs migrations before rolling out an upgrade. Keep archestra.migrationJob.enabled enabled unless your pipeline applies migrations separately.
To verify the database's TLS certificate, mount the CA bundle with archestra.extraVolumes and archestra.extraVolumeMounts and point the URL at it, for example ?sslmode=verify-full&sslrootcert=/etc/ssl/db/ca.pem. The web pods, worker pods and migration Job all get these mounts. The migration Job skips persistentVolumeClaim volumes, because it runs while the previous pods still hold their claims.
archestra:
extraVolumes:
- name: db-ca
secret:
secretName: db-ca-bundle
extraVolumeMounts:
- name: db-ca
mountPath: /etc/ssl/db
readOnly: true
For Knowledge Base vector storage, PostgreSQL must have the pgvector extension available and the migration user must be able to create the extension, or an administrator must install it first.
Set archestra.database.connectionBudget to size query pools across peak web and worker pods, including rollout overlap. Leave room in PostgreSQL for other clients and reserved connections. Each peak pod needs at least 13 budgeted connections; the chart rejects smaller budgets. A fixed archestra.database.poolMax or ARCHESTRA_ overrides budget sizing. Complete one rollout before starting another.
Cost Statistics Index
For large interaction histories, an optional covering index reduces database reads for Costs statistics. It adds index storage and maintenance work to interaction inserts.
After the database migrations finish, run this command once from /app/backend in the application container during a database maintenance window:
node scripts/create-statistics-index.mjs
The command uses ARCHESTRA_. Connect directly to PostgreSQL or through session pooling, using credentials that can create indexes. Transaction pooling is unsupported.
The build runs concurrently with interaction writes and consumes database I/O while it scans. It stops after a five-second lock wait or a thirty-minute statement timeout. Rerunning preserves a valid index and rebuilds an invalid index left by an interrupted build. Successful output reports created, already_, or rebuilt_.
Enable Fast Logs User Lists
The logs user picker can keep its most-active ordering without recounting the full log on each cache miss. New installations and upgrades leave this optimization disabled until you activate it.
-
Finish the database migrations and upgrade every web, worker, and other interaction writer. Stop all old binaries before enabling the summary: they do not maintain its counts.
-
From
/app/backendin an upgraded application container, run:bashnode dist/standalone-scripts/rebuild-interaction-user-activity.mjs --enable -
Confirm the output reports
ready: true. Exit code 2 means the bounded run is incomplete; rerun without--enableto resume. The background worker also resumes incomplete work every 30 seconds. Until completion, the picker uses the original exact query.
The migrations create small, initially empty summary tables and an append function; they do not scan or change the interaction table. Apply the function migration before starting upgraded writers: missing functions fail the write rather than bypassing count maintenance. Rebuilding reads existing history in user batches without holding write locks during the history scan. Inserts maintain counts in one database statement; retention deletes use a transaction. Writes for the same user serialize.
The server caches the most-active list for at most 30 seconds, including load time. An open picker refreshes every 20 seconds and revalidates when reopened, keeping successful active-page refreshes within the 60-second ranking budget without adding the old five-minute client cache. Network failures and inactive browser tabs can delay refreshes. Explicit search reads current history rather than the ranked cache.
- Before rolling back to an old binary, run the command with
--disableand wait for it to finish. Disabled writers do not maintain summary balances; a later--enablestarts a new rebuild. - Owner deletion or organization reassignment invalidates the summary. Exact queries remain active while the worker rebuilds it. User deletion removes that user's derived counts; names are joined when the list is loaded.
- Direct SQL changes to interactions bypass maintenance. Disable the summary before such work, then run with
--enableafterward. If counts may already have drifted, use--invalidateto rebuild while keeping exact fallback active. Do not use--invalidateon every resume; it restarts progress. - A negative reconciled count or an integer outside JavaScript's safe range stops the rebuild without publishing partial results. Exact fallback remains active while valid summary state is incomplete; unsafe version counters instead reject list requests rather than reuse an ambiguous cache entry. Investigate and repair the accounting fault before retrying with
--invalidate; repeated retries do not repair inconsistent accounting.
Scaling
archestra.replicaCount controls web replicas. archestra.worker.replicaCount controls separate workers. Enabling archestra.horizontalPodAutoscaler.enabled replaces the web replica setting; the default HPA range is 2–10 pods. Worker replicas remain manual. Increase database connection capacity alongside replicas.
Use archestra.resources and archestra.worker.resources to size pods. Diagnostics storage shared by concurrent pods requires a compatible ReadWriteMany volume; check archestra.diagnostics in the selected chart's values.
The web and worker pods share archestra.nodeSelector, archestra.tolerations, archestra.affinity, archestra.topologySpreadConstraints and archestra.podAnnotations.
To survive a zone outage, spread replicas across zones with archestra.topologySpreadConstraints. Leave out labelSelector and each Deployment counts only its own pods, so web pods and worker pods each spread evenly and can share a zone:
archestra:
topologySpreadConstraints:
- maxSkew: 1
topologyKey: topology.kubernetes.io/zone
whenUnsatisfiable: DoNotSchedule
For pod anti-affinity, add matchLabelKeys: [app.kubernetes.io/component] to the term so web and worker pods are counted separately (Kubernetes 1.31 and later).
Accessing the Platform
For a local verification before configuring ingress:
kubectl --namespace archestra port-forward svc/archestra-platform 9000:9000 3000:3000
Open http://localhost:3000. Confirm you can sign in and that the backend is reachable on port 9000. For an external deployment, configure TLS and the public URLs before connecting agents.
Routing the LLM Proxy Away From the Frontend
Route /v1 and /v2 to backend port 9000 and / to frontend port 3000. Keep /api/auth on the frontend. The chart applies this split for archestra.ingress.hosts by default. A complete archestra.ingress.spec or an external routing layer must apply it explicitly.
Keep-Alive Timeouts
Set the ingress or load-balancer response timeout long enough for streamed model responses. Also set ARCHESTRA_ above the load balancer's backend idle-connection timeout if it exceeds the platform default. Test a streaming request through the public endpoint.
MCP Gateway OAuth Public Origin
List every public gateway host in ARCHESTRA_ or ARCHESTRA_, using its public https:// scheme. API base URLs accept a comma-separated list. This keeps OAuth metadata and connection documents on HTTPS even when TLS terminates before Archestra.
An unconfigured host falls back to the request scheme. A proxy that drops X-Forwarded-Proto can therefore advertise HTTP and break OAuth discovery. ARCHESTRA_ does not change this public-origin rule.
SSRF Protection for MCP Server Pods
Self-hosted MCP servers inherit environment egress policies. Public internet mode blocks private, metadata, and reserved destinations unless explicitly allowed. The cluster's network dataplane must enforce those policies; creating policy objects alone does not enforce isolation.
MCP Apps Sandbox
Local instances isolate MCP Apps using localhost and 127.0.0.1. Production instances without a sandbox domain use an opaque iframe origin, which cannot use persistent browser storage or APIs restricted to a specific origin.
For apps needing those capabilities:
- Choose a sandbox domain such as
mcp.example.com. - Create wildcard DNS and TLS for
*.mcp.example.com. - Route that wildcard host to backend port 9000.
- Set
ARCHESTRA_MCP_SANDBOX_DOMAIN=mcp.example.com. - Open an app and confirm it renders through its sandbox host.
Allowed embedding origins follow ARCHESTRA_ and ARCHESTRA_.
Code Sandbox
Archestra's managed Dagger engines need Linux nodes that permit privileged root pods with all Linux capabilities, plus dynamically provisioned ReadWriteOnce storage. Engine pods are separate from agent runtime containers.
If your cluster does not admit these pods, set ARCHESTRA_ to an external tcp:// or kube-pod:// engine, or disable the sandbox with ARCHESTRA_CODE_RUNTIME_ENABLED=false or Helm's archestra.codeRuntime.enabled: false.
Release Channels And Upgrades
New companion and agent runtime images are published at ghcr.io/archestra-ai. The main platform image remains at archestra/platform on Docker Hub. If you mirror images internally, import the release’s companion images from GHCR and preserve your Helm registry overrides. Existing releases remain at their original addresses.
Pin an exact chart version or image tag from GitHub Releases. Tags ending in -rc.N are release candidates. Avoid relying on latest for production upgrades.
- Back up PostgreSQL and preserve encryption keys.
- Read release notes for migration requirements.
- Test the selected version in staging.
- Apply the Helm upgrade above and check rollout and migration Job status.
Upgrading from v1.3? Follow Upgrade from v1.3 to v1.4 first: v1.4 removes some v1.3 data and needs v1.3 stopped.
On the first v1.4 startup, Archestra converts legacy sharing and role permissions before serving API traffic. One replica performs the conversion; other replicas wait, and later restarts skip it. During startup, /health responds successfully while /ready returns HTTP 503 until the API is ready, so large conversions do not exhaust the Kubernetes startup probe budget.
Set archestra.shutdown.requestDrainSeconds above the longest request you want to preserve after shutdown starts. For example, 200 gives a request with 180 seconds remaining room to finish. Keep archestra.terminationGracePeriodSeconds: null to derive matching web and worker pod limits. See shutdown settings for cleanup budgets and environment overrides.
During shutdown, readiness returns 503 and new work is rejected. Admitted LLM and MCP calls can finish within the drain budget, including their persistence work; MCP replies and cancellations for active calls remain available. Notification streams close after active calls settle. At the deadline, remaining HTTP connections close and unfinished work may be interrupted.
Reconnect notification streams to a live replica. An interrupted tool call can already have performed its side effect: retry only when the tool supports idempotency or after reconciling its result. The drain setting does not extend provider, MCP upstream or client timeouts; raise those separately when needed.
For Docker, set the same shutdown environment variables and allow at least max(drain, worker timeout) + cleanup + 40 seconds in docker stop --time or Compose's stop_.
The proxy retries a provider connection failure at most twice before receiving the first response chunk. It does not retry provider error responses, timeouts, or failures after output starts. Recovery after partial output depends on your client's retry policy.
Gemini is excluded from these proxy retries because its SDK can report an interrupted error response as a connection failure.
Rolling back a container image does not reverse database migrations. Restore a compatible database backup when required by the release's rollback procedure.
Infrastructure as Code
Manage Archestra resources from Terraform or Crossplane. Both use the same API key — mint one in the API Keys section in Personal Settings (click your name in the sidebar) (see API Reference).
Terraform
- Configure the provider. Read credentials from the environment (
export ARCHESTRA_API_KEY=...andexport ARCHESTRA_BASE_URL=...) or pass them inline.
terraform {
required_providers {
archestra = {
source = "archestra-ai/archestra"
}
}
}
provider "archestra" {}
- Define a resource. Register an MCP server in the catalog, then install it.
resource "archestra_mcp_registry_catalog_item" "memory" {
name = "memory"
description = "In-memory key-value store"
local_config = {
command = "npx"
arguments = ["-y", "@modelcontextprotocol/server-memory"]
}
}
resource "archestra_mcp_server_installation" "memory" {
name = "memory"
catalog_id = archestra_mcp_registry_catalog_item.memory.id
}
- Apply.
terraform init
terraform apply
Full resource reference: Terraform provider docs.
Crossplane
Install Crossplane v1 or v2 before adding the provider.
- Install the provider. Pin the latest tag from GitHub Releases.
apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
name: provider-archestra
spec:
package: xpkg.upbound.io/archestra/provider-archestra:v1.1.4
- Configure credentials.
kubectl create secret generic archestra-creds \
-n crossplane-system \
--from-literal=credentials='{"api_key":"arch_...","base_url":"https://api.archestra.example.com"}'
apiVersion: archestra.crossplane.io/v1beta1
kind: ProviderConfig
metadata:
name: default
spec:
credentials:
source: Secret
secretRef:
namespace: crossplane-system
name: archestra-creds
key: credentials
- Create a resource. Mirror of the Terraform example above.
apiVersion: mcp.archestra.crossplane.io/v1alpha1
kind: RegistryCatalogItem
metadata:
name: memory
spec:
forProvider:
name: memory
description: In-memory key-value store
localConfig:
command: npx
arguments:
- "-y"
- "@modelcontextprotocol/server-memory"
providerConfigRef:
name: default
---
apiVersion: mcp.archestra.crossplane.io/v1alpha1
kind: ServerInstallation
metadata:
name: memory
spec:
forProvider:
name: memory
catalogIdRef:
name: memory
providerConfigRef:
name: default
Full resource reference: Crossplane provider README. Resource coverage is partial — current state and the gap vs. the Terraform provider are tracked on the coverage badge.
Connect Page Settings
Admins configure the page under Settings → Connect Page, or with Connection settings on the Connect page:
| Setting | Effect |
|---|---|
| Default client, Default MCP Gateway | Pre-selected for everyone. Users can still switch. |
| LLM Proxy, Skills, and Plugins on Connect | Turning one off removes it from new setups. Existing setups keep working. |
| Agents users can connect | The agents offered on Connect, in order. Drag to reorder, click ✕ to remove one, and use Add back to restore it. Click an agent to pick the provider keys its setup command shares with everyone who connects it. An agent with no keys picked uses each user's own. Generic client is always shown last. |
| Instructions for connected agents | Added to the system prompt of every agent users connect from the Connect page. The default asks agents to offer moving a session to your deployment's Cloud runtime. CLI wrappers fetch saved changes before the next launch. |
Claude Code, Codex, Copilot CLI, OpenCode, and Kilo Code refresh these instructions before launch. Changes replace the managed copy and preserve the user’s own instructions.
- Existing connections: Run setup once to install the refresh capability. Unix wrappers require Python 3 to fetch updates.
- Temporary outages: The client uses its last fetched copy.
- Other clients: Cursor’s User Rules and Claude Desktop’s organization instructions still need a setup update.
Setup reads /connect.md, /llms.txt, and the setup endpoints under /api/client-connections and /api/connection-setups/script without a session. A proxy in front of Archestra that requires login for every URL must let these through. It must also allow /v1/connection-instructions; this endpoint checks the installation’s read-only credential and current access.
Upgrade OAuth Clients
Deploy the unified OAuth Clients release to all replicas together, with the older replicas stopped before the updated application starts. Mixed versions and rolling back to the older authorization model are unsupported. Back up the database before the upgrade.
Existing client IDs, secrets, provider keys, gateway assignments, and issued tokens carry over. MCP clients retain MCP Gateway and A2A access; LLM clients retain LLM Proxy access. The upgrade combines each custom role action and wildcard grant across the two former client resources. A read grant never becomes edit or delete, and grants on individual clients keep their scope. See OAuth client access control.
After the upgrade, open Settings → OAuth Clients and check the clients' capabilities and permissions. Request tokens with the scopes the application needs. Repeat startups preserve permission changes made after the upgrade.