stef-openclaw-skills/skills/portainer/SKILL.md

name: portainer description: Interact with Portainer stacks via API key authentication. Use for any Portainer stack operations including: listing stacks, resolving stack/endpoint IDs, getting stack status, starting/stopping/restarting stacks, retrieving env vars and compose files, and updating stacks with new compose content. All stack commands accept names and resolve IDs automatically.

Portainer Skill

Manage Portainer stacks via API. All stack commands accept names and resolve IDs automatically.

Required auth config

workspace .clawdbot/credentials/portainer/config.json (preferred) or ~/.clawdbot/credentials/portainer/config.json

{
  "base_url": "https://portainer.example.com",
  "api_key": "YOUR_PORTAINER_API_KEY"
}

Commands

Resolve stack ID

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

Prints only the stack ID. Exits non-zero if not found.

Resolve endpoint ID

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

Prints only the endpoint (environment) ID.

List all stacks

bash scripts/list-stacks.sh

Outputs: ID Name Status (tab-aligned).

Get stack status

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

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

Restart stack

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

Stop stack

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

Start stack

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

Get stack env vars

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

Returns JSON array of {name, value} objects.

Get stack compose file

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

Returns the raw docker-compose.yml content.

Update stack

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

Updates a stack with a new compose file. Preserves existing env vars unless --env-file is provided.

Options:

• --pull — Force pull images and redeploy (like docker compose down/pull/up). Note: may return 504 timeout for large images, but operation completes in 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 to clean up old image versions.

Typical workflow:

bash scripts/update-stack.sh "stack-name" "compose.yml" --pull
# wait for update to complete (even if 504 timeout)
bash scripts/prune-stack-images.sh "stack-name"

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.
• update-stack.sh is the primary command for deploying new versions — it will trigger Portainer to pull new images if the compose file references updated image tags.