docker-sleep

A Docker CLI plugin that puts containers to sleep — either by stopping them (freeing RAM, maximum power savings) or pausing them (instant resume, RAM kept) — to conserve power on a laptop or workstation.

---

Table of Contents

1. Why
2. How it works
3. Installation
4. Configuration
5. Usage
6. Commands reference
7. Uninstalling
8. Building from source

---

Why

Running Docker containers consume CPU cycles, RAM, and network I/O even when you are not actively using them. On a laptop this translates directly into battery drain, fan noise, and heat.

docker-sleep gives you a single command to quiesce all (or a named subset of) containers when stepping away, and a matching wake command to bring them back.

---

How it works

The two modes

Mode	Mechanism	RAM freed	Resume time	Best for
stop	Sends SIGTERM to PID 1 in the container, waits for graceful shutdown, then SIGKILL if it exceeds the timeout. The container image and volumes are kept; only the running process is gone.	Yes	~seconds (full start)	Maximum power savings
pause	Uses the Linux cgroups freezer subsystem to suspend all processes inside the container. They remain in memory but receive no CPU time.	No	Instant (< 1 ms)	Short breaks; need fast resume

Plugin integration

docker-sleep is a standard Docker CLI plugin (the same mechanism used by docker compose, docker buildx, etc.). The binary lives in ~/.docker/cli-plugins/ and is called transparently by the docker CLI:

docker sleep  →  ~/.docker/cli-plugins/docker-sleep sleep  [args...]

On first invocation the Docker CLI performs a metadata handshake — it calls the binary with docker-cli-plugin-metadata and expects a JSON response. This is handled automatically.

Configuration loading

On every run the plugin reads its YAML config from ~/.config/docker-sleep/config.yaml (or the path given with --config). If the file is absent the defaults are used silently. The config is re-read on every invocation, so changes take effect immediately without restarting anything.

Container targeting

1. If container names/IDs are passed on the command line, only those are acted on.
2. Otherwise, if containers is set in the config, only those are acted on.
3. Otherwise, every running container is targeted (for sleep) or every stopped/paused container (for wake).

---

Installation

Prerequisites

• Docker Engine (any recent version)
• Go 1.22+ (only needed if building from source)

One-line install (from source)

git clone https://github.com/zaihan/docker-sleep
cd docker-sleep
make install          # builds and copies to ~/.docker/cli-plugins/
make config-init      # writes example config to ~/.config/docker-sleep/config.yaml

Verify the plugin is registered:

docker sleep --help

---

Configuration

Config file location: ~/.config/docker-sleep/config.yaml

# Action to perform when "docker sleep" is run.
#   "stop"  — sends SIGTERM then SIGKILL; frees RAM, maximum power savings. (default)
#   "pause" — freezes processes via cgroups; instant resume, RAM stays allocated.
action: stop

# Seconds to wait for graceful shutdown before SIGKILL is sent.
# Only relevant when action is "stop". Use 0 for an immediate kill.
stop_timeout: 10

# Optional allowlist of container names or ID prefixes to manage.
# When empty (the default) every running container is targeted.
# containers:
#   - my-database
#   - my-api
#   - a1b2c3d4e5f6

All fields are optional. Missing fields fall back to their defaults (action: stop, stop_timeout: 10, all containers).

---

Usage

Put all running containers to sleep

docker sleep

Sleep specific containers

docker sleep my-database my-api

Override the action for a single run

docker sleep --action pause          # pause even if config says stop
docker sleep --action stop my-api

Preview without doing anything

docker sleep --dry-run

Wake everything back up

docker wake

Wake specific containers

docker wake my-database my-api

Check current config and container states

docker sleep status

Example output:

Configured action : stop
Stop timeout      : 10s
Managed containers: (all running containers)

NAME                           STATUS         ID
------------------------------------------------------------
my-database                    running        a1b2c3d4e5f6
my-api                         running        b2c3d4e5f6a1

Use a custom config file

docker sleep --config /path/to/config.yaml

---

Commands reference

docker sleep [CONTAINER...]          Stop or pause running containers
  --action string                    Override config action: "stop" or "pause"
  --dry-run                          Print what would happen without doing it
  -c, --config string                Path to config file

docker wake [CONTAINER...]           Start stopped / unpause paused containers
  -c, --config string                Path to config file

docker sleep status                  Show active config and all container states
  -c, --config string                Path to config file

---

License

This project is licensed under the GNU General Public License v2.0. See LICENSE for the full text.

---

Uninstalling

make uninstall        # removes ~/.docker/cli-plugins/docker-sleep
rm -rf ~/.config/docker-sleep

---

Building from source

make build            # produces ./docker-sleep binary
make install          # build + copy to ~/.docker/cli-plugins/
make tidy             # go mod tidy
make test             # go test ./...
make clean            # remove build artefacts