Check Portainer connection and authentication status.

Also reports how many endpoints Portainer knows and whether the default endpoint is a Swarm cluster — the first thing an agent needs to decide between the service-level and container-level tools.

List all Portainer environments (endpoints).

Get details of a specific Portainer environment (endpoint).

Args: endpoint_id: The ID of the endpoint to inspect

List all Portainer stacks.

Get details of a stack including its compose file content.

Credential-looking values (stack Env variables named like *PASSWORD, *SECRET, *TOKEN, *KEY, ... and inline environment values in the compose file) are masked as [REDACTED] unless reveal_env=true. Always inspect with reveal_env=true before resending the compose file through portainer_stack_update — a masked file is rejected.

Args: stack_id: The ID of the stack to inspect reveal_env: Return credential values unmasked (default false)

Deploy a new stack from a docker-compose string.

Args: name: Name of the new stack compose_content: Docker Compose file content (YAML string) env: Stack environment variables (substituted into the compose file by Portainer), e.g. {"DB_PASSWORD": "..."} endpoint_id: Target endpoint ID (uses default if omitted)

Update (redeploy) an existing stack.

The stack's stored Env variables are always preserved: Portainer replaces the whole Env list on every update, so this tool reads the current list first and merges your changes into it. Omit every optional argument to simply redeploy the stack as it is.

To pick up a newly pushed build of a :latest image, pass pull_image=true — a plain redeploy reuses the image already on the nodes.

Args: stack_id: The ID of the stack to update compose_content: New Docker Compose content (YAML). If omitted, the stored file is redeployed unchanged. Must not contain [REDACTED] (inspect with reveal_env=true first). env: Env variables to add or overwrite, e.g. {"TAG": "v2"} env_remove: Names of Env variables to delete prune: Remove services no longer in the compose file (Swarm only). Defaults to the stack's current setting. pull_image: Force re-pulling images before redeploying (Portainer's "Re-pull image and redeploy"; default false) detach_from_git: Required to update a git-backed stack — Portainer converts it to a plain file-based stack and drops the git link and auto-update. Refused otherwise. endpoint_id: Endpoint ID (derived from the stack itself if omitted)

Delete a stack.

Args: stack_id: The ID of the stack to delete endpoint_id: Endpoint ID (derived from the stack itself if omitted)

Start a stopped stack.

Args: stack_id: The ID of the stack to start endpoint_id: Endpoint ID (derived from the stack itself if omitted)

Stop a running stack.

Args: stack_id: The ID of the stack to stop endpoint_id: Endpoint ID (derived from the stack itself if omitted)

List containers on an endpoint, with their stack and service.

On a Swarm endpoint prefer portainer_services_list / stack_status — containers there are task instances that come and go.

Args: endpoint_id: Target endpoint ID (uses default if omitted) show_all: If true, show all containers including stopped ones name_filter: Only return containers whose name contains this substring (server-side Docker filter) stack_filter: Only return containers belonging to this stack (Swarm namespace or Compose project label, exact match)

Get detailed information about a container.

Args: container_id: Container ID or name endpoint_id: Target endpoint ID (uses default if omitted)

Start a stopped container.

Args: container_id: Container ID or name endpoint_id: Target endpoint ID (uses default if omitted)

Stop a running container.

Args: container_id: Container ID or name endpoint_id: Target endpoint ID (uses default if omitted)

Restart a container.

Args: container_id: Container ID or name endpoint_id: Target endpoint ID (uses default if omitted)

Remove a container.

Args: container_id: Container ID or name force: Force removal of a running container (default false) endpoint_id: Target endpoint ID (uses default if omitted)

Get container logs.

Args: container_id: Container ID or name tail: Number of lines from the end of the logs (default 100, max 1000) since: Only lines newer than this: a duration ("10m", "2h", "1d"), a Unix timestamp or an ISO-8601 datetime timestamps: Prefix every line with its timestamp (default false) endpoint_id: Target endpoint ID (uses default if omitted)

Search container logs for lines matching a regex pattern.

Returns only matching lines (with optional context). Useful for finding specific errors, status codes, or keywords without downloading the full log.

Args: container_id: Container ID or name pattern: Regex pattern to search for (case-insensitive) tail: Number of log lines to fetch before filtering (default 500, max 1000) context_lines: Lines of context around each match (default 0, max 5) since: Only scan lines newer than this: a duration ("10m", "2h", "1d"), a Unix timestamp or an ISO-8601 datetime timestamps: Prefix every line with its timestamp (default false) endpoint_id: Target endpoint ID (uses default if omitted)

Scan all running containers in a stack for errors.

Fetches logs from every running container whose name starts with the given stack name and filters for common error patterns: HTTP 4xx/5xx, exceptions, fatal/critical/emergency log levels, panics, OOM, PHP errors, segfaults, etc.

Args: stack_name: Stack name prefix (e.g. "taylor", "blog", "somnlyx") tail: Log lines per container to scan (default 500, max 1000) endpoint_id: Target endpoint ID (uses default if omitted)

Get live CPU, memory, and network stats for a container.

Args: container_id: Container ID or name endpoint_id: Target endpoint ID (uses default if omitted)

Execute a command inside a running container and return its output.

Args: container_id: Container ID or name command: Shell command to execute (run via sh -c) workdir: Working directory inside the container user: User to run the command as (e.g. 'root', '1000:1000') endpoint_id: Target endpoint ID (uses default if omitted)

List Swarm services with running/desired replica counts.

On a Swarm endpoint this is the primary view (like docker service ls): services are the stable units, containers are their tasks. Cron-driven services (swarm-cronjob) carry cron: true and their last run's outcome instead of a meaningful replica count.

Args: endpoint_id: Target endpoint ID (uses default if omitted) stack_filter: Only services of this stack (exact stack name)

Get the full Swarm service definition (spec, update status, endpoint).

Credential-looking environment values in the container spec are masked as [REDACTED] unless reveal_env=true.

Args: service_id: Service ID or name (e.g. "arena-etl_backend") reveal_env: Return credential values unmasked (default false) endpoint_id: Target endpoint ID (uses default if omitted)

List a service's tasks with state, node and error (docker service ps).

The first place to look when replicas are not coming up: a task's error carries the scheduler / container start failure ("no suitable node", "task: non-zero exit (1)", image pull errors, ...).

Args: service_id: Service ID or name limit: Max tasks to return, newest per slot first (default 50, max 500) endpoint_id: Target endpoint ID (uses default if omitted)

Get logs of a Swarm service (all its tasks, across nodes).

Args: service_id: Service ID or name tail: Number of lines from the end of the logs (default 100, max 1000) since: Only lines newer than this: a duration ("10m", "2h", "1d"), a Unix timestamp or an ISO-8601 datetime timestamps: Prefix every line with its timestamp (default false) endpoint_id: Target endpoint ID (uses default if omitted)

Update a Swarm service: change its image, scale it, or force a restart.

Reads the current spec and version, applies the requested changes and submits the spec back (rolling update per the service's UpdateConfig). At least one of image / replicas / force_restart is required. Follow up with portainer_service_wait to know when the rollout converged.

To roll out a new build of the same :latest tag, pass image= ":" without a digest — Swarm resolves the tag to its current digest at update time. force_restart alone re-creates the tasks with the image digest already pinned in the spec.

Args: service_id: Service ID or name image: New image reference (e.g. "registry.example.com/app:latest") replicas: New replica count (replicated services only) force_restart: Re-create all tasks even if the spec is unchanged (docker service update --force) registry_id: ID of a Portainer-configured registry whose stored credentials the nodes should use to pull the image (auto-detected from the image host when omitted; 0 = none) endpoint_id: Target endpoint ID (uses default if omitted)

Roll a Swarm service back to its previous spec (docker service rollback).

Works only while Swarm still holds a PreviousSpec (i.e. after at least one update). Follow up with portainer_service_wait.

Args: service_id: Service ID or name endpoint_id: Target endpoint ID (uses default if omitted)

Wait for a service's rollout to converge after an update/rollback.

Polls until the service is healthy (running == desired and the update finished), the update paused on failure, or the timeout elapses. Returns the final service summary with converged, reason, timed_out and the recent task errors.

Args: service_id: Service ID or name timeout_seconds: How long to wait (default 120, clamped to 5..PORTAINER_LONG_TIMEOUT) endpoint_id: Target endpoint ID (uses default if omitted)

List Swarm nodes with role, availability, state and resources.

Args: endpoint_id: Target endpoint ID (uses default if omitted)

List Swarm secrets (names and metadata only — never the values).

Args: endpoint_id: Target endpoint ID (uses default if omitted)

List Swarm configs (names and metadata only — never the content).

Args: endpoint_id: Target endpoint ID (uses default if omitted)

Health summary of a stack: every service with running/desired replicas, update state and the most recent task failures.

Start here when asked "is stack X ok / why is X down". Works on Swarm (services + tasks) and falls back to container states on a standalone Compose endpoint. Cron-driven services are judged on their last run, and only failures newer than the last good task are reported.

Args: stack_name: Stack name (Swarm namespace / Compose project) endpoint_id: Target endpoint ID (uses default if omitted)

Wait for a stack's rollout to converge after stack_update.

Polls portainer_stack_status until every service is healthy, a service's update paused on failure, or the timeout elapses. Returns the final status with converged, reason and timed_out.

Args: stack_name: Stack name (Swarm namespace / Compose project) timeout_seconds: How long to wait (default 120, clamped to 5..PORTAINER_LONG_TIMEOUT) endpoint_id: Target endpoint ID (uses default if omitted)

List Docker images on an endpoint.

Args: endpoint_id: Target endpoint ID (uses default if omitted) reference_filter: Only return images matching this reference (e.g. 'nginx' or 'nginx:1.25'; server-side Docker filter)

Get detailed information about a Docker image.

Args: image_id: Image ID or name:tag endpoint_id: Target endpoint ID (uses default if omitted)

Pull a Docker image from a registry.

Credentials for a registry configured in Portainer are supplied by Portainer itself: the registry is picked automatically by matching the image's host against portainer_registries_list (Docker Hub images match a DockerHub-type registry), or explicitly via registry_id. registry_id=0 forces an anonymous pull. No password ever passes through the model. Explicit registry_auth is only needed for a registry Portainer does not know.

Args: image_name: Image name (e.g. 'nginx', 'ghcr.io/org/app') tag: Image tag (default 'latest') registry_id: ID of a registry configured in Portainer whose stored credentials should be used (auto-detected from the image host when omitted; 0 = pull anonymously) registry_auth: Base64-encoded JSON ({"username":..,"password":..,"serveraddress":..}) forwarded as X-Registry-Auth for a registry not configured in Portainer. Mutually exclusive with registry_id. endpoint_id: Target endpoint ID (uses default if omitted)

Remove a Docker image.

Args: image_id: Image ID or name:tag endpoint_id: Target endpoint ID (uses default if omitted)

List registries configured in Portainer (id, name, URL, type).

Use the id as registry_id in portainer_image_pull / portainer_service_update so Portainer supplies the stored credentials.

List Docker volumes on an endpoint.

Args: endpoint_id: Target endpoint ID (uses default if omitted) name_filter: Only return volumes whose name contains this substring (server-side Docker filter)

Get detailed information about a Docker volume.

Args: volume_name: Volume name endpoint_id: Target endpoint ID (uses default if omitted)

Create a Docker volume.

Args: name: Volume name driver: Volume driver (default 'local') labels: Optional labels as key-value pairs endpoint_id: Target endpoint ID (uses default if omitted)

Remove a Docker volume.

Args: volume_name: Volume name force: Force removal even if in use (default false) endpoint_id: Target endpoint ID (uses default if omitted)

List Docker networks on an endpoint.

Args: endpoint_id: Target endpoint ID (uses default if omitted) name_filter: Only return networks whose name contains this substring (server-side Docker filter)

Get detailed information about a Docker network.

Args: network_id: Network ID or name endpoint_id: Target endpoint ID (uses default if omitted)

Create a Docker network.

Args: name: Network name driver: Network driver (default 'bridge'; use 'overlay' for Swarm) internal: Restrict external access (default false) labels: Optional labels as key-value pairs endpoint_id: Target endpoint ID (uses default if omitted)

Remove a Docker network.

Args: network_id: Network ID or name endpoint_id: Target endpoint ID (uses default if omitted)

Connect a container to a network.

Args: network_id: Network ID or name container_id: Container ID or name endpoint_id: Target endpoint ID (uses default if omitted)

Disconnect a container from a network.

Args: network_id: Network ID or name container_id: Container ID or name force: Force disconnect (default false) endpoint_id: Target endpoint ID (uses default if omitted)

Get Docker system information for an endpoint (OS, CPU, memory, containers count, etc).

Args: endpoint_id: Target endpoint ID (uses default if omitted)

Get Docker disk usage (containers, images, volumes, build cache).

Args: endpoint_id: Target endpoint ID (uses default if omitted)

Reclaim disk space: remove stopped containers, unused images or build cache.

Volumes are never pruned by this tool (that destroys data); use portainer_volume_remove for a specific volume. Check portainer_docker_disk_usage first to see what is reclaimable.

Args: target: "containers" (all stopped), "images" (dangling only, or every unused image with all_images=true) or "build_cache" all_images: For target="images": also remove tagged images not used by any container (default false — dangling layers only) endpoint_id: Target endpoint ID (uses default if omitted)

List all Portainer users.

Get details of a specific Portainer user.

Args: user_id: The ID of the user to inspect