Swarm Cluster
Initialize, join, unlock, and update a Docker Swarm cluster.
Swarm → Cluster lists every agent you can read with its Swarm role (Manager, Worker, or Not initialized) and the cluster ID for managers. Click Inspect on a row to open that agent’s cluster panel.
Initialize a Swarm
Section titled “Initialize a Swarm”Use this when an agent isn’t in a Swarm yet. Arcane then includes it in the rest of the Swarm workspace.
- Open Swarm → Cluster and click Inspect on the agent.
- Optional: under Initialize Cluster, open Advanced settings. The defaults suit a local or single-network cluster.
- Click Initialize.
Advanced settings:
| Field | What it does |
|---|---|
| Listen address | Address and port the Swarm manager listens on for cluster traffic. |
| Advertise address | Address other nodes use to reach this manager. Set it when the host has several network interfaces. |
| Swarm spec JSON | A full Swarm spec as a JSON object, for settings not covered by the other fields. |
| Auto-lock managers | Encrypts manager data so a restarted manager stays locked until you enter the unlock key. |
| Force new cluster | Creates a new single-manager cluster from this node’s existing Swarm state. Use it to recover a cluster that lost its managers. |
Join an existing Swarm
Section titled “Join an existing Swarm”To add an agent to a running cluster as a manager or worker:
- Open Swarm → Cluster and click Inspect on the agent.
- Under Join Existing Cluster, enter the remote manager addresses (comma separated), the join token, and optional listen and advertise addresses.
- Click Join.
Easy Join remote agents
Section titled “Easy Join remote agents”Easy Join adds other Remote Agents to a manager’s cluster without copying addresses or join tokens.
- Click Easy Join on a manager’s row under Swarm → Cluster, or on a Remote Agent’s detail page or row menu.
- Select each target. Only enabled, online agents not already linked to a node of this cluster are offered.
- For each target, choose worker or manager and an availability mode.
- Optional: set listen, advertise, or data-path addresses per target. Blank manager addresses use the ones Arcane finds in the cluster. Any you enter must be reachable from every selected host.
- Confirm.
Join tokens are never shown. Each target gets its own result in Join results, and one failure doesn’t undo the others:
| Result | Meaning |
|---|---|
| Joined and verified | The host joined and Arcane linked the agent to its Swarm node. |
| Already a member and verified | The host was already in this cluster. Arcane linked it without rejoining. |
| Joined; verification is still pending | The host joined, but Arcane couldn’t confirm the node in time. Opening Nodes finishes the link later. |
A host active in a different cluster is rejected; Arcane doesn’t force it to leave. Easy Join needs swarm:join on the manager and every target. The Cluster page’s Easy Join button also needs swarm-nodes:list and swarm:unlock on the manager.
Leave a cluster
Section titled “Leave a cluster”In the cluster panel, click Leave Cluster to remove that node. Select Force leave if a normal leave fails.
Unlock a locked cluster
Section titled “Unlock a locked cluster”With Auto-lock managers on, a restarted manager keeps the cluster locked until you unlock it.
- Open Swarm → Cluster and click Inspect on a manager.
- Enter the unlock key.
- Click Unlock.
Rotate join tokens and the unlock key
Section titled “Rotate join tokens and the unlock key”A manager’s cluster panel shows and can rotate the worker join token, manager join token, and manager unlock key. Treat them like passwords. Rotating one invalidates the old value.
Update the cluster spec
Section titled “Update the cluster spec”- Under Update Swarm Spec, click Load current spec.
- Edit the JSON.
- Click Update Spec.
Cluster actions need a Swarm manager agent and matching permissions. See Docker Swarm for the rules.