Skip to content

Migrate to 3.0

Upgrade an Arcane 2.x installation to Arcane 3.0.

  1. 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.
  2. Resolve job runs marked Needs attention. 3.0 removes Resolve after review.
  3. Back up your data. Back up the Arcane database, /app/data, your Compose and env files, and your projects directory.
  4. Update your Compose files. Apply the Compose changes to the Manager and every agent.
  5. Restart the Manager. Run docker compose down, then docker compose up -d. If it stops, the log lists each variable to rename.
  6. Restart every agent. Former direct agents also need to re-enroll. See Agents.
  7. Check roles and notifications. See After upgrading.
  8. Update your scripts. Upgrade arcane-cli to 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.

Make these four changes in every Compose file before starting 3.0:

  1. Image. If you pull from GHCR as ghcr.io/getarcaneapp/arcane or ghcr.io/getarcaneapp/arcane-headless, switch to ghcr.io/getarcaneapp/manager and ghcr.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.
  2. Prefix. Add ARCANE_ to every Arcane environment variable. See Environment variables.
  3. Removed variables. Delete JWT_SECRET, EDGE_MUX_DISABLED, and EDGE_TRANSPORT=poll.
  4. Inverted variables. Replace ANALYTICS_DISABLED=true with ARCANE_ANALYTICS_ENABLED=false, and UPDATE_CHECK_DISABLED=true with ARCANE_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=1000

Agent:

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_xxxxxxxx

Former direct agents (AGENT_MODE=true) need a new install command. See Agents.

  • 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.

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

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
  • _FILE variants also require the ARCANE_ prefix.
  • Setting a legacy variable without its ARCANE_ replacement stops startup with legacy environment variables are no longer read and 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, and OTEL_*.
  • JWT_SECRET, ANALYTICS_DISABLED, UPDATE_CHECK_DISABLED, and VOLUME_WORKSPACE_MAX_DEPTH are 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=true still 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.

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_* and EDGE_* names stop startup with rename X to ARCANE_AGENT_*.
  • ARCANE_AGENT_TRANSPORT accepts auto, grpc, or websocket. Anything else stops startup.
  • AGENT_MODE=true or ARCANE_AGENT_MODE=true without ARCANE_AGENT=true stops startup with direct agents were removed in v3.
  • Existing edge:// agents become agent:// automatically. Nothing to re-enroll.
  • ARCANE_AGENT_TOKEN takes 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:

  1. Open Agents and select the agent.
  2. Open Connection & Agent and click Generate Enrollment Token.
  3. Copy the install command.
  4. On the agent host, remove the old container and run the new command.

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}/gitops to /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:list or environments:read in addition to settings:*, environment-settings:*, or notifications:*.
  • 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 has env_file: .env.
  • The Security overview shows a single patch-priority score across all agents.

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.

  • Every /api/environments/... route moved to /api/agents/.... The old paths no longer exist.
  • Actions use the ?action= query parameter.
  • Resource updates use PATCH instead of PUT.
  • Some list endpoints return -1 for totals unless you pass includeTotal=true.
  • Notification settings moved from /api/environments/{id}/notifications/settings to /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.

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:update adds containers:read and containers: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 permissions prints every permission and the endpoints it covers as JSON.

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 * * * becomes 0 2 * * *.
  • Descriptors like @daily and @every 6h still 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.

  • The GHCR-only image aliases ghcr.io/getarcaneapp/arcane and ghcr.io/getarcaneapp/arcane-headless. Use ghcr.io/getarcaneapp/manager and ghcr.io/getarcaneapp/agent. Docker Hub and Quay never had these aliases.
  • Resolve after review on job runs.
  • The Previews tab.