swarm_node

The swarm_node domain has 12 actions. On the meta surface they are all reached through arcane_swarm_node; on the individual surface each one is its own tool; on the dynamic surface run them with arcane_execute_action and the canonical ID.

Summary

Action	Title	Kind
swarm_node.agent_binding_delete	Detach a visible environment from a swarm node	destructive
swarm_node.agent_binding_set	Attach a visible environment to a swarm node	write
swarm_node.agent_deployment_create	Get swarm node agent deployment snippets	destructive
swarm_node.agent_deployment_delete	Remove a dedicated swarm node agent registration	destructive
swarm_node.agents_reconcile	Reconcile swarm node agent bindings	write
swarm_node.delete	Delete swarm node	destructive
swarm_node.demote	Demote swarm node	destructive
swarm_node.get	Get swarm node	read
swarm_node.list	List swarm nodes	read
swarm_node.promote	Promote swarm node	write
swarm_node.tasks	List tasks for a swarm node	read
swarm_node.update	Update swarm node	write

Actions

swarm_node.agent_binding_delete

Detach a visible environment from a swarm node

• Kind: destructive — requires confirm: true
• Required parameters: nodeId
• Meta tool: arcane_swarm_node with "action": "agent_binding_delete"
• Individual tool: arcane_swarm_node_agent_binding_delete
• Arcane route: DELETE /api/environments/{id}/swarm/nodes/{nodeId}/agent/binding
• Operation ID: delete-swarm-node-agent-binding
• Usage: Clears the visible environment bound to the node (nodeId from swarm_node.list, on the manager’s environment). The environment itself, its agent and token are kept, and legacy hidden registrations are not touched (use swarm_node.agent_deployment_delete). Succeeds even when nothing was bound.
• Related actions: swarm_node.get, swarm_node.agent_binding_set, swarm_node.agent_deployment_delete

swarm_node.agent_binding_set

Attach a visible environment to a swarm node

• Kind: write
• Required parameters: nodeId, body
• Meta tool: arcane_swarm_node with "action": "agent_binding_set"
• Individual tool: arcane_swarm_node_agent_binding_set
• Arcane route: PUT /api/environments/{id}/swarm/nodes/{nodeId}/agent/binding
• Operation ID: put-swarm-node-agent-binding
• Usage: Records that an existing Arcane environment is the agent of this node. nodeId from swarm_node.list, environmentId is the manager’s environment, and the environment to attach goes in body.environmentId (from environment.list or the node’s agent.candidates). Arcane first asks that environment for its swarm identity, so it must be visible, enabled, reachable and report exactly this node ID, else 400. Set body.rebind to move a binding (the environment is bound elsewhere, or the node already has one), body.replaceDeployment to also delete a legacy hidden agent of the node. Returns the node with its updated agent.
• Related actions: swarm_node.list, environment.list, swarm_node.agent_binding_delete, swarm_node.agents_reconcile, swarm_node.get

swarm_node.agent_deployment_create

Get swarm node agent deployment snippets

• Kind: destructive — only when rotate is true; those calls require confirm: true, the others do not
• Required parameters: nodeId
• Meta tool: arcane_swarm_node with "action": "agent_deployment_create"
• Individual tool: arcane_swarm_node_agent_deployment_create
• Arcane route: POST /api/environments/{id}/swarm/nodes/{nodeId}/agent/deployment
• Operation ID: get-swarm-node-agent-deployment
• Usage: Registers (or reuses) an environment bound to the node and returns docker run / compose snippets for its agent. The environment it creates is a normal visible environment: remove it with environment.delete. nodeId from swarm_node.list, needs swarm:nodes. A node that already has a binding reuses that environment and its token. rotate=true issues a new token and deletes the old one, cutting off an agent still using it, and only that needs confirm=true. The result holds dockerRun, dockerCompose, environmentId and the node’s agent status.
• Related actions: swarm_node.list, swarm_node.agent_binding_delete, environment.delete, swarm_node.get

swarm_node.agent_deployment_delete

Remove a dedicated swarm node agent registration

• Kind: destructive — requires confirm: true
• Required parameters: nodeId
• Meta tool: arcane_swarm_node with "action": "agent_deployment_delete"
• Individual tool: arcane_swarm_node_agent_deployment_delete
• Arcane route: DELETE /api/environments/{id}/swarm/nodes/{nodeId}/agent/deployment
• Operation ID: delete-swarm-node-agent-deployment
• Usage: Removes only a legacy hidden (dedicated) agent registration of the node. It leaves the visible environment that agent_deployment_create creates. nodeId from swarm_node.list. Succeeds even when the node has no hidden registration. To undo agent_deployment_create, use environment.delete with its environmentId.
• Related actions: environment.delete, swarm_node.agent_binding_delete, swarm_node.get

swarm_node.agents_reconcile

Reconcile swarm node agent bindings

• Kind: write
• Required parameters: none
• Meta tool: arcane_swarm_node with "action": "agents_reconcile"
• Individual tool: arcane_swarm_node_agents_reconcile
• Arcane route: POST /api/environments/{id}/swarm/nodes/agents/reconcile
• Operation ID: reconcile-swarm-node-agents
• Usage: Binds every node that exactly one visible environment reports as its own to that environment. Ambiguous and mismatched nodes are left as they are. Call on the manager’s environment (Swarm manager only, needs swarm:nodes). Nodes already bound are not changed. results lists every node with nodeId, state, environmentId and, when still unbound, candidates to resolve with swarm_node.agent_binding_set.
• Related actions: swarm_node.list, swarm_node.agent_binding_set, swarm_node.get

swarm_node.delete

Delete swarm node

• Kind: destructive — requires confirm: true
• Required parameters: nodeId
• Meta tool: arcane_swarm_node with "action": "delete"
• Individual tool: arcane_swarm_node_delete
• Arcane route: DELETE /api/environments/{id}/swarm/nodes/{nodeId}
• Operation ID: delete-swarm-node
• Usage: A node that is not down is refused unless force is true, and the removed node’s daemon still believes it is in the swarm until it leaves. nodeId from swarm_node.list. Swarm manager only, needs swarm:nodes. The clean order is swarm.leave on the node’s own environment, wait for status down in swarm_node.get, then delete. An environment bound to the node stays bound (detach it with swarm_node.agent_binding_delete).
• Related actions: swarm_node.list, swarm_node.get, swarm.leave, swarm_node.agent_binding_delete

swarm_node.demote

Demote swarm node

• Kind: destructive — requires confirm: true
• Required parameters: nodeId
• Meta tool: arcane_swarm_node with "action": "demote"
• Individual tool: arcane_swarm_node_demote
• Arcane route: POST /api/environments/{id}/swarm/nodes/{nodeId}/demote
• Operation ID: demote-swarm-node
• Usage: Turns a manager back into a worker (role=worker through a node update). nodeId from swarm_node.list, Swarm manager only, needs swarm:nodes. Docker refuses to demote the last manager. role shows worker at once (it is the node spec), and managerStatus empties in swarm_node.get once Docker has finished.
• Related actions: swarm_node.list, swarm_node.get, swarm_node.promote

swarm_node.get

Get swarm node

• Kind: read
• Required parameters: nodeId
• Meta tool: arcane_swarm_node with "action": "get"
• Individual tool: arcane_swarm_node_get
• Arcane route: GET /api/environments/{id}/swarm/nodes/{nodeId}
• Operation ID: get-swarm-node
• Usage: nodeId from swarm_node.list, on the manager’s environment. Fails when the node is gone. Returns the same summary as the list (role, availability, status, reachability, labels, engineVersion, agent binding). Use it to confirm update, promote and demote: role, availability and labels show the node spec and change at once, while managerStatus and reachability follow when Docker has finished the role change.
• Related actions: swarm_node.list, swarm_node.tasks, swarm_node.update

swarm_node.list

List swarm nodes

• Kind: read
• Required parameters: none
• Meta tool: arcane_swarm_node with "action": "list"
• Individual tool: arcane_swarm_node_list
• Arcane route: GET /api/environments/{id}/swarm/nodes
• Operation ID: list-swarm-nodes
• Usage: The starting point for every nodeId: call it on the swarm manager’s environment (Swarm manager only: refused outside a swarm or on a worker). Each node has id, hostname, role, availability, status (ready/down), managerStatus (leader/manager), managerAddress, reachability, labels, engineVersion and agent (which Arcane environment covers the node: state, environmentId, bindingKind, candidates). search matches hostname, id, role, status or availability. Sort by hostname, role, status, availability, created or updated. Paginate with start and limit (default 20).
• Related actions: swarm_node.get, swarm_node.tasks, swarm_node.update, swarm.join_tokens

swarm_node.promote

Promote swarm node

• Kind: write
• Required parameters: nodeId
• Meta tool: arcane_swarm_node with "action": "promote"
• Individual tool: arcane_swarm_node_promote
• Arcane route: POST /api/environments/{id}/swarm/nodes/{nodeId}/promote
• Operation ID: promote-swarm-node
• Usage: Makes a worker a manager (role=manager through a node update). nodeId from swarm_node.list, Swarm manager only, needs swarm:nodes. Joining the managers takes a moment: role shows manager at once, so poll swarm_node.get until reachability is reachable. Keep an odd number of managers, since quorum needs a majority of them.
• Related actions: swarm_node.list, swarm_node.get, swarm_node.demote

swarm_node.tasks

List tasks for a swarm node

• Kind: read
• Required parameters: nodeId
• Meta tool: arcane_swarm_node with "action": "tasks"
• Individual tool: arcane_swarm_node_tasks
• Arcane route: GET /api/environments/{id}/swarm/nodes/{nodeId}/tasks
• Operation ID: list-swarm-node-tasks
• Usage: nodeId from swarm_node.list. Swarm manager only. Lists the tasks Docker has scheduled on that node, including finished and shut-down ones still in task history (compare desiredState and currentState): id, serviceName, slot, currentState, error, containerId. search matches task name, service name, node name, id or state. Sort by service, node, state, created or updated. Use swarm_service.tasks for one service across nodes.
• Related actions: swarm_node.list, swarm_task.list, swarm_service.tasks

swarm_node.update

Update swarm node

• Kind: write
• Required parameters: nodeId
• Meta tool: arcane_swarm_node with "action": "update"
• Individual tool: arcane_swarm_node_update
• Arcane route: PATCH /api/environments/{id}/swarm/nodes/{nodeId}
• Operation ID: update-swarm-node
• Usage: nodeId from swarm_node.list. Swarm manager only, needs swarm:nodes. Changes only the fields given: availability (active, pause or drain, where drain moves the node’s tasks elsewhere), role (manager or worker), name, labels. labels replace the whole label set (pass the current ones from swarm_node.get plus yours, {} clears them). version defaults to the node’s current version. Returns only a message: check with swarm_node.get.
• Related actions: swarm_node.get, swarm_node.list, swarm_node.promote, swarm_node.demote