Show HN: Doormouse – a reverse proxy that wakes sleeping servers via Wake-on-LAN Doormouse, a new open-source reverse proxy from developer darksworm, wakes sleeping servers via Wake-on-LAN when requests arrive, then suspends them after inactivity, cutting power use for homelab machines like NAS, GPU boxes, and game servers. The tool, available as a Docker image on GitHub Container Registry, runs on an always-on host like a Raspberry Pi, sends magic packets to boot targets, and supports HTTP and raw TCP, with configuration via config.toml. 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. Note "Sleep" is whatever your shutdown command does, so suspend, hibernate and full poweroff all work. Poweroff wakes the most reliably. Suspend is faster but some boards will not resume from it. Test yours before you depend on it. 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. Important Host networking is required. Wake-on-LAN needs to broadcast, which Docker's default bridge network will not carry. Because host networking does not remap ports, the proxy is reachable on whatever port says. Set port = ":80" if you want the URL without a port, or put doormouse behind a front proxy that terminates TLS. - A request arrives for a configured hostname or listen port. - doormouse checks cached machine health. If the host is up, it forwards immediately. - Otherwise it sends magic packets every 500ms and polls until the host answers or timeout expires. - It then waits for the route to be ready, which is a separate check. - It forwards the request and streams the response back. - 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. | Matched on | destination | Shares port | | |---|---|---|---| HTTP | hostname Host header | http://nas.local:2283 | Yes | TCP | listen port own socket | nas.local:22 | No | 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. Note Your client still sees a different address. It connects to doormouse-host:2222 , not nas.local:22 , so OpenSSH looks up a different known hosts entry and prompts on first use. To keep one entry for both paths, set HostKeyAlias : Host nas-via-doormouse HostName doormouse-host Port 2222 HostKeyAlias nas.local Warning A TCP route is a new way in to that service. The example above exposes the NAS's sshd on every interface the doormouse host listens on. Authentication is unaffected, since sshd still authenticates every connection. But a service that was previously reachable only from your LAN now depends on where you run the proxy. Bind it somewhere you trust. 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.Enough to try it out, tedious past that. /etc/hosts on one client. 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. Warning A public A record holding a private address such as 10.0.0.5 is dropped by some resolvers as DNS rebinding. Use a local override instead. 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://... . Note Readiness is polled only while the machine is live. A machine that sleeps all day therefore generates no per-route traffic. 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. Tip An open ssh session holds the machine awake even while nothing is typed, so a forgotten terminal keeps it up all night. Let sshd close idle sessions itself and the threshold can do its job. In sshd config on the target: ChannelTimeout =10m UnusedConnectionTimeout 1m Requires OpenSSH 9.3 or newer. 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" 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 Every check would fail, the machine would look permanently dead, and every request would try to wake it. health check . A TCP routes need destination that cannot work. 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 It must start with health check the checker cannot dispatch on. 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. Caution The last rule can break an upgrade. A config carrying a key from an older version will now fail to start. Read the error, drop the key, restart. 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