Migrate to 3.0
Upgrade an Arcane 2.x installation to Arcane 3.0.
Upgrade
Section titled “Upgrade”- Upgrade to 2.17.3. Start the Manager and every agent on it once. Older databases stop 3.0 with
upgrade to Arcane v2.17.1 first. - Resolve job runs marked Needs attention. 3.0 removes Resolve after review.
- Back up your data. Back up the Arcane database,
/app/data, your Compose and env files, and your projects directory. - Update your Compose files. Apply the Compose changes to the Manager and every agent.
- Restart the Manager. Run
docker compose down, thendocker compose up -d. If it stops, the log lists each variable to rename. - Restart every agent. Former direct agents also need to re-enroll. See Agents.
- Check roles and notifications. See After upgrading.
- Update your scripts. Upgrade
arcane-clito 3.0, then apply the CLI changes and API changes.
To go back to 2.x, restore the backup from step 3. See Downgrade from 3.0 to 2.x.
Compose changes
Section titled “Compose changes”Make these four changes in every Compose file before starting 3.0:
- Image. If you pull from GHCR as
ghcr.io/getarcaneapp/arcaneorghcr.io/getarcaneapp/arcane-headless, switch toghcr.io/getarcaneapp/managerandghcr.io/getarcaneapp/agent. Those two names were GHCR-only aliases. Docker Hub (getarcaneapp/manager) and Quay (quay.io/getarcaneapp/manager) already use the new names, so only the tag changes there. - Prefix. Add
ARCANE_to every Arcane environment variable. See Environment variables. - Removed variables. Delete
JWT_SECRET,EDGE_MUX_DISABLED, andEDGE_TRANSPORT=poll. - Inverted variables. Replace
ANALYTICS_DISABLED=truewithARCANE_ANALYTICS_ENABLED=false, andUPDATE_CHECK_DISABLED=truewithARCANE_UPDATE_CHECK_ENABLED=false. The old names are ignored, so analytics and update checks turn back on if you skip this.
Manager:
services: arcane: image: ghcr.io/getarcaneapp/arcane:latest image: ghcr.io/getarcaneapp/manager:v3 environment: - APP_URL=https://arcane.example.com - ENCRYPTION_KEY=<your-encryption-key> - PROJECTS_DIRECTORY=/opt/docker - JWT_SECRET=<your-jwt-secret> - EDGE_MUX_DISABLED=true - ARCANE_APP_URL=https://arcane.example.com - ARCANE_ENCRYPTION_KEY=<your-encryption-key> - ARCANE_PROJECTS_DIRECTORY=/opt/docker - PUID=1000 - PGID=1000Agent:
services: arcane-agent: image: ghcr.io/getarcaneapp/arcane-headless:latest image: ghcr.io/getarcaneapp/agent:v3 environment: - EDGE_AGENT=true - EDGE_TRANSPORT=poll - MANAGER_API_URL=https://arcane.example.com - AGENT_TOKEN=arc_xxxxxxxx - ARCANE_AGENT=true - ARCANE_MANAGER_API_URL=https://arcane.example.com - ARCANE_AGENT_TOKEN=arc_xxxxxxxxFormer direct agents (AGENT_MODE=true) need a new install command. See Agents.
After upgrading
Section titled “After upgrading”- Check custom roles. Saved roles and API keys migrate on startup. Review them if you script against permission names or relied on the built-in Deployer role. See Permissions.
- Set up notifications again under System → Notifications. Providers are now global to the Manager.
Breaking changes
Section titled “Breaking changes”Everything that changed in 3.0, for reference. The steps above cover what you must do.
| What breaks | Details |
|---|---|
Arcane variables need the ARCANE_ prefix. Old names stop startup. |
Environment variables |
GHCR’s arcane and arcane-headless image aliases are gone. Use manager and agent. |
Other removals |
| Direct agents are gone. Every remote host is an agent. | Agents |
Edge agents are now just agents. EDGE_* variables are renamed. |
Agents |
| The polling transport is gone. | Agents |
The legacy edge tunnel and EDGE_MUX_DISABLED are gone. |
Agents |
| Resolve after review on job runs is gone. | Other removals |
| Cron schedules use five fields. Seconds are gone. | Job schedules |
| The environment switcher is gone. Pages show every agent. | All agents |
| Old detail-page bookmarks don’t resolve. | All agents |
The CLI environments command is now agents. Flags and config keys were removed. |
CLI changes |
API routes under /api/environments moved to /api/agents. |
API changes |
| API actions, updates, and totals changed. | API changes |
| Permissions are renamed and split. Saved roles migrate on startup. | Permissions |
| Manager, agents, and CLI must all run 3.0. | Upgrade |
| Upgrade to 2.17.3 first. Older databases stop startup. | Upgrade |
Details
Section titled “Details”Environment variables are renamed
Every Arcane variable now starts with ARCANE_.
Environment variables are renamed
Every Arcane variable now starts with ARCANE_.
| 2.x | 3.0 |
|---|---|
APP_URL |
ARCANE_APP_URL |
ENCRYPTION_KEY_FILE |
ARCANE_ENCRYPTION_KEY_FILE |
EDGE_AGENT, MANAGER_API_URL, AGENT_TOKEN |
ARCANE_AGENT, ARCANE_MANAGER_API_URL, ARCANE_AGENT_TOKEN |
EDGE_* (transport, reconnect, mTLS) |
ARCANE_AGENT_* |
ANALYTICS_DISABLED=true |
ARCANE_ANALYTICS_ENABLED=false |
UPDATE_CHECK_DISABLED=true |
ARCANE_UPDATE_CHECK_ENABLED=false |
_FILEvariants also require theARCANE_prefix.- Setting a legacy variable without its
ARCANE_replacement stops startup withlegacy environment variables are no longer readand lists each variable to rename (rename X to ARCANE_X). - Third-party and standard variables are unchanged:
PUID,PGID,TZ,DOCKER_HOST,DOCKER_CONFIG,HTTP_PROXY,HTTPS_PROXY,NO_PROXY, andOTEL_*. JWT_SECRET,ANALYTICS_DISABLED,UPDATE_CHECK_DISABLED, andVOLUME_WORKSPACE_MAX_DEPTHare ignored and log a startup warning until removed. Arcane now signs session tokens with its own ML-DSA-87 key.- A settings variable now always applies and locks that setting in the UI. In 2.x it only applied with
UI_CONFIGURATION_DISABLED=true.ARCANE_UI_CONFIGURATION_DISABLED=truestill makes every setting read-only. - Invalid values stop startup. See Settings overrides.
Agents
Edge agents are now just agents. Direct agents and polling are gone.
Agents
Edge agents are now just agents. Direct agents and polling are gone.
Change these on every agent:
| 2.x | 3.0 |
|---|---|
EDGE_AGENT=true |
ARCANE_AGENT=true |
EDGE_TRANSPORT |
ARCANE_AGENT_TRANSPORT |
EDGE_RECONNECT_INTERVAL |
ARCANE_AGENT_RECONNECT_INTERVAL |
EDGE_MTLS_* |
ARCANE_AGENT_MTLS_* |
EDGE_TRANSPORT=poll |
Remove it. Use auto (default). |
EDGE_MUX_DISABLED |
Remove it. |
Health checks on port 3553 |
Remove them. |
ARCANE_EDGE_*andEDGE_*names stop startup withrename X to ARCANE_AGENT_*.ARCANE_AGENT_TRANSPORTacceptsauto,grpc, orwebsocket. Anything else stops startup.AGENT_MODE=trueorARCANE_AGENT_MODE=truewithoutARCANE_AGENT=truestops startup withdirect agents were removed in v3.- Existing
edge://agents becomeagent://automatically. Nothing to re-enroll. ARCANE_AGENT_TOKENtakes the agent’s API key, as before, or an enrollment token (arc_etkn_...). With an enrollment token, the agent registers on first start and stores the API key it gets back.
Former direct agents convert to Pending agents with the same ID, keeping webhooks, Git syncs, settings, and jobs. Re-enroll each one:
- Open Agents and select the agent.
- Open Connection & Agent and click Generate Enrollment Token.
- Copy the install command.
- On the agent host, remove the old container and run the new command.
Every page covers all agents
The environment switcher is gone.
Every page covers all agents
The environment switcher is gone.
Lists, the dashboard, topology, Swarm, Security, Git Syncs, and Podman Auto Update show resources across every readable agent, with an Agent column and filter. See Work across agents.
- The Environments page is now Agents, at
/agents. - Detail URLs require
?env=<id>, breaking 2.x bookmarks. - Git Syncs moved from
/environments/{id}/gitopsto/gitops. - Per-agent settings moved from the agent page to Settings pages, with an Applying settings for picker. See Agent settings.
- Users, roles, API keys, authentication, notifications, webhooks, backups, and diagnostics moved to System.
- Notification providers are global to the Manager instead of per agent. Set them up again under System → Notifications.
- Editing those pages requires
environments:listorenvironments:readin addition tosettings:*,environment-settings:*, ornotifications:*. - System → Webhooks lists webhooks from all agents.
- Agent colors moved to Account → Preferences.
- New projects no longer get an empty
.env, and the default Compose template no longer hasenv_file: .env. - The Security overview shows a single patch-priority score across all agents.
CLI changes
Removed flags and commands, and their replacements.
CLI changes
Removed flags and commands, and their replacements.
| Removed | Use instead |
|---|---|
environments and its environment, env, e aliases |
agents |
--env on containers create |
--env-var |
--config on admin notifications settings set |
--provider-config |
--output on templates download |
--output-file |
--disabled |
--enabled=false |
jwt_token and refresh_token in the config file |
arcane-cli auth login |
default_environment, config set environment, environments switch |
--agent <id> on each command |
--api-url, --access-token, --edge, --use-api-key on agents |
Nothing. agents create needs --name. |
Commands run across all agents by default. Mutating commands without --agent prompt for confirmation. See CLI Configuration.
API changes
Actions, PATCH updates, renamed routes, and totals.
API changes
Actions, PATCH updates, renamed routes, and totals.
- Every
/api/environments/...route moved to/api/agents/.... The old paths no longer exist. - Actions use the
?action=query parameter. - Resource updates use
PATCHinstead ofPUT. - Some list endpoints return
-1for totals unless you passincludeTotal=true. - Notification settings moved from
/api/environments/{id}/notifications/settingsto/api/notifications/settings. - System backup restore, file browsing, upload, and delete moved from
/api/backups/{id}to/api/agents/{id}/backups/{backupId}. - Check the API reference for other renamed routes.
Permissions
Renamed and split permissions, and what migrates automatically.
Permissions
Renamed and split permissions, and what migrates automatically.
Saved roles and API keys migrate on startup. Nothing to do unless you script against permission names.
Every resource now uses the same verbs: list, read, create, update, delete. Resources keep extra verbs where they have extra actions, like containers:restart.
| 2.x | 3.0 |
|---|---|
settings:read, settings:write |
settings:* (Manager) and environment-settings:* (per agent) |
containers:edit |
containers:update |
swarm:services, swarm:stacks, swarm:nodes, swarm:configs, swarm:secrets |
swarm-services:*, swarm-stacks:*, swarm-nodes:*, swarm-configs:*, swarm-secrets:* |
podman:pods, podman:quadlets, podman:kube, podman:secrets |
podman-pods:*, podman-quadlets:*, podman-kube:*, podman-secrets:* |
jobs:manage, notifications:manage, system-backups:manage, build-workspaces:manage, vulnerabilities:manage |
One permission per action, like jobs:run or notifications:test |
image-updates:check (also applied updates) |
image-updates:check and image-updates:apply |
customize:manage |
Removed. Use templates:*. |
dashboard:read |
Removed. Saved roles and API keys drop it on startup. |
- Picking a permission also adds the ones it needs. For example,
containers:updateaddscontainers:readandcontainers:list. - Built-in roles changed. Deployer loses
containers:update. - Authentication settings and the backup recovery key need a global admin.
- Remote agents check every permission themselves, the same as local. The Manager and every agent must run 3.0.
arcane permissionsprints every permission and the endpoints it covers as JSON.
Job schedules
Five-field cron instead of six.
Job schedules
Five-field cron instead of six.
- Schedules use standard five-field cron:
minute hour day month weekday. - Saved six-field schedules convert automatically. The seconds field is dropped.
- Update scripts and settings overrides:
0 0 2 * * *becomes0 2 * * *. - Descriptors like
@dailyand@every 6hstill work. - A run missed while Arcane was down runs once on startup.
- Overlapping runs of the same job wait their turn instead of being skipped.
Other removals
Image aliases, job run resolution, and the Previews tab.
Other removals
Image aliases, job run resolution, and the Previews tab.
- The GHCR-only image aliases
ghcr.io/getarcaneapp/arcaneandghcr.io/getarcaneapp/arcane-headless. Useghcr.io/getarcaneapp/managerandghcr.io/getarcaneapp/agent. Docker Hub and Quay never had these aliases. - Resolve after review on job runs.
- The Previews tab.