Control Docker containers and stacks via Portainer API. List containers, start/stop/restart, view logs, and redeploy stacks from git.
---
name: portainer
description: Control Docker containers and stacks via Portainer API. List containers, start/stop/restart, view logs, and redeploy stacks from git.
metadata: {"clawdbot":{"emoji":"๐ณ","requires":{"bins":["curl","jq"],"env":["PORTAINER_API_KEY"]},"primaryEnv":"PORTAINER_API_KEY"}}
---
# ๐ณ Portainer Skill
```
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ โ
โ ๐ณ P O R T A I N E R C O N T R O L C L I ๐ณ โ
โ โ
โ Manage Docker containers via Portainer API โ
โ Start, stop, deploy, redeploy โ
โ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
```
> *"Docker containers? I'll handle them from my lily pad."* ๐ธ
---
## ๐ What Does This Skill Do?
The **Portainer Skill** gives you control over your Docker infrastructure through Portainer's REST API. Manage containers, stacks, and deployments without touching the web UI.
**Features:**
- ๐ **Status** โ Check Portainer server status
- ๐ฅ๏ธ **Endpoints** โ List all Docker environments
- ๐ฆ **Containers** โ List, start, stop, restart containers
- ๐ **Stacks** โ List and manage Docker Compose stacks
- ๐ **Redeploy** โ Pull from git and redeploy stacks
- ๐ **Logs** โ View container logs
---
## โ๏ธ Requirements
| What | Details |
|------|---------|
| **Portainer** | Version 2.x with API access |
| **Tools** | `curl`, `jq` |
| **Auth** | API Access Token |
### Setup
1. **Get API Token from Portainer:**
- Log into Portainer web UI
- Click username โ My Account
- Scroll to "Access tokens" โ Add access token
- Copy the token (you won't see it again!)
2. **Configure credentials:**
```bash
# Add to ~/.clawdbot/.env
PORTAINER_URL=https://your-portainer-server:9443
PORTAINER_API_KEY=ptr_your_token_here
```
3. **Ready!** ๐
---
## ๐ ๏ธ Commands
### `status` โ Check Portainer Server
```bash
./portainer.sh status
```
**Output:**
```
Portainer v2.27.3
```
---
### `endpoints` โ List Environments
```bash
./portainer.sh endpoints
```
**Output:**
```
3: portainer (local) - โ online
4: production (remote) - โ online
```
---
### `containers` โ List Containers
```bash
# List containers on default endpoint (4)
./portainer.sh containers
# List containers on specific endpoint
./portainer.sh containers 3
```
**Output:**
```
steinbergerraum-web-1 running Up 2 days
cora-web-1 running Up 6 weeks
minecraft running Up 6 weeks (healthy)
```
---
### `stacks` โ List All Stacks
```bash
./portainer.sh stacks
```
**Output:**
```
25: steinbergerraum - โ active
33: cora - โ active
35: minecraft - โ active
4: pulse-website - โ inactive
```
---
### `stack-info` โ Stack Details
```bash
./portainer.sh stack-info 25
```
**Output:**
```json
{
"Id": 25,
"Name": "steinbergerraum",
"Status": 1,
"EndpointId": 4,
"GitConfig": "https://github.com/user/repo",
"UpdateDate": "2026-01-25T08:44:56Z"
}
```
---
### `redeploy` โ Pull & Redeploy Stack ๐
```bash
./portainer.sh redeploy 25
```
**Output:**
```
โ Stack 'steinbergerraum' redeployed successfully
```
This will:
1. Pull latest code from git
2. Rebuild containers if needed
3. Restart the stack
---
### `start` / `stop` / `restart` โ Container Control
```bash
# Start a container
./portainer.sh start steinbergerraum-web-1
# Stop a container
./portainer.sh stop steinbergerraum-web-1
# Restart a container
./portainer.sh restart steinbergerraum-web-1
# Specify endpoint (default: 4)
./portainer.sh restart steinbergerraum-web-1 4
```
**Output:**
```
โ Container 'steinbergerraum-web-1' restarted
```
---
### `logs` โ View Container Logs
```bash
# Last 100 lines (default)
./portainer.sh logs steinbergerraum-web-1
# Last 50 lines
./portainer.sh logs steinbergerraum-web-1 4 50
```
---
## ๐ฏ Example Workflows
### ๐ "Deploy Website Update"
```bash
# After merging PR
./portainer.sh redeploy 25
./portainer.sh logs steinbergerraum-web-1 4 20
```
### ๐ง "Debug Container"
```bash
./portainer.sh containers
./portainer.sh logs cora-web-1
./portainer.sh restart cora-web-1
```
### ๐ "System Overview"
```bash
./portainer.sh status
./portainer.sh endpoints
./portainer.sh containers
./portainer.sh stacks
```
---
## ๐ง Troubleshooting
### โ "Authentication required / Repository not found"
**Problem:** Stack redeploy fails with git auth error
**Solution:** The stack needs `repositoryGitCredentialID` parameter. The script handles this automatically by reading from the existing stack config.
---
### โ "Container not found"
**Problem:** Container name doesn't match
**Solution:** Use exact name from `./portainer.sh containers`:
- Include the full name: `steinbergerraum-web-1` not `steinbergerraum`
- Names are case-sensitive
---
### โ "PORTAINER_URL and PORTAINER_API_KEY must be set"
**Problem:** Credentials not configured
**Solution:**
```bash
# Add to ~/.clawdbot/.env
echo "PORTAINER_URL=https://your-server:9443" >> ~/.clawdbot/.env
echo "PORTAINER_API_KEY=ptr_your_token" >> ~/.clawdbot/.env
```
---
## ๐ Integration with Clawd
```
"Redeploy the website"
โ ./portainer.sh redeploy 25
"Show me running containers"
โ ./portainer.sh containers
"Restart the Minecraft server"
โ ./portainer.sh restart minecraft
"What stacks do we have?"
โ ./portainer.sh stacks
```
---
## ๐ Changelog
| Version | Date | Changes |
|---------|------|---------|
| 1.0.0 | 2026-01-25 | Initial release |
---
## ๐ธ Credits
```
@..@
(----)
( >__< ) "Containers are just fancy lily pads
^^ ^^ for your code to hop around!"
```
**Author:** Andy Steinberger (with help from his Clawdbot Owen the Frog ๐ธ)
**Powered by:** [Portainer](https://portainer.io/) API
**Part of:** [Clawdbot](https://clawdhub.com) Skills Collection
---
<div align="center">
**Made with ๐ for the Clawdbot Community**
*Ribbit!* ๐ธ
</div>
don't have the plugin yet? install it then click "run inline in claude" again.