# Skill: docker

## Metadata

| Field | Value |
|-------|-------|
| **Name** | `docker` |
| **Version** | `1.0.0` |
| **Package** | `oclawma-skill-docker` |
| **Category** | `infrastructure` |
| **Author** | `OpenClaw Team` |
| **License** | `MIT` |
| **Python** | `>=3.9` |

## Description

Official Docker skill for OCLAWMA providing comprehensive container management capabilities. This skill wraps the Docker CLI into safe, easy-to-use tools with proper error handling and output formatting.

### Features

- **Container Lifecycle** - Run, start, stop, restart, and remove containers
- **Container Operations** - View logs, execute commands, inspect containers, view stats
- **Image Management** - Pull, build, list, and remove images
- **Network Management** - Create, list, and remove Docker networks
- **Volume Management** - Create, list, and remove volumes
- **System Operations** - Prune unused containers, networks, images, and volumes
- **Docker Compose** - Manage multi-container applications

## Installation

```bash
pip install oclawma-skill-docker
```

Or install from source:

```bash
git clone https://github.com/openclaw/oclawma-skill-docker.git
cd oclawma-skill-docker
pip install -e .
```

### Prerequisites

- **Docker** - Installed and configured (`docker version` should work)
- **Docker Compose** (optional) - For compose operations (`docker-compose version` or `docker compose version`)

## Configuration

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `DOCKER_HOST` | (system default) | Docker daemon socket to connect to |

## Tools

### Container Lifecycle

#### `run`

Run a new container.

**Parameters:**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `image` | `string` | Yes | - | Docker image to run |
| `command` | `string` | No | - | Command to run in container |
| `name` | `string` | No | - | Container name |
| `ports` | `array` | No | - | Port mappings (e.g., `["8080:80"]`) |
| `volumes` | `array` | No | - | Volume mounts (e.g., `["/host:/container"]`) |
| `env` | `object` | No | - | Environment variables |
| `detach` | `boolean` | No | true | Run in detached mode |
| `network` | `string` | No | - | Network to connect to |
| `restart` | `string` | No | - | Restart policy |

**Example:**
```python
# Run nginx with port mapping
result = await registry.execute_tool(
    "docker", "run",
    image="nginx:latest",
    name="web-server",
    ports=["8080:80", "8443:443"],
    volumes=["/host/html:/usr/share/nginx/html"],
    env={"NGINX_HOST": "example.com"},
    restart="unless-stopped"
)

# Run a command in a container
result = await registry.execute_tool(
    "docker", "run",
    image="python:3.11",
    command="python --version",
    detach=False
)
```

#### `ps`

List containers.

**Parameters:**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `all` | `boolean` | No | false | Show all containers including stopped |
| `filter` | `string` | No | - | Filter by condition |
| `format` | `string` | No | table | Output format (table, json) |

**Example:**
```python
# List running containers
result = await registry.execute_tool("docker", "ps")

# List all containers
result = await registry.execute_tool("docker", "ps", all=True)

# Filter by status
result = await registry.execute_tool(
    "docker", "ps",
    filter="status=exited"
)
```

#### `stop`

Stop one or more containers.

**Parameters:**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `container` | `string` | Yes | - | Container name or ID |
| `timeout` | `integer` | No | 10 | Seconds to wait before killing |

#### `start`

Start one or more stopped containers.

**Parameters:**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `container` | `string` | Yes | - | Container name or ID |

#### `restart`

Restart a container.

**Parameters:**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `container` | `string` | Yes | - | Container name or ID |
| `timeout` | `integer` | No | 10 | Seconds to wait before killing |

#### `rm`

Remove one or more containers.

**Parameters:**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `container` | `string` | Yes | - | Container name or ID |
| `force` | `boolean` | No | false | Force removal |
| `volumes` | `boolean` | No | false | Remove associated volumes |

### Container Operations

#### `logs`

Fetch container logs.

**Parameters:**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `container` | `string` | Yes | - | Container name or ID |
| `follow` | `boolean` | No | false | Follow log output |
| `tail` | `integer` | No | 100 | Number of lines from end |
| `timestamps` | `boolean` | No | true | Show timestamps |
| `since` | `string` | No | - | Show logs since timestamp |

**Example:**
```python
# Get last 50 log lines
result = await registry.execute_tool(
    "docker", "logs",
    container="my-app",
    tail=50
)

# Get logs from last hour
result = await registry.execute_tool(
    "docker", "logs",
    container="my-app",
    since="1h"
)
```

#### `exec`

Execute command in running container.

**Parameters:**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `container` | `string` | Yes | - | Container name or ID |
| `command` | `string` | Yes | - | Command to execute |
| `interactive` | `boolean` | No | false | Keep STDIN open |
| `tty` | `boolean` | No | false | Allocate pseudo-TTY |

**Example:**
```python
# List files in container
result = await registry.execute_tool(
    "docker", "exec",
    container="my-app",
    command="ls -la /app"
)

# Get environment variables
result = await registry.execute_tool(
    "docker", "exec",
    container="my-app",
    command="env"
)
```

#### `inspect`

Return low-level information about container or image.

**Parameters:**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `target` | `string` | Yes | - | Container or image name/ID |
| `type` | `string` | No | container | Type (container or image) |
| `format` | `string` | No | - | Format output using Go template |

**Example:**
```python
# Inspect container
result = await registry.execute_tool(
    "docker", "inspect",
    target="my-container"
)

# Get specific field
result = await registry.execute_tool(
    "docker", "inspect",
    target="my-container",
    format="{{.State.Status}}"
)
```

#### `stats`

Display container resource usage statistics.

**Parameters:**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `container` | `string` | No | - | Container name or ID (omit for all) |
| `stream` | `boolean` | No | false | Stream stats |
| `no_stream` | `boolean` | No | true | Disable streaming |

### Image Operations

#### `images`

List images.

**Parameters:**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `all` | `boolean` | No | false | Show all images including intermediate |
| `filter` | `string` | No | - | Filter by condition |
| `format` | `string` | No | table | Output format |

#### `pull`

Pull an image from registry.

**Parameters:**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `image` | `string` | Yes | - | Image name with optional tag |
| `platform` | `string` | No | - | Platform (e.g., linux/amd64) |

**Example:**
```python
# Pull latest nginx
result = await registry.execute_tool(
    "docker", "pull",
    image="nginx:latest"
)

# Pull specific platform
result = await registry.execute_tool(
    "docker", "pull",
    image="nginx:latest",
    platform="linux/arm64"
)
```

#### `build`

Build an image from Dockerfile.

**Parameters:**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `path` | `string` | Yes | - | Path to build context |
| `tag` | `string` | No | - | Image tag |
| `dockerfile` | `string` | No | - | Path to Dockerfile |
| `build_args` | `object` | No | - | Build arguments |
| `no_cache` | `boolean` | No | false | Do not use cache |

**Example:**
```python
# Build with tag
result = await registry.execute_tool(
    "docker", "build",
    path=".",
    tag="myapp:v1.0",
    build_args={"VERSION": "1.0"}
)

# Build specific Dockerfile
result = await registry.execute_tool(
    "docker", "build",
    path=".",
    dockerfile="Dockerfile.prod",
    tag="myapp:prod"
)
```

#### `rmi`

Remove one or more images.

**Parameters:**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `image` | `string` | Yes | - | Image name or ID |
| `force` | `boolean` | No | false | Force removal |

### Network Operations

#### `network_ls`

List networks.

**Parameters:**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `filter` | `string` | No | - | Filter by condition |
| `format` | `string` | No | table | Output format |

#### `network_create`

Create a network.

**Parameters:**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `name` | `string` | Yes | - | Network name |
| `driver` | `string` | No | bridge | Network driver |
| `subnet` | `string` | No | - | Subnet in CIDR format |

**Example:**
```python
result = await registry.execute_tool(
    "docker", "network_create",
    name="my-network",
    driver="bridge",
    subnet="172.20.0.0/16"
)
```

#### `network_rm`

Remove a network.

**Parameters:**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `name` | `string` | Yes | - | Network name |

### Volume Operations

#### `volume_ls`

List volumes.

**Parameters:**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `filter` | `string` | No | - | Filter by condition |

#### `volume_create`

Create a volume.

**Parameters:**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `name` | `string` | Yes | - | Volume name |
| `driver` | `string` | No | local | Volume driver |

#### `volume_rm`

Remove a volume.

**Parameters:**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `name` | `string` | Yes | - | Volume name |
| `force` | `boolean` | No | false | Force removal |

### System Operations

#### `system_prune`

Remove unused data.

**Parameters:**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `all` | `boolean` | No | false | Remove all unused data |
| `volumes` | `boolean` | No | false | Prune volumes |
| `force` | `boolean` | No | false | Do not prompt for confirmation |

### Docker Compose

#### `compose_up`

Start services defined in docker-compose.yml.

**Parameters:**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `file` | `string` | No | docker-compose.yml | Compose file path |
| `services` | `array` | No | - | Specific services to start |
| `detach` | `boolean` | No | true | Run in detached mode |
| `build` | `boolean` | No | false | Build images before starting |

**Example:**
```python
# Start all services
result = await registry.execute_tool(
    "docker", "compose_up",
    file="docker-compose.yml",
    detach=True
)

# Start specific services
result = await registry.execute_tool(
    "docker", "compose_up",
    services=["web", "db"],
    build=True
)
```

#### `compose_down`

Stop and remove containers, networks.

**Parameters:**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `file` | `string` | No | docker-compose.yml | Compose file path |
| `volumes` | `boolean` | No | false | Remove volumes |
| `remove_orphans` | `boolean` | No | false | Remove orphaned containers |

## Error Handling

All tools return a standardized result dictionary:

```python
{
    "success": bool,           # True if operation succeeded
    "output": str,             # Command output on success
    "error": str | None,       # Error message on failure
    "exit_code": int | None,   # Process exit code
    "truncated": bool          # True if output was truncated
}
```

### Common Errors

- **Docker not found** - Install Docker and ensure it's in PATH
- **Connection refused** - Check Docker daemon is running
- **Permission denied** - User may need to be in docker group
- **Image not found** - Run `pull` first or check image name
- **Container not found** - Check container name/ID

## Dependencies

- `oclawma>=0.1.0` - Core OCLAWMA framework
- `pyyaml>=6.0` - YAML parsing

## Testing

```bash
# Run test suite
pytest tests/ -v

# Test with coverage
pytest --cov=src/oclawma_skill_docker
```

## Development

```bash
# Clone repository
git clone https://github.com/openclaw/oclawma-skill-docker.git
cd oclawma-skill-docker

# Create virtual environment
python -m venv venv
source venv/bin/activate

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest

# Run linting
black src tests
ruff check src tests
mypy src
```

## License

MIT License - see LICENSE file for details.

## Contributing

Contributions are welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request
