stef-openclaw-skills/docs/portainer.md

Portainer Skill

Interact with Portainer stacks via API key authentication. Manage stacks, resolve identifiers, update deployments, and clean up old images.

Overview

This skill provides a comprehensive set of commands for managing Portainer Docker stacks through the API. All stack commands accept stack names and automatically resolve IDs internally.

Prerequisites

Auth Configuration

Create a config file at:

~/.clawdbot/credentials/portainer/config.json

With the following content:

{
  "base_url": "https://your-portainer-instance.com",
  "api_key": "YOUR_PORTAINER_API_KEY"
}

To generate an API key:

1. Log into Portainer
2. Go to User Settings → Access tokens
3. Create a new token with appropriate permissions

Commands

Stack Identification

Get Stack ID

bash scripts/get-stack-id.sh "<stack-name>"

Resolves a stack name to its numeric ID. Prints only the ID on success.

Get Endpoint ID

bash scripts/get-endpoint-id.sh "<endpoint-name>"

Resolves an endpoint (environment) name to its ID.

Stack Inventory

List All Stacks

bash scripts/list-stacks.sh

Lists all stacks with their ID, Name, and Status.

Get Stack Status

bash scripts/get-stack-status.sh "<stack-name>"

Returns JSON with stack details: Id, Name, Status, Type, EndpointId, CreationDate, UpdatedDate.

Stack Lifecycle

Stop Stack

bash scripts/stop-stack.sh "<stack-name>"

Start Stack

bash scripts/start-stack.sh "<stack-name>"

Restart Stack

bash scripts/restart-stack.sh "<stack-name>"

Stack Configuration

Get Environment Variables

bash scripts/get-stack-env.sh "<stack-name>"

Returns JSON array of {name, value} objects.

Get Compose File

bash scripts/get-stack-compose.sh "<stack-name>"

Returns the raw docker-compose.yml content.

Stack Updates

Update Stack

bash scripts/update-stack.sh "<stack-name>" "<compose-file>" [options]

Options:

• --pull — Force pull images and redeploy (like docker compose down/pull/up)
• --env-file <file> — Path to a file with env vars (format: NAME=value per line)

Notes:

• Without --env-file, existing environment variables are preserved
• The --pull flag may return HTTP 504 for large images, but the operation completes in the background

Prune Stack Images

bash scripts/prune-stack-images.sh "<stack-name>"

Removes dangling images on the endpoint. Run this after update-stack --pull completes.

Typical Workflow

Updating a Stack with a New Image Version

# 1. Get the current compose file
bash scripts/get-stack-compose.sh "my-stack" > /tmp/my-stack-compose.yml

# 2. Update the stack (pull new images)
bash scripts/update-stack.sh "my-stack" "/tmp/my-stack-compose.yml" --pull

# 3. Wait for update to complete (even if you see a 504 timeout)

# 4. Clean up old images
bash scripts/prune-stack-images.sh "my-stack"

Modifying a Stack's Compose File

# 1. Get the current compose file
bash scripts/get-stack-compose.sh "my-stack" > /tmp/my-stack-compose.yml

# 2. Edit the compose file
nano /tmp/my-stack-compose.yml

# 3. Update the stack with the modified file
bash scripts/update-stack.sh "my-stack" "/tmp/my-stack-compose.yml"

# 4. Optionally prune old images if you changed image tags
bash scripts/prune-stack-images.sh "my-stack"

Error Handling

All scripts:

• Exit with code 0 on success
• Exit with non-zero code on failure
• Print error messages to stderr
• Print results to stdout

Common errors:

• Missing config file: Create the auth configuration file
• Invalid API key: Generate a new API key in Portainer
• Stack not found: Check the stack name with list-stacks.sh
• 504 Gateway Timeout: The operation is still running in the background; wait and then run the prune command

API Reference

This skill uses the following Portainer API endpoints:

Endpoint	Method	Purpose
/api/stacks	GET	List all stacks
/api/stacks/{id}	GET	Get stack details
/api/stacks/{id}	PUT	Update stack
/api/stacks/{id}/file	GET	Get compose file
/api/stacks/{id}/start	POST	Start stack
/api/stacks/{id}/stop	POST	Stop stack
/api/stacks/{id}/restart	POST	Restart stack
/api/endpoints	GET	List endpoints
/api/endpoints/{id}/docker/containers/json	GET	List containers
/api/endpoints/{id}/docker/images/json	GET	List images
/api/endpoints/{id}/docker/images/{id}	DELETE	Remove image

Notes

• All *-stack.sh commands resolve the stack ID internally from the name
• Endpoint ID is fetched automatically from stack info for lifecycle and update operations
• The --pull flag triggers Portainer to pull new images and recreate containers
• Large image pulls may cause HTTP 504 timeouts, but operations complete server-side
• Use prune-stack-images.sh after updates to clean up old dangling images