swarm_service

The swarm_service domain has 9 actions. On the meta surface they are all reached through arcane_swarm_service; 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_service.create	Create swarm service	write
swarm_service.delete	Delete swarm service	destructive
swarm_service.get	Get swarm service	read
swarm_service.list	List swarm services	read
swarm_service.logs	Get Swarm service logs	read
swarm_service.rollback	Rollback a swarm service	destructive
swarm_service.scale	Scale a swarm service	write
swarm_service.tasks	List tasks for a swarm service	read
swarm_service.update	Update swarm service	destructive

Actions

swarm_service.create

Create swarm service

• Kind: write
• Required parameters: spec
• Meta tool: arcane_swarm_service with "action": "create"
• Individual tool: arcane_swarm_service_create
• Arcane route: POST /api/environments/{id}/swarm/services
• Operation ID: create-swarm-service
• Usage: spec is a Docker ServiceSpec with Docker’s field names. Duration fields (StopGracePeriod, healthcheck intervals, RestartPolicy/UpdateConfig delays, …) are integer nanoseconds. Returns the new service’s id. Follow its tasks with swarm_service.tasks.
• Related actions: swarm_service.update, swarm_service.tasks

swarm_service.delete

Delete swarm service

• Kind: destructive — requires confirm: true
• Required parameters: serviceId
• Meta tool: arcane_swarm_service with "action": "delete"
• Individual tool: arcane_swarm_service_delete
• Arcane route: DELETE /api/environments/{id}/swarm/services/{serviceId}
• Operation ID: delete-swarm-service
• Usage: serviceId (ID or name) from swarm_service.list. Removes the service and stops all its tasks. This cannot be undone. Docker refuses to delete configs and secrets while a service references them, so delete the service first. To remove a whole stack use swarm_stack.delete instead. Needs a Swarm manager and the swarm:services permission.
• Related actions: swarm_service.list, swarm_stack.delete, swarm_config.delete, swarm_secret.delete

swarm_service.get

Get swarm service

• Kind: read
• Required parameters: serviceId
• Meta tool: arcane_swarm_service with "action": "get"
• Individual tool: arcane_swarm_service_get
• Arcane route: GET /api/environments/{id}/swarm/services/{serviceId}
• Operation ID: get-swarm-service
• Usage: serviceId (ID or name) from swarm_service.list. Returns the full Docker spec and version.Index (both needed by swarm_service.update), endpoint (published ports and virtual IPs), updateStatus (state of the last update or rollback, absent if none), the hostnames of nodes running its tasks (filled only when serviceId is the ID, empty when called by name), and networkDetails and mounts enriched with network and volume details.
• Related actions: swarm_service.list, swarm_service.update, swarm_service.tasks, swarm_service.logs

swarm_service.list

List swarm services

• Kind: read
• Required parameters: none
• Meta tool: arcane_swarm_service with "action": "list"
• Individual tool: arcane_swarm_service_list
• Arcane route: GET /api/environments/{id}/swarm/services
• Operation ID: list-swarm-services
• Usage: The starting point for every serviceId: returns a page of service summaries (id, name, image, mode, replicas, runningReplicas, ports, stackName, nodes, networks, mounts, labels). search matches name, image, ID, stack name, mode, network or node names. Sort by name, image, mode, replicas, created or updated. Paginate with start and limit (default 20). Needs an environment that is a Swarm manager. Use swarm_stack.services for one stack’s services.
• Related actions: swarm_service.get, swarm_service.tasks, swarm_service.create, swarm_stack.services, swarm.status

swarm_service.logs

Get Swarm service logs

Return the recent log lines of a Swarm service across its tasks, optionally listening for new lines for a few seconds

• Kind: read
• Required parameters: serviceId
• Meta tool: arcane_swarm_service with "action": "logs"
• Individual tool: arcane_swarm_service_logs
• Arcane route: GET /api/environments/{id}/ws/swarm/services/{serviceId}/logs (WebSocket)
• Operation ID: ws-swarm-service-logs
• Usage: serviceId is the service ID or name from swarm_service.list (a stack’s services are named <stack>_<service>, see swarm_stack.services). Merges the output of all the service’s tasks: returns the last tail lines (default 100, or ‘all’) in lines. Narrow with since, add timestamps, or set follow to keep listening for up to seconds. Use swarm_service.tasks to see which task or node failed when the logs are empty.
• Related actions: swarm_service.list, swarm_service.tasks, swarm_service.get, swarm_stack.services

swarm_service.rollback

Rollback a swarm service

• Kind: destructive — requires confirm: true
• Required parameters: serviceId
• Meta tool: arcane_swarm_service with "action": "rollback"
• Individual tool: arcane_swarm_service_rollback
• Arcane route: POST /api/environments/{id}/swarm/services/{serviceId}/rollback
• Operation ID: rollback-swarm-service
• Usage: Reverts the service to its previous spec (Docker’s PreviousSpec), as docker service rollback. serviceId from swarm_service.list. The previous spec is the one before the latest change, and swarm_service.scale counts as a change, so a rollback right after a scale undoes the scale. Runs in the background: poll swarm_service.get until updateStatus.State is rollback_completed. Needs a Swarm manager and the swarm:services permission.
• Related actions: swarm_service.get, swarm_service.update, swarm_service.tasks

swarm_service.scale

Scale a swarm service

• Kind: write
• Required parameters: serviceId, replicas
• Meta tool: arcane_swarm_service with "action": "scale"
• Individual tool: arcane_swarm_service_scale
• Arcane route: POST /api/environments/{id}/swarm/services/{serviceId}/scale
• Operation ID: scale-swarm-service
• Usage: serviceId from swarm_service.list. replicas is the new desired count (0 stops all tasks). Only replicated services (and replicated jobs, where it sets TotalCompletions) can be scaled, and a global service is refused. Arcane rewrites the spec with the new count, so it becomes the spec that swarm_service.rollback returns to. Tasks start or stop in the background: check runningReplicas in swarm_service.list or swarm_service.tasks.
• Related actions: swarm_service.list, swarm_service.tasks, swarm_service.get

swarm_service.tasks

List tasks for a swarm service

• Kind: read
• Required parameters: serviceId
• Meta tool: arcane_swarm_service with "action": "tasks"
• Individual tool: arcane_swarm_service_tasks
• Arcane route: GET /api/environments/{id}/swarm/services/{serviceId}/tasks
• Operation ID: list-swarm-service-tasks
• Usage: serviceId from swarm_service.list. Returns a page of the service’s tasks, including stopped and failed ones from the task history: id, name, slot, nodeId/nodeName, desiredState, currentState, error, image and containerId. Use it to see where replicas run and why they fail. search matches task, service or node name, ID or state. Sort by service, node, state, created or updated. limit defaults to 20.
• Related actions: swarm_service.list, swarm_service.logs, swarm_node.get, swarm_task.list, swarm_node.tasks

swarm_service.update

Update swarm service

• Kind: destructive — requires confirm: true
• Required parameters: serviceId, spec, version
• Meta tool: arcane_swarm_service with "action": "update"
• Individual tool: arcane_swarm_service_update
• Arcane route: PUT /api/environments/{id}/swarm/services/{serviceId}
• Operation ID: update-swarm-service
• Usage: Replaces the whole spec: pass the spec from swarm_service.get with your changes, and its version.Index (0 uses the current version).
• Related actions: swarm_service.get, swarm_service.rollback