Deployment

The Archestra Platform can be deployed using Docker for development and testing, or Helm for production environments. Both deployment methods provide access to the Admin UI on port 3000 and the API on port 9000.

Docker Deployment

Docker deployment provides the fastest way to get started with Archestra Platform, ideal for development and testing purposes.

Docker Prerequisites

• Docker - Container runtime (Install Docker)

Basic Deployment

Run the platform with a single command:

docker pull archestra/platform:latest;
docker run -p 9000:9000 -p 3000:3000 \
   -v archestra-postgres-data:/var/lib/postgresql/data \
   -v archestra-app-data:/app/data \
   archestra/platform;

This will start the platform with:

• Admin UI available at http://localhost:3000
• API available at http://localhost:9000
• Auth Secret auto-generated and saved to /app/data/.auth_secret (persisted across restarts)

Using External PostgreSQL

To use an external PostgreSQL database, pass the DATABASE_URL environment variable:

docker pull archestra/platform:latest;
docker run -p 9000:9000 -p 3000:3000 \
  -e DATABASE_URL=postgresql://user:password@host:5432/database \
  archestra/platform

⚠️ Important: If you don't specify DATABASE_URL, PostgreSQL will run inside the container for you. This approach is meant for development and tinkering purposes only and is not intended for production, as the data is not persisted when the container stops.

Helm Deployment (Recommended for Production)

Helm deployment is our recommended approach for deploying Archestra Platform to production environments.

Helm Prerequisites

• Kubernetes cluster - A running Kubernetes cluster
• Helm 3+ - Package manager for Kubernetes (Install Helm)
• kubectl - Kubernetes CLI (Install kubectl)

Installation

Install Archestra Platform using the Helm chart from our OCI registry:

helm upgrade archestra-platform \
  oci://europe-west1-docker.pkg.dev/friendly-path-465518-r6/archestra-public/helm-charts/archestra-platform \
  --install \
  --namespace archestra \
  --create-namespace \
  --wait

This command will:

• Install or upgrade the release named archestra-platform
• Create the namespace archestra if it doesn't exist
• Wait for all resources to be ready

Configuration

The Helm chart provides extensive configuration options through values. For the complete configuration reference, see the values.yaml file.

Core Configuration

Archestra Platform Settings:

• archestra.image - Docker image for the Archestra Platform (contains both backend API and frontend). See available tags
• archestra.env - Environment variables to pass to the container (see Environment Variables section above for available options)

Example:

helm upgrade archestra-platform \
  oci://europe-west1-docker.pkg.dev/friendly-path-465518-r6/archestra-public/helm-charts/archestra-platform \
  --install \
  --namespace archestra \
  --create-namespace \
  --set archestra.env.ARCHESTRA_API_BASE_URL=https://api.example.com \
  --wait

Note: ARCHESTRA_AUTH_SECRET is optional and will be auto-generated (64 characters) if not specified. If you need to set it manually, it must be at least 32 characters:

# Generate a secure secret
openssl rand -base64 32

# Then add to your helm command:
--set archestra.env.ARCHESTRA_AUTH_SECRET=<your-generated-secret>

MCP Server Runtime Configuration

Orchestrator Settings:

• archestra.orchestrator.baseImage - Base Docker image for MCP server containers (defaults to official Archestra MCP server base image)

Kubernetes Settings:

• archestra.orchestrator.kubernetes.namespace - Kubernetes namespace where MCP server pods will be created (defaults to Helm release namespace)
• archestra.orchestrator.kubernetes.loadKubeconfigFromCurrentCluster - Use in-cluster configuration (recommended when running inside K8s)
• archestra.orchestrator.kubernetes.kubeconfig.enabled - Enable mounting kubeconfig from a secret
• archestra.orchestrator.kubernetes.kubeconfig.secretName - Name of secret containing kubeconfig file
• archestra.orchestrator.kubernetes.kubeconfig.mountPath - Path where kubeconfig will be mounted
• archestra.orchestrator.kubernetes.serviceAccount.create - Create a service account (default: true)
• archestra.orchestrator.kubernetes.serviceAccount.annotations - Annotations to add to the service account
• archestra.orchestrator.kubernetes.serviceAccount.name - Name of the service account (auto-generated if not set)
• archestra.orchestrator.kubernetes.serviceAccount.imagePullSecrets - Image pull secrets for the service account
• archestra.orchestrator.kubernetes.rbac.create - Create RBAC resources (default: true)

Service & Ingress Configuration

Service Settings:

• archestra.service.annotations - Annotations to add to the Kubernetes Service for cloud provider integrations

Ingress Settings:

• archestra.ingress.enabled - Enable or disable ingress creation (default: false)
• archestra.ingress.annotations - Annotations for ingress controller and load balancer behavior
• archestra.ingress.spec - Complete ingress specification for advanced configurations

Cloud Provider Configuration (Streaming Timeout Settings)

⚠️ IMPORTANT: Archestra Platform requires proper timeout settings on the upstream load balancer. Without longer timeouts, streaming responses may end prematurely, resulting in a “network error”

Google Cloud Platform (GKE)

For GKE deployments using the GCE Ingress Controller, configure load balancer timeouts using a BackendConfig resource. BackendConfig is cloud-provider-specific and should be managed through your infrastructure-as-code (Terraform, Pulumi, etc.) rather than the Helm chart.

Create BackendConfig Resource:

The BackendConfig should be created in the same namespace as your Archestra Platform deployment:

apiVersion: cloud.google.com/v1
kind: BackendConfig
metadata:
  name: archestra-platform-backend-config
  namespace: archestra # Same namespace as Helm release
spec:
  timeoutSec: 600 # 10 minutes for streaming responses and long-running MCP operations
  connectionDraining:
    drainingTimeoutSec: 60
  healthCheck:
    checkIntervalSec: 10
    timeoutSec: 5
    healthyThreshold: 1
    unhealthyThreshold: 3
    type: HTTP
    requestPath: /health
    port: 9000

Reference BackendConfig in Service:

After creating the BackendConfig resource, configure the Helm chart to reference it via service annotations:

archestra:
  service:
    annotations:
      cloud.google.com/backend-config: '{"ports": {"9000":"archestra-platform-backend-config"}}'

Apply via Helm:

helm upgrade archestra-platform \
  oci://europe-west1-docker.pkg.dev/friendly-path-465518-r6/archestra-public/helm-charts/archestra-platform \
  --install \
  --namespace archestra \
  --create-namespace \
  --set-string archestra.service.annotations."cloud\.google\.com/backend-config"='{"ports": {"9000":"archestra-platform-backend-config"}}' \
  --wait

Amazon Web Services (AWS EKS)

For AWS EKS with Application Load Balancer (ALB), configure timeout annotations on the Service:

archestra:
  service:
    annotations:
      service.beta.kubernetes.io/aws-load-balancer-backend-protocol: "http"
      service.beta.kubernetes.io/aws-load-balancer-connection-idle-timeout: "600"

Apply via Helm:

helm upgrade archestra-platform \
  oci://europe-west1-docker.pkg.dev/friendly-path-465518-r6/archestra-public/helm-charts/archestra-platform \
  --install \
  --namespace archestra \
  --create-namespace \
  --set-string archestra.service.annotations."service\.beta\.kubernetes\.io/aws-load-balancer-backend-protocol"=http \
  --set-string archestra.service.annotations."service\.beta\.kubernetes\.io/aws-load-balancer-connection-idle-timeout"="600" \
  --wait

Microsoft Azure (AKS)

For Azure AKS with Application Gateway Ingress Controller (AGIC), configure timeout annotations on the Ingress:

archestra:
  ingress:
    enabled: true
    annotations:
      appgw.ingress.kubernetes.io/request-timeout: "600"
      appgw.ingress.kubernetes.io/connection-draining-timeout: "60"

Apply via Helm:

helm upgrade archestra-platform \
  oci://europe-west1-docker.pkg.dev/friendly-path-465518-r6/archestra-public/helm-charts/archestra-platform \
  --install \
  --namespace archestra \
  --create-namespace \
  --set archestra.ingress.enabled=true \
  --set-string archestra.ingress.annotations."appgw\.ingress\.kubernetes\.io/request-timeout"="600" \
  --set-string archestra.ingress.annotations."appgw\.ingress\.kubernetes\.io/connection-draining-timeout"="60" \
  --wait

Other Ingress Controllers (nginx, Traefik, etc.)

For nginx-ingress:

archestra:
  ingress:
    enabled: true
    annotations:
      nginx.ingress.kubernetes.io/proxy-read-timeout: "600"
      nginx.ingress.kubernetes.io/proxy-send-timeout: "600"

For Traefik:

archestra:
  ingress:
    enabled: true
    annotations:
      traefik.ingress.kubernetes.io/service.passhostheader: "true"
      # Configure timeout via Traefik IngressRoute or Middleware

Database Configuration

PostgreSQL Settings:

• postgresql.external_database_url - External PostgreSQL connection string (recommended for production)
• postgresql.enabled - Enable managed PostgreSQL instance (default: true, disabled if external_database_url is set)

For external PostgreSQL (recommended for production):

helm upgrade archestra-platform \
  oci://europe-west1-docker.pkg.dev/friendly-path-465518-r6/archestra-public/helm-charts/archestra-platform \
  --install \
  --namespace archestra \
  --create-namespace \
  --set postgresql.external_database_url=postgresql://user:password@host:5432/database \
  --wait

If you don't specify postgresql.external_database_url, the chart will deploy a managed PostgreSQL instance using the Bitnami PostgreSQL chart. For PostgreSQL-specific configuration options, see the Bitnami PostgreSQL Helm chart documentation.

Accessing the Platform

After installation, access the platform using port forwarding:

# Forward the API (port 9000) and the Admin UI (port 3000)
kubectl --namespace archestra port-forward svc/archestra-platform 9000:9000 3000:3000

Then visit:

• Admin UI: http://localhost:3000
• API: http://localhost:9000

Infrastructure as Code

Terraform

For managing Archestra Platform resources, you can use our official Terraform provider to manage Archestra Platform declaratively.

For complete documentation, examples, and resource reference, visit the Archestra Terraform Provider Documentation.

Environment Variables

The following environment variables can be used to configure Archestra Platform:

• ARCHESTRA_DATABASE_URL - PostgreSQL connection string for the database.

  • Format: postgresql://user:password@host:5432/database
  • Default: Internal PostgreSQL (Docker) or managed instance (Helm)
  • Required for production deployments with external database

• ARCHESTRA_API_BASE_URL - Base URL for the Archestra API proxy. This is where your agents should connect to instead of the LLM provider directly.

  • Default: http://localhost:9000
  • Example: http://localhost:9001 or https://api.example.com
  • Note: This configures both the port where the backend API server listens (parsed from the URL) and the base URL that the frontend uses to connect to the backend

• ARCHESTRA_FRONTEND_URL - The URL where users access the frontend application.

  • Example: https://frontend.example.com
  • Optional for local development

• ARCHESTRA_AUTH_COOKIE_DOMAIN - Cookie domain configuration for authentication.

  • Should be set to the domain of the ARCHESTRA_FRONTEND_URL
  • Example: If frontend is at https://frontend.example.com, set to example.com
  • Required when using different domains or subdomains for frontend and backend

• ARCHESTRA_AUTH_SECRET - Secret key used for signing authentication tokens and passwords.

  • Auto-generated once on first run. Set manually if you need to control the secret value. Must be at least 32 characters long.
  • Example: something-really-really-secret-12345

• ARCHESTRA_AUTH_ADMIN_EMAIL - Email address for the default Archestra Admin user, created on startup.

  • Default: admin@localhost.ai

• ARCHESTRA_AUTH_ADMIN_PASSWORD - Password for the default Archestra Admin user. Set once on first-run.

  • Default: password
  • Note: Change this to a secure password for production deployments

• ARCHESTRA_AUTH_DISABLE_BASIC_AUTH - Hides the username/password login form on the sign-in page.

  • Default: false
  • Set to true to disable basic authentication and require users to authenticate via SSO only
  • Note: Configure at least one SSO provider before enabling this option. See Single Sign-On for SSO configuration.

• ARCHESTRA_AUTH_DISABLE_INVITATIONS - Disables user invitations functionality.

  • Default: false
  • Set to true to hide invitation-related UI and block invitation API endpoints
  • When enabled, administrators cannot create new invitations, and the invitation management UI is hidden
  • Useful for environments where user provisioning is handled externally (e.g., via SSO with automatic provisioning)

• ARCHESTRA_ORCHESTRATOR_K8S_NAMESPACE - Kubernetes namespace to run MCP server pods.

  • Default: default
  • Example: archestra-mcp or production

• ARCHESTRA_ORCHESTRATOR_MCP_SERVER_BASE_IMAGE - Base Docker image for MCP servers.

  • Default: europe-west1-docker.pkg.dev/friendly-path-465518-r6/archestra-public/mcp-server-base:0.0.3
  • Can be overridden per individual MCP server.

• ARCHESTRA_ORCHESTRATOR_LOAD_KUBECONFIG_FROM_CURRENT_CLUSTER - Use in-cluster config when running inside Kubernetes.

  • Default: true
  • Set to false when Archestra is deployed in the different cluster and specify the ARCHESTRA_ORCHESTRATOR_KUBECONFIG.

• ARCHESTRA_ORCHESTRATOR_KUBECONFIG - Path to custom kubeconfig file. Mount the required kubeconfig as volume inside the

  • Optional: Uses default locations if not specified
  • Example: /path/to/kubeconfig

• ARCHESTRA_OTEL_EXPORTER_OTLP_ENDPOINT - OTEL Exporter endpoint for sending traces

  • Default: http://localhost:4318/v1/traces

• ARCHESTRA_OTEL_EXPORTER_OTLP_AUTH_USERNAME - Username for OTEL basic authentication

  • Optional: Only used if both username and password are provided
  • Example: your-username

• ARCHESTRA_OTEL_EXPORTER_OTLP_AUTH_PASSWORD - Password for OTEL basic authentication

  • Optional: Only used if both username and password are provided
  • Example: your-password

• ARCHESTRA_OTEL_EXPORTER_OTLP_AUTH_BEARER - Bearer token for OTEL authentication

  • Optional: Takes precedence over basic authentication if provided
  • Example: your-bearer-token

• ARCHESTRA_ANALYTICS - Controls PostHog analytics for product improvements.

  • Default: enabled
  • Set to disabled to opt-out of analytics

• ARCHESTRA_LOGGING_LEVEL - Log level for Archestra

  • Default: info
  • Supported values: trace, debug, info, warn, error, fatal

• ARCHESTRA_METRICS_SECRET - Bearer token for authenticating metrics endpoint access

  • Default: archestra-metrics-secret
  • Note: When set, clients must include Authorization: Bearer <token> header to access /metrics

• ARCHESTRA_SECRETS_MANAGER - Secrets storage backend for managing sensitive data (API keys, tokens, etc.)

  • Default: DB (database storage)
  • Options: DB or Vault
  • Note: When set to Vault, requires HASHICORP_VAULT_ADDR and HASHICORP_VAULT_TOKEN to be configured

• HASHICORP_VAULT_ADDR - HashiCorp Vault server address

  • Required when: ARCHESTRA_SECRETS_MANAGER=Vault
  • Example: http://localhost:8200
  • Note: System falls back to database storage if Vault is configured but credentials are missing

• HASHICORP_VAULT_TOKEN - HashiCorp Vault authentication token

  • Required when: ARCHESTRA_SECRETS_MANAGER=Vault
  • Note: System falls back to database storage if Vault is configured but credentials are missing

• ARCHESTRA_ENTERPRISE_LICENSE_ACTIVATED - Activates enterprise features in Archestra.

  • Please reach out to sales@archestra.ai to learn more about the license.