A reverse proxy that wakes your servers when someone knocks.

Most homelabs grow one machine that costs real money to run: a NAS with a stack of spinning disks, a box with a GPU in it for LLM inference or transcoding, an old workstation kept around for backups. You need it a few hours a day. It draws power for all twenty-four. Turning it off saves that power, but then the services on it are gone exactly when you want them.

doormouse closes that gap. Run it on the small machine you already keep on all the time — a Raspberry Pi, a mini PC, whatever hosts your lighter services — and put it in front of the expensive one. When a request arrives for a sleeping machine, doormouse sends a Wake-on-LAN magic packet, waits for the host to boot, and forwards the request. The client sees one slow response instead of a connection error. Once the machine has been idle long enough, doormouse suspends it again.

It handles HTTP and raw TCP, so the same proxy can front a web app and ssh. A few things it fronts well:

• A NAS serving photos, media or backups in bursts, idle the rest of the day.
• A GPU box for local LLMs or transcoding, awake only while you are asking it something.
• A game server that sleeps until the first player connects.
• A build or CI machine you hit a handful of times a week.

• A target host with Wake-on-LAN enabled. Most wired NICs support it, but it is usually off by default in the BIOS and sometimes in the OS as well.
• An always-on host to run doormouse. A Raspberry Pi is enough.
• Both hosts in the same broadcast domain. Magic packets do not route.

Write config.toml:

port = ":8080"
timeout = "1m"
poll_interval = "5s"
health_check_interval = "30s"
health_cache_duration = "10s"

[[machines]]
name = "nas"
mac_address = "7c:8b:ad:da:be:51"
broadcast_ip = "10.0.0.255"
health_check = "tcp://nas.local:22"
inactivity_threshold = "1h"

ssh_host = "nas.local:22"
ssh_user = "doormouse"
ssh_key_path = "/app/ssh_key"
shutdown_command = "sudo systemctl suspend"

[[routes]]
machine = "nas"
hostname = "photos.example.com"
destination = "http://nas.local:2283"

Then bring it up:

services:
  doormouse:
    image: ghcr.io/darksworm/doormouse:latest
    network_mode: host
    restart: unless-stopped
    volumes:
      - ./config.toml:/app/config.toml
      - ./ssh_key:/app/ssh_key

docker compose up -d

Point photos.example.com at the doormouse host, then open http://photos.example.com:8080. The NAS wakes.

1. A request arrives for a configured hostname or listen port.
2. doormouse checks cached machine health. If the host is up, it forwards immediately.
3. Otherwise it sends magic packets every 500ms and polls until the host answers or timeout expires.
4. It then waits for the route to be ready, which is a separate check.
5. It forwards the request and streams the response back.
6. When no route has seen traffic for inactivity_threshold and no connection is open, it runs the shutdown command.

A machine is a host. doormouse wakes and suspends it as one unit.

A route is one way in to that machine. One machine can carry many routes: a NAS might serve photos, files and ssh. That is one machine and three routes. Traffic on any route keeps the whole machine awake.

A route is reached one way or the other, never both.

HTTP routes multiplex on the Host header, so any number of them share one port. Raw TCP carries no such header. Each TCP route therefore needs its own listener.

# HTTP route, matched on the Host header.
[[routes]]
machine = "nas"
hostname = "photos.example.com"
destination = "http://nas.local:2283"

# TCP route, own port: ssh -p 2222 you@doormouse-host
[[routes]]
machine = "nas"
listen_port = 2222
destination = "nas.local:22"

TCP connections are spliced byte for byte. The upstream host key reaches your client unmodified, so there is no man-in-the-middle and no key substitution.

Host nas-via-doormouse
    HostName doormouse-host
    Port 2222
    HostKeyAlias nas.local

doormouse deals with two kinds of name, resolved in two different places.

A route's hostname is what the client asks for. It has to resolve to the doormouse host. Not to the machine you want woken, which is asleep and cannot answer.

A route's destination is what doormouse dials. It resolves on the doormouse host, on your LAN.

So photos.example.com points at your Raspberry Pi, and doormouse forwards to nas.local:2283 behind it.

Use whichever you already run:

• A local DNS server, such as Pi-hole, AdGuard Home, dnsmasq or your router. Add an A record for the hostname with the doormouse host's IP. A wildcard like *.home.example.com saves you a record per route.
• /etc/hosts on one client. Enough to try it out, tedious past that.
• Public DNS, if you own the domain. Point the A record at the doormouse host.

TCP routes are matched on a port, not a name, so any name that reaches the doormouse host will do, including the bare IP.

destination and health_check have to resolve while the machine is asleep. A name that only exists while the host is up cannot be used to wake it. Give the machine a DHCP reservation and a static DNS entry, or write the IP straight into the config.

There are two health_check fields and they answer different questions.

machines[].health_check is liveness: is the host up? It drives Wake-on-LAN and the wake wait. Point it at something that is always running:

health_check = "tcp://nas.local:22"

Do not point it at a single application. If that application crashes, doormouse concludes the host is down and fires magic packets at a machine that is already awake.

routes[].health_check is readiness: can this route serve? It gates forwarding for that route alone. It defaults to dialling destination, inferring :80 or :443 from the URL scheme when the port is implicit.

Point it at a real health endpoint when a service takes noticeably longer to come up than the host does:

health_check = "http://nas.local:2283/api/server/ping"

Otherwise a successful wake still yields a 502, because the host is up but the service is not yet listening.

Three forms are accepted: tcp://host:port, http://... and https://....

inactivity_threshold = "1h"

doormouse suspends a machine when both conditions hold:

• No route has seen traffic for inactivity_threshold.
• No forwarded connection is still open.

The second condition matters. An ssh session is idle by nature, and a large upload can outlast the threshold. Neither should be cut off mid-flight.

Omit the field, or set "0s", to never shut the machine down.

ChannelTimeout *=10m
UnusedConnectionTimeout 1m

Configure exactly one per machine.

Over SSH:

ssh_host = "nas.local:22"
ssh_user = "doormouse"
ssh_key_path = "/app/ssh_key"
shutdown_command = "sudo systemctl suspend"

The key has to be readable by the user doormouse runs as, which in the container is UID 1000. doormouse checks the key at startup and warns if it cannot open it, because the key itself is only used much later, when the machine goes idle.

Over HTTP:

shutdown_http_url = "http://nas.local/api/shutdown"
shutdown_http_method = "POST"   # optional, defaults to POST
shutdown_http_ok_status = 202   # optional, defaults to any 2xx

doormouse validates the config at startup and refuses to run on a bad one, rather than starting and misbehaving later. It rejects:

• A machine with no health_check. Every check would fail, the machine would look permanently dead, and every request would try to wake it.
• A destination that cannot work. TCP routes need host:port. HTTP routes need an absolute http:// or https:// URL. A schemeless value such as nas.local:2283 parses as a URL scheme named nas.local and would otherwise 502 every request with nothing in the logs.
• A health_check the checker cannot dispatch on. It must start with tcp://, http:// or https://.
• Any unrecognised key. Typos used to decode silently to a zero value, which is the usual route to a missing health check.

SIGINT and SIGTERM trigger a graceful shutdown. doormouse stops accepting, gives in-flight HTTP requests up to 15 seconds to finish, closes the TCP listeners and exits 0. In-flight TCP connections are dropped rather than drained, so a forwarded ssh session ends when the proxy stops.

Early versions used one [[targets]] block per server. That format still loads, but it will be removed in a future release.

On startup doormouse translates an old config, logs what it did, and writes the result beside the original as <name>.migrated.toml. Review that file, then swap it in. Your original is never modified, since it is often bind-mounted read-only or checked into a config repo.

A config may use one format or the other, never both.

For migration output on the host, create a config directory before starting Compose and copy your existing config into it:

mkdir -p conf
cp config.toml conf/config.toml

Mount that directory in place of the single config file:

volumes:
  - ./conf:/app
  - ./ssh_key:/app/ssh_key:ro

The directory must be writable and the config readable by the container user. If your host UID is 1000, files created by the commands above already have the right owner. Otherwise, set user: "<UID>:<GID>" on the service, replacing the placeholders with id -u and id -g. Alternatively, use sudo chown 1000:1000 conf conf/config.toml and ensure the directory has owner write permission. The migrated file is mode 0600, owned by the container UID; using your own UID lets you read and replace it without sudo.

With the quick-start single-file mount, /app is not writable by the container user. doormouse logs the complete migrated config instead; retrieve it with docker compose logs doormouse. The same fallback applies if a mounted config directory is read-only or lacks write permission.

Every release publishes an image to ghcr.io/darksworm/doormouse, built for linux/amd64 and linux/arm64. Four tags point at it:

latest is fine for trying doormouse out. Once it is proxying something you care about, pin the exact version or the minor line, so an upgrade happens when you choose it.

The image runs as UID 1000, not root, so anything you mount in has to be readable by that user. On most Linux hosts you are 1000 already. If not, chown 1000:1000 the file or set user: on the service to your own IDs.

Ports below 1024 still work, because the binary carries the CAP_NET_BIND_SERVICE capability that Docker grants by default. If you drop capabilities, keep that one or doormouse will not start.

The file capability cannot grant privileges when no-new-privileges is enabled (see the kernel documentation). For that setup, use ports at or above 1024, or arrange for the runtime to grant NET_BIND_SERVICE to the process before execution. This also applies to Kubernetes configurations with allowPrivilegeEscalation: false.

Images up to and including 1.0.0 ran as root, so check both of those when you upgrade past it.

go build -o doormouse .
go test -race ./...

The container end-to-end suite checks the release image's wake/proxy/SSH-shutdown lifecycle, runtime permissions, and config migration:

go -C e2e test -race -count=1 -timeout=5m -v ./...

To build a local container image, only Docker is required:

docker build -t doormouse:local .

The multi-stage Dockerfile compiles Go inside Docker and packages the binary in the same non-root runtime used for releases. No host Go installation is needed. With Docker Buildx, docker buildx bake also builds and loads doormouse:local.

To check both release architectures (amd64 and arm64), configure QEMU/binfmt emulation for the runtime image's build steps, then run:

docker buildx bake release --set release.output=type=cacheonly

The release workflow uses that same Bake target to publish version, minor, major, and latest tags to GHCR. The GitHub release stays a draft until the images have been pushed successfully.

• traefik-wol, a Traefik plugin.
• caddy-wol, a Caddy plugin.

Prefer those if you already run Traefik or Caddy. doormouse runs standalone and also forwards raw TCP.

Pull requests welcome. See CONTRIBUTING.md for setup and commit conventions.

Docs aim for a Flesch-Kincaid grade of 9 or below. Many readers do not speak English as a first language, so short sentences and plain phrasing help. Keep the technical vocabulary, though: liveness, Host header and broadcast domain are shorter and clearer than talking around them.