Stowaway – start Docker containers when you open them, put them to sleep when idle (Compose plugin friendly)

Hi all,

I've been working on a small project for my own OMV box and it's grown into something I think others here might find useful, so I'm sharing it.

What it is

Stowaway sits between your dashboard or bookmarks and your containers' web interfaces. When you open an app's link, Stowaway starts the container, shows a short "waking up" page, and then passes you through to the app as normal. When nobody has used it for a while, it stops the container again.

I built it because I had a pile of containers I only open now and then, plus a habit of trying out new ones. They were all running 24/7 and eating RAM and CPU for nothing. Now you can install as many as you like and only the ones you're actually using are running.

Main features

• Wake on demand: opening the link starts the container. It works with macvlan containers too.
• Sleep when idle: you set the idle time per app. It won't put an app to sleep while it's busy, judged by CPU or network activity, so a transcode or download isn't cut off.
• "Only when I say so" mode: the app is never put to sleep automatically. You start and stop it from the dashboard or Home Assistant.
• Companion containers: for apps with helpers, like Tdarr and its nodes. The helpers wake and sleep together with the main app, and a busy node keeps the app awake.
• Scheduled maintenance: restarts and image updates on a schedule, with rollback if an update fails.
• Dashboard tiles: status for Homarr, Homepage, Dashy, Glance and Heimdall. The status checks never wake the app.
• Home Assistant integration (HACS): switches, sensors and buttons per app. For example, you could put the media server to sleep when everyone leaves home.
• Diagnostics: optional debug logging, with a report you can download. Passwords and tokens are removed from it automatically.
• Small footprint: about 40 MB of RAM, and close to 0% CPU when idle.

Installing with the OMV Compose plugin

Go to Services → Compose → Files → Add, and paste:

yaml

services:  stowaway:    image: ghcr.io/sat32blk/stowaway:latest    container_name: stowaway    restart: unless-stopped    network_mode: host    # Only needed if you have containers on macvlan, uncomment these AND MACVLAN_HELPER_IP:    # cap_add:    #   - NET_ADMIN    environment:      - DASHBOARD_PORT=8880      - TZ=America/New_York      # - MACVLAN_HELPER_IP=192.168.1.250   # a free IP outside your DHCP range    volumes:      - /var/run/docker.sock:/var/run/docker.sock      - ${DOCKER_DATA}/stowaway:/config

Save it and click Up. Then open http://<your-omv-ip>:8880, create your account, and tick Enable Stowaway on the containers you want managed. Each app gets its own link port. Point your dashboard or bookmark at that link instead of the container's port.

Notes for OMV users

• Containers you created with the Compose plugin work as they are. You don't have to change their compose files.
• If you use macvlan, for example for a container with its own IP, Stowaway needs NET_ADMIN and a spare IP. Linux normally blocks the host from talking to its own macvlan containers, so Stowaway adds a small helper interface to get around that. If you already have a macvlan shim set up, it uses that instead.
• After a reboot, managed apps stay asleep until someone opens them. That's on purpose.

Links

• GitHub: https://github.com/Sat32blk/Stowaway
• Home Assistant integration: https://github.com/Sat32blk/stowaway-homeassistant

It's MIT licensed and free. I'm running it on my own OMV 7 server with Navidrome on macvlan and Tdarr with three nodes, but I'd really like to hear how it does on other setups. Bug reports, feature ideas and "this broke my thing" posts are all welcome, here or as a GitHub issue. The dashboard has a Report a problem button that fills in most of the details for you.

Thanks!

Stowaway is now at v1.6.4

When I first posted, Stowaway was at v1.1.0. Quite a bit has been added since then, so here’s a roundup.

One page for everything

The dashboard now lists every container on your server in one list. Each app’s panel shows:

• how it sleeps
• whether an update is waiting
• its CPU and memory use
• what opened it last (which device, Home Assistant, a schedule…)

Click Let Stowaway manage on the ones you want put to sleep. The top of the page shows how much memory and CPU sleeping apps are saving.

Dashboards set up and kept up to date for you

You no longer have to copy settings into your dashboard by hand. In an app’s settings, click Add to Homarr, Add to Heimdall, Add to Homepage or Add to Glance:

• Homarr: Stowaway adds the app through Homarr’s API.
• Heimdall: it creates the tile with the app’s own icon, in the category you pick.
• Homepage and Glance: it writes their config file.

This works with dashboards on macvlan too. From then on, your dashboard shows each app’s live status: In Use, Sleeping in 8 min, Idle or Sleeping. Checking the status never wakes the app. After a Stowaway update, the same button brings the dashboard’s setup up to date. Dashy and others can use the status address.

There’s also a tile for Stowaway itself, showing how many apps are awake or asleep and how much memory and CPU sleeping is freeing. You pick which numbers it shows, and Homarr, Heimdall and Glance follow your choices automatically.

Updates and scheduled restarts

Stowaway checks your containers for newer images. You can install an update with one click, or let it happen automatically when the app wakes or at a scheduled restart. If the new version won’t start, it goes back to the old one. Any container can be restarted (and optionally updated) daily, weekly or monthly, even ones Stowaway doesn’t put to sleep.

Settings per app, in tabs

Each app’s settings window has tabs:

• sleep timer
• staying awake (while busy, or set awake hours)
• address
• companions
• updates
• dashboards
• Home Assistant

Companion containers, like Tdarr’s nodes, wake and sleep with their app and keep it awake while they’re busy.

Home Assistant

There’s an integration you can install through HACS. Each app gets:

• an awake switch
• a keep-awake timer
• sleep mode, CPU, memory and “last woken by” sensors

That’s handy for things like putting the media servers to sleep when nobody’s home. Apps you add to or remove from Stowaway show up in Home Assistant, or disappear from it, on their own.

Also:

• HTTPS with Let’s Encrypt
• macvlan and ipvlan support
• a sign-in for the dashboard
• a new icon

Stowaway itself still uses about 40 MB of memory.

Upgrading: pull ghcr.io/sat32blk/stowaway:latest and bring the stack up again. Your settings carry over.

GitHub: https://github.com/Sat32blk/Stowaway

Home Assistant integration: https://github.com/Sat32blk/stowaway-homeassistant

If you’re running it on OMV, I’d love to hear how it goes, especially with the Compose plugin and macvlan. Bug reports and ideas are welcome here or on GitHub.