OpenClaw - Arcane Docker Management Skill\r

\r

Overview\r

This skill enables you to interact with your Arcane Docker Management API to manage Docker containers, compose stacks, templates, networks, volumes, images, and system monitoring. Arcane is a comprehensive Docker management platform with a REST API.\r \r

When to Use This Skill\r

Use this skill when the user requests any of the following:\r

• Managing Docker containers (list, start, stop, restart, remove, inspect)\r
• Managing Docker Compose stacks (deploy, update, remove, view logs)\r
• Working with Docker templates (create, deploy, manage)\r
• Managing Docker images (list, pull, remove, prune)\r
• Managing Docker networks and volumes\r
• Monitoring system resources and Docker statistics\r
• Managing user accounts and API keys\r
• Viewing system logs and events\r \r

API Configuration\r

\r

Base URL\r

The API base URL should be configured by the user. Default: http://localhost:3552/api\r \r

Authentication\r

Arcane supports two authentication methods:\r \r

1. Bearer Token (JWT): Obtained via login endpoint\r
2. API Key: Long-lived authentication using X-API-Key header\r \r

Getting a Bearer Token\r

curl -X POST "$BASE_URL/auth/login" \\r
  -H "Content-Type: application/json" \\r
  -d '{\r
    "username": "admin",\r
    "password": "your_password"\r
  }'\r
```\r
\r
Response includes `token`, `refreshToken`, and `expiresAt`.\r
\r
#### Using API Keys\r
API keys can be created and managed through the `/apikeys` endpoints. Use the `X-API-Key` header for authentication.\r
\r
## Core Functionality\r
\r
### 1. Container Management\r
\r
#### List Containers\r
```bash\r
# Get all containers\r
curl -X GET "$BASE_URL/containers" \\r
  -H "Authorization: Bearer $TOKEN"\r
\r
# Filter by status\r
curl -X GET "$BASE_URL/containers?status=running" \\r
  -H "Authorization: Bearer $TOKEN"\r
\r
# Search containers\r
curl -X GET "$BASE_URL/containers?search=nginx" \\r
  -H "Authorization: Bearer $TOKEN"\r
```\r
\r
#### Container Operations\r
```bash\r
# Start container\r
curl -X POST "$BASE_URL/containers/{id}/start" \\r
  -H "Authorization: Bearer $TOKEN"\r
\r
# Stop container\r
curl -X POST "$BASE_URL/containers/{id}/stop" \\r
  -H "Authorization: Bearer $TOKEN"\r
\r
# Restart container\r
curl -X POST "$BASE_URL/containers/{id}/restart" \\r
  -H "Authorization: Bearer $TOKEN"\r
\r
# Remove container\r
curl -X DELETE "$BASE_URL/containers/{id}" \\r
  -H "Authorization: Bearer $TOKEN"\r
\r
# Get container details\r
curl -X GET "$BASE_URL/containers/{id}" \\r
  -H "Authorization: Bearer $TOKEN"\r
\r
# Get container logs\r
curl -X GET "$BASE_URL/containers/{id}/logs?tail=100" \\r
  -H "Authorization: Bearer $TOKEN"\r
\r
# Get container stats\r
curl -X GET "$BASE_URL/containers/{id}/stats" \\r
  -H "Authorization: Bearer $TOKEN"\r
```\r
\r
#### Advanced Container Operations\r
```bash\r
# Execute command in container\r
curl -X POST "$BASE_URL/containers/{id}/exec" \\r
  -H "Authorization: Bearer $TOKEN" \\r
  -H "Content-Type: application/json" \\r
  -d '{\r
    "command": ["ls", "-la"],\r
    "workingDir": "/app"\r
  }'\r
\r
# Rename container\r
curl -X POST "$BASE_URL/containers/{id}/rename" \\r
  -H "Authorization: Bearer $TOKEN" \\r
  -H "Content-Type: application/json" \\r
  -d '{\r
    "name": "new-container-name"\r
  }'\r
\r
# Update container resources\r
curl -X POST "$BASE_URL/containers/{id}/update" \\r
  -H "Authorization: Bearer $TOKEN" \\r
  -H "Content-Type: application/json" \\r
  -d '{\r
    "cpuShares": 512,\r
    "memory": 536870912,\r
    "restartPolicy": "unless-stopped"\r
  }'\r
```\r
\r
### 2. Docker Compose Stack Management\r
\r
#### List Stacks\r
```bash\r
curl -X GET "$BASE_URL/stacks" \\r
  -H "Authorization: Bearer $TOKEN"\r
```\r
\r
#### Deploy Stack from Template\r
```bash\r
curl -X POST "$BASE_URL/stacks" \\r
  -H "Authorization: Bearer $TOKEN" \\r
  -H "Content-Type: application/json" \\r
  -d '{\r
    "name": "my-stack",\r
    "templateId": "template-id",\r
    "envVars": {\r
      "PORT": "8080",\r
      "DATABASE_URL": "postgres://..."\r
    }\r
  }'\r
```\r
\r
#### Deploy Stack from Compose File\r
```bash\r
curl -X POST "$BASE_URL/stacks" \\r
  -H "Authorization: Bearer $TOKEN" \\r
  -H "Content-Type: application/json" \\r
  -d '{\r
    "name": "my-stack",\r
    "composeContent": "version: \"3.8\"\
services:\
  web:\
    image: nginx:latest\
    ports:\
      - \"80:80\""\r
  }'\r
```\r
\r
#### Stack Operations\r
```bash\r
# Get stack details\r
curl -X GET "$BASE_URL/stacks/{id}" \\r
  -H "Authorization: Bearer $TOKEN"\r
\r
# Update stack\r
curl -X PUT "$BASE_URL/stacks/{id}" \\r
  -H "Authorization: Bearer $TOKEN" \\r
  -H "Content-Type: application/json" \\r
  -d '{\r
    "envVars": {\r
      "PORT": "9090"\r
    }\r
  }'\r
\r
# Remove stack\r
curl -X DELETE "$BASE_URL/stacks/{id}" \\r
  -H "Authorization: Bearer $TOKEN"\r
\r
# Start stack\r
curl -X POST "$BASE_URL/stacks/{id}/start" \\r
  -H "Authorization: Bearer $TOKEN"\r
\r
# Stop stack\r
curl -X POST "$BASE_URL/stacks/{id}/stop" \\r
  -H "Authorization: Bearer $TOKEN"\r
\r
# Restart stack\r
curl -X POST "$BASE_URL/stacks/{id}/restart" \\r
  -H "Authorization: Bearer $TOKEN"\r
\r
# Get stack logs\r
curl -X GET "$BASE_URL/stacks/{id}/logs?tail=100" \\r
  -H "Authorization: Bearer $TOKEN"\r
\r
# Pull latest images for stack\r
curl -X POST "$BASE_URL/stacks/{id}/pull" \\r
  -H "Authorization: Bearer $TOKEN"\r
```\r
\r
### 3. Template Management\r
\r
#### List Templates\r
```bash\r
curl -X GET "$BASE_URL/templates" \\r
  -H "Authorization: Bearer $TOKEN"\r
```\r
\r
#### Create Template\r
```bash\r
curl -X POST "$BASE_URL/templates" \\r
  -H "Authorization: Bearer $TOKEN" \\r
  -H "Content-Type: application/json" \\r
  -d '{\r
    "name": "nginx-template",\r
    "description": "Basic nginx web server",\r
    "content": "version: \"3.8\"\
services:\
  web:\
    image: nginx:{{VERSION}}\
    ports:\
      - \"{{PORT}}:80\"",\r
    "variables": [\r
      {\r
        "name": "VERSION",\r
        "description": "Nginx version",\r
        "defaultValue": "latest"\r
      },\r
      {\r
        "name": "PORT",\r
        "description": "Host port",\r
        "defaultValue": "80"\r
      }\r
    ],\r
    "category": "web-servers",\r
    "tags": ["nginx", "web"]\r
  }'\r
```\r
\r
#### Template Operations\r
```bash\r
# Get template\r
curl -X GET "$BASE_URL/templates/{id}" \\r
  -H "Authorization: Bearer $TOKEN"\r
\r
# Update template\r
curl -X PUT "$BASE_URL/templates/{id}" \\r
  -H "Authorization: Bearer $TOKEN" \\r
  -H "Content-Type: application/json" \\r
  -d '{\r
    "name": "updated-template-name",\r
    "description": "Updated description"\r
  }'\r
\r
# Delete template\r
curl -X DELETE "$BASE_URL/templates/{id}" \\r
  -H "Authorization: Bearer $TOKEN"\r
\r
# Get template content with parsed variables\r
curl -X GET "$BASE_URL/templates/{id}/content" \\r
  -H "Authorization: Bearer $TOKEN"\r
```\r
\r
#### Global Template Variables\r
```bash\r
# Get global variables\r
curl -X GET "$BASE_URL/templates/global-variables" \\r
  -H "Authorization: Bearer $TOKEN"\r
\r
# Update global variables\r
curl -X PUT "$BASE_URL/templates/global-variables" \\r
  -H "Authorization: Bearer $TOKEN" \\r
  -H "Content-Type: application/json" \\r
  -d '{\r
    "GLOBAL_DOMAIN": "example.com",\r
    "GLOBAL_NETWORK": "traefik-public"\r
  }'\r
```\r
\r
### 4. Image Management\r
\r
#### List Images\r
```bash\r
curl -X GET "$BASE_URL/images" \\r
  -H "Authorization: Bearer $TOKEN"\r
```\r
\r
#### Pull Image\r
```bash\r
curl -X POST "$BASE_URL/images/pull" \\r
  -H "Authorization: Bearer $TOKEN" \\r
  -H "Content-Type: application/json" \\r
  -d '{\r
    "image": "nginx:latest"\r
  }'\r
```\r
\r
#### Image Operations\r
```bash\r
# Get image details\r
curl -X GET "$BASE_URL/images/{id}" \\r
  -H "Authorization: Bearer $TOKEN"\r
\r
# Remove image\r
curl -X DELETE "$BASE_URL/images/{id}" \\r
  -H "Authorization: Bearer $TOKEN"\r
\r
# Prune unused images\r
curl -X POST "$BASE_URL/images/prune" \\r
  -H "Authorization: Bearer $TOKEN"\r
\r
# Search images in registry\r
curl -X GET "$BASE_URL/images/search?term=nginx" \\r
  -H "Authorization: Bearer $TOKEN"\r
```\r
\r
### 5. Network Management\r
\r
#### List Networks\r
```bash\r
curl -X GET "$BASE_URL/networks" \\r
  -H "Authorization: Bearer $TOKEN"\r
```\r
\r
#### Create Network\r
```bash\r
curl -X POST "$BASE_URL/networks" \\r
  -H "Authorization: Bearer $TOKEN" \\r
  -H "Content-Type: application/json" \\r
  -d '{\r
    "name": "my-network",\r
    "driver": "bridge",\r
    "internal": false,\r
    "attachable": true\r
  }'\r
```\r
\r
#### Network Operations\r
```bash\r
# Get network details\r
curl -X GET "$BASE_URL/networks/{id}" \\r
  -H "Authorization: Bearer $TOKEN"\r
\r
# Remove network\r
curl -X DELETE "$BASE_URL/networks/{id}" \\r
  -H "Authorization: Bearer $TOKEN"\r
\r
# Connect container to network\r
curl -X POST "$BASE_URL/networks/{id}/connect" \\r
  -H "Authorization: Bearer $TOKEN" \\r
  -H "Content-Type: application/json" \\r
  -d '{\r
    "containerId": "container-id"\r
  }'\r
\r
# Disconnect container from network\r
curl -X POST "$BASE_URL/networks/{id}/disconnect" \\r
  -H "Authorization: Bearer $TOKEN" \\r
  -H "Content-Type: application/json" \\r
  -d '{\r
    "containerId": "container-id"\r
  }'\r
\r
# Prune unused networks\r
curl -X POST "$BASE_URL/networks/prune" \\r
  -H "Authorization: Bearer $TOKEN"\r
```\r
\r
### 6. Volume Management\r
\r
#### List Volumes\r
```bash\r
curl -X GET "$BASE_URL/volumes" \\r
  -H "Authorization: Bearer $TOKEN"\r
```\r
\r
#### Create Volume\r
```bash\r
curl -X POST "$BASE_URL/volumes" \\r
  -H "Authorization: Bearer $TOKEN" \\r
  -H "Content-Type: application/json" \\r
  -d '{\r
    "name": "my-volume",\r
    "driver": "local",\r
    "labels": {\r
      "project": "my-app"\r
    }\r
  }'\r
```\r
\r
#### Volume Operations\r
```bash\r
# Get volume details\r
curl -X GET "$BASE_URL/volumes/{name}" \\r
  -H "Authorization: Bearer $TOKEN"\r
\r
# Remove volume\r
curl -X DELETE "$BASE_URL/volumes/{name}" \\r
  -H "Authorization: Bearer $TOKEN"\r
\r
# Prune unused volumes\r
curl -X POST "$BASE_URL/volumes/prune" \\r
  -H "Authorization: Bearer $TOKEN"\r
```\r
\r
### 7. System Monitoring\r
\r
#### System Information\r
```bash\r
# Get Docker system info\r
curl -X GET "$BASE_URL/system/info" \\r
  -H "Authorization: Bearer $TOKEN"\r
\r
# Get Docker version\r
curl -X GET "$BASE_URL/system/version" \\r
  -H "Authorization: Bearer $TOKEN"\r
\r
# Get system stats\r
curl -X GET "$BASE_URL/system/stats" \\r
  -H "Authorization: Bearer $TOKEN"\r
\r
# Get disk usage\r
curl -X GET "$BASE_URL/system/df" \\r
  -H "Authorization: Bearer $TOKEN"\r
```\r
\r
#### Events and Logs\r
```bash\r
# Get system events (streaming)\r
curl -X GET "$BASE_URL/system/events" \\r
  -H "Authorization: Bearer $TOKEN"\r
\r
# Get events with filters\r
curl -X GET "$BASE_URL/system/events?since=1609459200&type=container" \\r
  -H "Authorization: Bearer $TOKEN"\r
```\r
\r
### 8. User Management\r
\r
#### List Users\r
```bash\r
curl -X GET "$BASE_URL/users" \\r
  -H "Authorization: Bearer $TOKEN"\r
```\r
\r
#### Create User\r
```bash\r
curl -X POST "$BASE_URL/users" \\r
  -H "Authorization: Bearer $TOKEN" \\r
  -H "Content-Type: application/json" \\r
  -d '{\r
    "username": "newuser",\r
    "email": "[email protected]",\r
    "password": "securepassword123",\r
    "role": "user"\r
  }'\r
```\r
\r
#### User Operations\r
```bash\r
# Get user details\r
curl -X GET "$BASE_URL/users/{userId}" \\r
  -H "Authorization: Bearer $TOKEN"\r
\r
# Update user\r
curl -X PUT "$BASE_URL/users/{userId}" \\r
  -H "Authorization: Bearer $TOKEN" \\r
  -H "Content-Type: application/json" \\r
  -d '{\r
    "email": "[email protected]",\r
    "role": "admin"\r
  }'\r
\r
# Delete user\r
curl -X DELETE "$BASE_URL/users/{userId}" \\r
  -H "Authorization: Bearer $TOKEN"\r
\r
# Change password\r
curl -X PUT "$BASE_URL/auth/password" \\r
  -H "Authorization: Bearer $TOKEN" \\r
  -H "Content-Type: application/json" \\r
  -d '{\r
    "currentPassword": "oldpassword",\r
    "newPassword": "newpassword123"\r
  }'\r
```\r
\r
### 9. API Key Management\r
\r
#### List API Keys\r
```bash\r
curl -X GET "$BASE_URL/apikeys" \\r
  -H "Authorization: Bearer $TOKEN"\r
```\r
\r
#### Create API Key\r
```bash\r
curl -X POST "$BASE_URL/apikeys" \\r
  -H "Authorization: Bearer $TOKEN" \\r
  -H "Content-Type: application/json" \\r
  -d '{\r
    "name": "CI/CD Pipeline Key",\r
    "description": "API key for automated deployments",\r
    "expiresAt": "2025-12-31T23:59:59Z"\r
  }'\r
```\r
\r
#### API Key Operations\r
```bash\r
# Get API key details\r
curl -X GET "$BASE_URL/apikeys/{id}" \\r
  -H "Authorization: Bearer $TOKEN"\r
\r
# Update API key\r
curl -X PUT "$BASE_URL/apikeys/{id}" \\r
  -H "Authorization: Bearer $TOKEN" \\r
  -H "Content-Type: application/json" \\r
  -d '{\r
    "name": "Updated Key Name",\r
    "description": "Updated description"\r
  }'\r
\r
# Delete API key\r
curl -X DELETE "$BASE_URL/apikeys/{id}" \\r
  -H "Authorization: Bearer $TOKEN"\r
```\r
\r
## Implementation Guidelines\r
\r
### Error Handling\r
All API responses follow a standard format:\r
```json\r
{\r
  "success": true|false,\r
  "data": {...},\r
  "message": "Success or error message"\r
}\r
```\r
\r
Error responses use HTTP problem details (RFC 7807):\r
```json\r
{\r
  "type": "about:blank",\r
  "title": "Error title",\r
  "status": 400,\r
  "detail": "Detailed error message"\r
}\r
```\r
\r
### Pagination\r
List endpoints support pagination with these query parameters:\r
- `start`: Starting index (default: 0)\r
- `limit`: Items per page (default: 20)\r
- `sort`: Column to sort by\r
- `order`: Sort direction (asc/desc, default: asc)\r
- `search`: Search query\r
\r
Response includes pagination metadata:\r
```json\r
{\r
  "success": true,\r
  "data": [...],\r
  "pagination": {\r
    "start": 0,\r
    "limit": 20,\r
    "total": 100,\r
    "hasMore": true\r
  }\r
}\r
```\r
\r
### Using Python\r
When implementing Arcane operations in Python, use the `requests` library:\r
\r
```python\r
import requests\r
\r
BASE_URL = "http://localhost:3552/api"\r
TOKEN = "your-jwt-token"\r
\r
headers = {\r
    "Authorization": f"Bearer {TOKEN}",\r
    "Content-Type": "application/json"\r
}\r
\r
# List containers\r
response = requests.get(f"{BASE_URL}/containers", headers=headers)\r
containers = response.json()\r
\r
# Deploy stack\r
stack_data = {\r
    "name": "my-stack",\r
    "templateId": "template-id",\r
    "envVars": {\r
        "PORT": "8080"\r
    }\r
}\r
response = requests.post(f"{BASE_URL}/stacks", headers=headers, json=stack_data)\r
result = response.json()\r
```\r
\r
### Using Bash\r
For simple operations, use curl with error handling:\r
\r
```bash\r
#!/bin/bash\r
\r
BASE_URL="http://localhost:3552/api"\r
TOKEN="your-jwt-token"\r
\r
# Function to make authenticated requests\r
api_call() {\r
    local method=$1\r
    local endpoint=$2\r
    local data=$3\r
    \r
    if [ -z "$data" ]; then\r
        curl -s -X "$method" "$BASE_URL/$endpoint" \\r
            -H "Authorization: Bearer $TOKEN"\r
    else\r
        curl -s -X "$method" "$BASE_URL/$endpoint" \\r
            -H "Authorization: Bearer $TOKEN" \\r
            -H "Content-Type: application/json" \\r
            -d "$data"\r
    fi\r
}\r
\r
# Example: List containers\r
containers=$(api_call GET "containers")\r
echo "$containers" | jq '.data[] | {id, name, status}'\r
```\r
\r
## Common Workflows\r
\r
### 1. Deploy Application Stack\r
```python\r
# 1. Create or select template\r
template_data = {\r
    "name": "webapp-template",\r
    "content": "version: '3.8'\
services:\
  web:\
    image: myapp:{{VERSION}}\
    ports:\
      - '{{PORT}}:8080'",\r
    "variables": [\r
        {"name": "VERSION", "defaultValue": "latest"},\r
        {"name": "PORT", "defaultValue": "80"}\r
    ]\r
}\r
template = requests.post(f"{BASE_URL}/templates", headers=headers, json=template_data).json()\r
\r
# 2. Deploy stack from template\r
stack_data = {\r
    "name": "production-webapp",\r
    "templateId": template["data"]["id"],\r
    "envVars": {\r
        "VERSION": "v1.2.3",\r
        "PORT": "8080"\r
    }\r
}\r
stack = requests.post(f"{BASE_URL}/stacks", headers=headers, json=stack_data).json()\r
\r
# 3. Monitor deployment\r
stack_id = stack["data"]["id"]\r
logs = requests.get(f"{BASE_URL}/stacks/{stack_id}/logs?tail=50", headers=headers).json()\r
```\r
\r
### 2. Scale and Monitor Containers\r
```python\r
# Get running containers\r
containers = requests.get(f"{BASE_URL}/containers?status=running", headers=headers).json()\r
\r
# Get stats for each container\r
for container in containers["data"]:\r
    stats = requests.get(f"{BASE_URL}/containers/{container['id']}/stats", headers=headers).json()\r
    print(f"{container['name']}: CPU {stats['data']['cpuPercent']:.2f}%, Memory {stats['data']['memoryPercent']:.2f}%")\r
\r
# Update container resources if needed\r
update_data = {\r
    "cpuShares": 1024,\r
    "memory": 1073741824  # 1GB\r
}\r
requests.post(f"{BASE_URL}/containers/{container_id}/update", headers=headers, json=update_data)\r
```\r
\r
### 3. Cleanup and Maintenance\r
```python\r
# Prune unused resources\r
requests.post(f"{BASE_URL}/images/prune", headers=headers)\r
requests.post(f"{BASE_URL}/volumes/prune", headers=headers)\r
requests.post(f"{BASE_URL}/networks/prune", headers=headers)\r
\r
# Get disk usage before and after\r
df_before = requests.get(f"{BASE_URL}/system/df", headers=headers).json()\r
# ... perform cleanup ...\r
df_after = requests.get(f"{BASE_URL}/system/df", headers=headers).json()\r
```\r
\r
## Best Practices\r
\r
1. **Authentication**: Always use API keys for automated scripts and services. Use JWT tokens for interactive sessions.\r
\r
2. **Error Handling**: Check response status codes and handle errors appropriately:\r
   - 200: Success\r
   - 400: Bad request (validation error)\r
   - 401: Unauthorized\r
   - 403: Forbidden\r
   - 404: Not found\r
   - 500: Internal server error\r
\r
3. **Resource Management**: \r
   - Always specify resource limits when creating containers\r
   - Use labels to organize resources\r
   - Regularly prune unused resources\r
\r
4. **Security**:\r
   - Store API keys and tokens securely (use environment variables)\r
   - Use HTTPS in production\r
   - Implement proper access controls with user roles\r
   - Rotate API keys regularly\r
\r
5. **Monitoring**:\r
   - Monitor container stats regularly\r
   - Set up alerts for resource usage\r
   - Review system logs periodically\r
\r
6. **Templates**:\r
   - Use variables for configurable values\r
   - Document template variables clearly\r
   - Version control your templates\r
   - Use global variables for shared configuration\r
\r
## Troubleshooting\r
\r
### Common Issues\r
\r
**Authentication Failed**\r
- Verify token is not expired (check `expiresAt`)\r
- Use refresh token to get new access token\r
- Verify API key is correct and not expired\r
\r
**Container Won't Start**\r
- Check container logs: `GET /containers/{id}/logs`\r
- Inspect container: `GET /containers/{id}`\r
- Verify port conflicts and resource availability\r
\r
**Stack Deployment Failed**\r
- Validate compose file syntax\r
- Check template variables are properly defined\r
- Review stack logs: `GET /stacks/{id}/logs`\r
\r
**Resource Not Found**\r
- Verify resource ID is correct\r
- Check if resource was deleted\r
- Ensure proper permissions\r
\r
## Notes\r
\r
- All timestamps are in ISO 8601 format (UTC)\r
- Container IDs can be full or short (first 12 characters)\r
- Image names support full registry paths (registry.example.com/image:tag)\r
- Network and volume names must be unique\r
- Stack names must be unique per user/project\r
\r
## Reference Links\r
\r
For complete API documentation and schema definitions, refer to the OpenAPI specification provided in the JSON schema.