Docker Socket Proxy

# Docker Socket Proxy

Manages Docker containers via the `tecnativa/docker-socket-proxy` REST API using `curl` and `jq`. Which modes are available depends on which API sections the proxy instance has enabled.

## Trigger conditions

- User asks to list, start, stop, restart, kill, pause, or unpause a container or service
- User wants container logs, stats, top processes, or filesystem changes
- User asks about Docker images, networks, volumes, swarm services, or tasks
- A service needs to be restarted after a config change

## Usage

```
bash {baseDir}/scripts/run-docker.sh <mode> [args...]
```

Run with no arguments for full usage. Proxy URL is resolved from `$DOCKER_PROXY_URL` → `$DOCKER_HOST` (tcp→http) → `http://localhost:2375`.

## Modes

### System
| Mode | Description |
|------|-------------|
| `ping` | Health check |
| `version` | Docker version |
| `info` | Host summary (containers, memory, etc.) |
| `events [--since T] [--until T] [--filters k=v]` | Recent events (1s window) |
| `system-df` | Disk usage by images/containers/volumes |

### Containers
| Mode | Description |
|------|-------------|
| `list` | Running containers |
| `list-all` | All containers including stopped |
| `inspect <name>` | Full container details |
| `top <name> [ps-args]` | Running processes inside container |
| `logs <name> [tail]` | Container logs (default tail=100) |
| `stats <name>` | CPU, memory, network, block I/O |
| `changes <name>` | Filesystem changes since start |
| `start <name>` | Start container |
| `stop <name> [timeout]` | Stop container |
| `restart <name> [timeout]` | Restart container |
| `kill <name> [signal]` | Kill container (default SIGKILL) |
| `pause <name>` | Pause container |
| `unpause <name>` | Unpause container |
| `rename <name> <new-name>` | Rename container |
| `exec <name> <cmd> [args...]` | Run command in container |
| `prune-containers` | Remove stopped containers |

### Images
| Mode | Description |
|------|-------------|
| `images` | List images...

# Docker Socket Proxy

OpenClaw skill for managing Docker containers via a [Tecnativa docker-socket-proxy](https://github.com/Tecnativa/docker-socket-proxy) instance.

## Why docker-socket-proxy

Exposing the raw Docker socket to an agent is equivalent to giving it root access to the host — it can mount any path, run privileged containers, or do anything the Docker daemon allows.

docker-socket-proxy sits in front of the socket and acts as a firewall. Each API section (containers, images, networks, volumes, Swarm, etc.) is individually toggled on or off via env vars. The agent can only do what you explicitly enable. If you only turn on `CONTAINERS=1` and `ALLOW_RESTARTS=1`, it can restart containers and nothing else.

Use this skill when you want an agent that can manage Docker without handing it the keys to the host.

## Requirements

- [`tecnativa/docker-socket-proxy`](https://github.com/Tecnativa/docker-socket-proxy) running and exposed over TCP
- `$DOCKER_HOST` set to the proxy address (e.g. `tcp://docker-host:2375`), or `$DOCKER_PROXY_URL` set to the HTTP equivalent
- `curl` and `jq` on PATH

## Features

Covers the full Docker REST API surface exposed by docker-socket-proxy:

| Category | Operations |
|----------|-----------|
| System | ping, version, info, events, disk usage |
| Containers | list, inspect, top, logs, stats, filesystem changes, start, stop, restart, kill, pause, unpause, rename, exec, prune |
| Images | list, inspect, history, prune |
| Networks | list, inspect, prune |
| Volumes | list, inspect, prune |
| Swarm | info, nodes, services, tasks, configs, secrets |
| Plugins | list |

Available modes depend on which API sections are enabled on your proxy instance. Disabled sections return HTTP 403.

## Installation

```bash
clawhub install docker-socket-proxy
```

Or copy the skill directory into your OpenClaw workspace:

```
~/.openclaw/workspace/skills/docker-socket-proxy/
```

## Usage

```bash
bash {baseDir}/scripts/run-docker.sh <mode> [args...