# Connect Docker

> Know when a container on your Mac crashes, runs out of memory or can't start. The alert carries its last 30 log lines, and an agent you hand it to gets them too.

Source: https://coisland.app/docs/connect-docker/

## What you need

- **You need:** No token, from Reads Docker on this Mac through its local socket
- **The form asks:** Connector name, Socket (optional)
- **You can watch:** Containers down, Containers over a limit
- **Access:** GET requests to Docker's socket on this Mac only; it never starts or stops a container

The Docker connector reads Docker on your Mac through its local socket. **Containers down** alerts when a container crashes, runs out of memory, keeps restarting, turns unhealthy or can't start. **Containers over a limit** alerts when a container's memory or CPU goes above the limit you set. Every request is a `GET`: CoIsland never starts or stops a container, and nothing is kept in the Keychain.

## Add a Docker connector

1. Open **Settings › Connectors**, click **+**, choose **Docker**.
2. **Connector name:** what monitors call it, such as `docker`.
3. **Socket:** optional. CoIsland finds the socket of Docker Desktop, OrbStack, Colima, Rancher Desktop and Podman by itself. Give a path only if yours lives somewhere else.
4. Click **Add Connector**.

**Containers down** on every container (`name:*`) comes as a recommended monitor, added in one click.

## The two kinds

| Kind | Alerts when | Example body |
|---|---|---|
| Containers down (`docker.down`) | A container crashes, is killed for running out of memory, dies, keeps restarting, turns unhealthy or can't start | `project:my-app` |
| Containers over a limit (`docker.usage`) | A container's memory goes above `memory:2GB`, or above `memory:90%` of its own limit (of Docker's memory when it has none), or its CPU above `cpu:80%` | `project:my-app memory:2GB` |

Both take `name:`, a container's name or a glob (`name:web-*`, or `name:*` for every container), `project:`, a Docker Compose project, and `image:`, an image with or without its tag (`image:postgres` matches `postgres:17`).

### Containers down

- **A crash** is a non-zero exit that isn't a stop. Exits 0, 130, 137 and 143, the codes `docker stop`, Ctrl-C and quitting Docker leave, stay quiet. A program that exits with its own error code when told to stop still alerts, and running out of memory always does.
- **A failed start** alerts with Docker's own reason, for example `Bind for 0.0.0.0:8081 failed: port is already allocated`.
- **Each crash alerts once.** The first check records what is already down, so a container that died before you added the monitor stays quiet.
- **The alert carries the container's last 30 log lines.** Hand it to Claude Code, Codex or Cortex Code and the agent gets them too.

### Containers over a limit

`memory:2GB` is an amount, `memory:90%` a share of the container's memory limit, and `cpu:80%` its CPU use. A container run without a memory limit can use all the memory Docker has, so `memory:90%` counts against that. A container alerts once when it crosses the limit, stays quiet while it stays above, and alerts again only after it dropped back under.

## A watch file

```text
-- name: My app's containers
-- kind: docker.down
-- connector: docker
-- every: 1m

project:my-app
```

## When Docker isn't running

Each Docker monitor says so on its card and alerts nothing. Quitting Docker on purpose never turns into an alert, and nothing is lost when Docker comes back.

The Docker connector watches Docker on this Mac only. Remote Docker hosts and Kubernetes aren't covered, and it never acts on a container.

## Troubleshooting

- **Docker isn't running.** Start Docker Desktop, OrbStack, Colima, Rancher Desktop or Podman. The next check reads it again.
- **Docker runs, but CoIsland doesn't reach it.** Its socket lives somewhere CoIsland doesn't look. `docker context inspect --format '{{.Endpoints.docker.Host}}'` prints it, like `unix:///Users/you/.docker/run/docker.sock`. Put the path after `unix://` in the connector's **Socket** field.

Next: the [Docker connector](https://coisland.app/docker/) for what it watches.