You are viewing the docs for Archestra v1.4. View the latest docs
Upgrade from v1.3 to v1.4
Upgrading to v1.4 takes Archestra offline while the database migrates, and deletes some v1.3 settings for good. Record them, take a backup, then follow the steps for your install. The backup is your only way back to v1.3.
What Changes for Your Deployment
Each change below needs something from you. Handle the deleted data while v1.3 still runs.
Deleted in v1.4
v1.4 deletes these instead of converting them. Record them before you upgrade, and recreate them after.
- Guardrail policies. The Tool Call Policies and Tool Result Policies on the v1.3 Guardrails page are deleted. The new Guardrails starts off, so no tool-call rules apply until you go to Guardrails, click Create my policy, and rebuild them.
- LLM Proxy cost limits. Cost limits applied to an LLM Proxy are deleted. Organization, team, user, agent, and virtual key limits are kept. Recreate the deleted ones as organization limits.
- Custom role permissions. Custom roles lose their per-area settings, agent trigger, site notification, secret, and scheduled task permissions. Note each role under Settings → Roles, then grant
organizationSettings:update, or Projects actions for schedules, where a role needs them.
Clients That Stop Working
- Provider-key-only LLM requests get
401. Give each client an Archestra credential, such as a virtual key, or turn on Allow requests without a virtual key. - Extra LLM Proxies are removed: only your default proxy remains. Requests to another proxy's ID get
404, so point those clients at the default proxy. - Sharing fields in the API are rejected with
400:scope,teams,users,visibility,teamIds, andrestricted. Sharing is now permission grants. Update scripts that set these fields, and review who can use each agent, gateway, and MCP server. - Team and organization gateway tokens become service accounts with the same token value. The organization token reaches only gateways shared with the whole organization. Check them under Settings → Service Accounts, and grant access where a client lost it.
- Terraform provider 2.x does not work with v1.4, and 3.x does not work with v1.3. After the upgrade, move to 3.x with its migration guide.
- API clients of
GET /api/agents/optionsandGET /api/projectsnow get pages:{ data, pagination }./api/tokensis removed. - Task MCP tools are renamed:
start_istask start_, and the otherrun *_tasktools follow. Update prompts and clients that call them.
Behavior Changes
- OAuth token rate limit. The token endpoint allows 100 requests per minute per client IP. Behind an ingress, every client shares one IP: set
ARCHESTRA_to your load balancer's addresses.TRUST_ PROXY - MCP server image updates. Servers on a
:latestor untagged image restart onto the new build when the tag moves, checked every 15 minutes. Pin image tags, or setARCHESTRA_ORCHESTRATOR_MCP_IMAGE_UPDATE_CHECK_INTERVAL_MINUTES=0. - Manual tool mode. Agents and MCP gateways in Manual mode get Progressive tool loading: clients see
search_andtools run_instead of the full list. Turn it off where a client needs every tool up front.tool - Code Sandbox Python. Sandboxes run Python 3.14, up from 3.12. Fix commands that use modules removed since 3.12, such as
cgi, or packages without 3.14 wheels. - Agent Runtime. It needs the Agent Sandbox controller in your cluster. If you use Agent Runtime, see Cluster Prerequisites.
- Image registry. Companion and agent images publish to
ghcr.io/archestra-ai; the platform image stays atarchestra/platform. Update image mirrors and registry overrides.
Before You Upgrade
- Record everything under Deleted in v1.4.
- Pick the latest v1.4 release from GitHub Releases. Use v1.4.33 or later: it fixes access that earlier v1.4 releases got wrong after the conversion.
- With Helm, update
values.yaml. See Helm Values. - Update your environment variables. See Environment Variables.
- With Argo CD or Flux, pause auto-sync. It would restart the v1.3 pods you stop during the upgrade.
- Plan downtime. Nothing serves requests from the moment you stop v1.3 until v1.4 reports ready.
Upgrade With Helm
These commands assume the release archestra-platform in the namespace archestra, as in Helm Deployment, with the bundled PostgreSQL.
-
Note your web and worker replica counts, then stop v1.3 and wait until its pods are gone:
bashkubectl get deployment archestra-platform archestra-platform-worker -n archestra kubectl scale deployment archestra-platform archestra-platform-worker -n archestra --replicas=0 kubectl wait pod -n archestra --for=delete --timeout=5m \ -l 'app.kubernetes.io/instance=archestra-platform,app.kubernetes.io/component in (web,worker)'v1.3 and v1.4 must not run against the database at the same time.
-
Back up the database while nothing writes to it. With an external database, use your own backup instead.
bashPGPASS=$(kubectl get secret archestra-platform-postgresql -n archestra -o jsonpath='{.data.password}' | base64 -d) kubectl exec -n archestra archestra-platform-postgresql-0 -- \ env PGPASSWORD="$PGPASS" pg_dump -U archestra -d archestra_dev -Fc > archestra-v1.3.dump -
Upgrade the chart. Helm runs the database migrations before it starts v1.4.
bashexport ARCHESTRA_VERSION="1.4.36" # x-release-please-version helm upgrade archestra-platform \ oci://ghcr.io/archestra-ai/helm-charts/archestra-platform \ --version "$ARCHESTRA_VERSION" --namespace archestra \ --values values.yaml --timeout 30mDo not add
--atomic,--rollback-on-failure, or--reuse-values. The first two put v1.3 back on a migrated database. The last keeps the v1.3 image tag. -
Start v1.4 with the replica counts you noted (
1below), and wait for it:bashkubectl scale deployment archestra-platform archestra-platform-worker -n archestra --replicas=1 kubectl rollout status deployment archestra-platform -n archestra --timeout=30m kubectl rollout status deployment archestra-platform-worker -n archestra --timeout=15mWith autoscaling on, scale the web Deployment to your
minReplicas: the autoscaler does not start it from zero. On its first start, v1.4 converts v1.3 sharing into permission grants and reports not ready until it finishes. The worker starts after the web pod is ready. -
Sign in, then recreate what you recorded under Deleted in v1.4.
If a migration fails, Helm deletes the migration Job and its logs. To keep them, follow the logs from a second terminal during the upgrade: kubectl logs -n archestra -f job/archestra-platform-migrate. Never start v1.3 against the migrated database: roll back instead.
Upgrade With Docker
The v1.4 container migrates the database when it starts. It also rebuilds its embedded Kubernetes cluster, so your MCP servers redeploy and lose files stored inside them.
-
Find the container with
docker ps, stop it, and back up both volumes:bashdocker stop --time 120 <container> for volume in archestra-postgres-data archestra-app-data; do docker run --rm -v "$volume":/data -v "$PWD":/backup alpine \ tar czf "/backup/$volume-v1.3.tgz" -C /data . done docker rm <container> -
Start v1.4 with the same volumes. Pin the version:
latestcan be a release candidate.bashdocker run \ -p 127.0.0.1:9000:9000 -p 127.0.0.1:3000:3000 \ -e ARCHESTRA_QUICKSTART=true \ -v /var/run/docker.sock:/var/run/docker.sock \ -v archestra-postgres-data:/var/lib/postgresql/data \ -v archestra-app-data:/app/data \ archestra/platform:1.4.36 # x-release-please-version -
Open http://localhost:3000, sign in, then recreate what you recorded under Deleted in v1.4.
Helm Values
A v1.3 values file renders with the v1.4 chart, but these keys need changes:
archestra.imageTag: delete it, or set it to the v1.4 version. A values file fromhelm show valuespins1.3.81, which keeps v1.3 running under the v1.4 chart.archestra.worker.nodeSelectorandarchestra.worker.tolerations: delete them if they are{}or[]. In v1.4 an empty value clears the sharedarchestra.*value instead of inheriting it.archestra.terminationGracePeriodSeconds: delete it to derive it from the shutdown settings. A value below that budget, 120 seconds by default, fails the upgrade.archestra.worker.podAnnotations: removed. Usearchestra.podAnnotations.archestra.renderer.*andarchestra.orchestrator.mcpIdleHibernationEnabled: removed. Delete them.
If you manage the Role yourself (rbac.create: false), add the rules the v1.4 chart adds for events, persistent volume claims, and Agent Sandbox resources.
Environment Variables
Remove these v1.3 variables, or move them to their replacement:
ARCHESTRA_: removed. Agent Runtime turns on when the cluster has the Agent Sandbox controller.AGENT_ RUNTIME_ ENABLED ARCHESTRA_: useAGENT_ RUNTIME_ BASE_ IMAGE ARCHESTRA_andAGENT_ RUNTIME_ IMAGE_ REGISTRY ARCHESTRA_.AGENT_ RUNTIME_ IMAGE_ TAG ARCHESTRA_: workspaces are persistent volumes. Size them withAGENT_ RUNTIME_ EPHEMERAL_ STORAGE_ LIMIT ARCHESTRA_.AGENT_ RUNTIME_ WORKSPACE_ STORAGE_ SIZE ARCHESTRA_,PLUGINS_ ENABLED ARCHESTRA_, andMCP_ SERVER_ ALERTING_ ENABLED ARCHESTRA_: removed. Plugins, MCP server alerts, and connector permission sync are always available, so settingKNOWLEDGE_ BASE_ AUTO_ SYNC_ PERMISSIONS_ ENABLED falseno longer turns them off.ARCHESTRA_andMCP_ SKILLS_ ENABLED ARCHESTRA_: removed. These followORCHESTRATOR_ MCP_ IDLE_ HIBERNATION_ ENABLED ARCHESTRA_.BETA ARCHESTRA_: removed with app recordings.APP_ RECORDING_ RENDERER_ URL
Roll Back
Going back to v1.3 means restoring the backup. A helm rollback or image change alone starts v1.3 on a database it cannot read.
-
Stop v1.4 the same way you stopped v1.3. Its connections block the restore.
-
Replace the database with the backup. This drops the tables v1.4 created, so it runs as the PostgreSQL superuser:
bashPGSUPER=$(kubectl get secret archestra-platform-postgresql -n archestra -o jsonpath='{.data.postgres-password}' | base64 -d) kubectl exec -i -n archestra archestra-platform-postgresql-0 -- \ env PGPASSWORD="$PGSUPER" pg_restore -U postgres -d postgres --clean --if-exists --create < archestra-v1.3.dump -
Run
helm rollback archestra-platform <v1.3 revision> -n archestra, then scale the web and worker Deployments back up.helm history archestra-platform -n archestralists the revisions.
With Docker, stop and remove the v1.4 container, replace both volumes with the archives, and start archestra/platform:1.3.81 with the same docker run command:
for volume in archestra-postgres-data archestra-app-data; do
docker volume rm "$volume"
docker run --rm -v "$volume":/data -v "$PWD":/backup alpine \
tar xzf "/backup/$volume-v1.3.tgz" -C /data
done