Contnap

At work I run tests locally — that means spinning up Postgres, and sometimes OpenSearch. The problem: once the tests are done, those containers keep running. Postgres is fine, but OpenSearch is Java, so it sits there eating RAM and draining the battery for nothing. I wanted something that would stop containers when idle and wake them back up transparently when needed, without having to touch any client configuration.

That’s contnap: a transparent proxy that manages container lifecycles automatically. It holds the port open while the container is stopped. When a connection arrives, it buffers the packets, starts the container, waits for it to be ready, then forwards traffic as if nothing happened. When the container goes idle again, it stops it.

For HTTP traffic, instead of making the client wait in silence, contnap serves a self-refreshing “Starting…” page in the browser until the container is up.

Configuration

Contnap is configured entirely through Docker labels on the containers themselves — no separate config file.

Required:

• contnap.enabled: "true" — opt the container in
• contnap.tcp_ports or contnap.udp_ports — comma-separated ports to proxy

Optional:

• contnap.timeout — inactivity threshold in seconds before stopping (default: 300)
• contnap.http_ports — ports that get the wakeup page instead of raw buffering
• contnap.group — group name to wake/stop a multi-container stack together
• contnap.pre_start / contnap.post_stop — shell commands to run before start or after stop
• contnap.machines — IP addresses or hostnames to monitor for presence
• contnap.autostart — wake the container when listed machines appear on the network
• contnap.only_listed_machines — restrict access to specified IPs only
• contnap.schedule — restrict wakeup to time windows (e.g. Mon-Fri 08:00-19:00)

Contnap integrates with Docker health checks: it waits for the container to report healthy before routing traffic, so clients never hit a half-started service.

Observability

Contnap exposes a Unix socket API for live queries and can write periodic JSON snapshots to a file, useful for monitoring or scripting around container state.

Alternatives

Two other open source projects do something similar:

ContainerNursery (TypeScript/Node.js) acts as an HTTP reverse proxy that stops idle containers and restarts them on incoming requests. It shows a loading page during warm-up and can monitor CPU usage to avoid stopping a container that is still busy. HTTP only — no TCP or UDP support.

Sablier (Go) integrates as a plugin into existing reverse proxies (Traefik, Caddy, Nginx). It supports Docker, Kubernetes, Podman, Docker Swarm, and Proxmox LXC. It also has a “scale mode” that throttles CPU and memory instead of fully stopping containers, trading resource savings for zero cold-start latency. Primarily HTTP-focused, though a third-party companion project (sablier-proxy) adds basic TCP support — blocking only, no wakeup page.

ContainerNursery is HTTP only. Contnap proxies raw TCP and UDP natively, which is what makes it usable for non-HTTP services like Postgres.

Source code: codeberg.org/slundi/contnap