Mousehole, a Seedbox IP Updater for MAM

A background service to update a seedbox IP for MAM and an HTTP server to manage it.

This can be helpful if you are using a host/VPN/seedbox to seed and its IP address is not stable.

Features:

• Background service that regularly updates MAM with the IP address of the host.

Before an update, Mousehole checks that it actually needs to update by comparing the host's current IP address and AS and with the last MAM response.

• Frontend website to manage the service, allowing:
• Setting your MAM cookie
• Displaying status information
• Manual triggering of checks
• API server with management endpoints.

See API.md for details.

Getting Started

To use Mousehole, you need to:

• Run the service
• Set your MAM cookie via the web interface
• Handle MAM errors (if any)

Running the service

#### Docker Compose (recommended)

services:
  gluetun:
    image: qmcgaw/gluetun:latest
    cap_add:
      
NET_ADMIN
    
devices:
      
/dev/net/tun:/dev/net/tun
    
ports:
      
"5010:5010" # Mousehole port
      
"8080:8080" # qBittorrent Web UI port
      
"6881:6881/tcp" # qBittorrent TCP torrent port
      
"6881:6881/udp" # qBittorrent UDP torrent port
    
environment:
      VPN_SERVICE_PROVIDER: "your-vpn-provider"
      FIREWALL_VPN_INPUT_PORTS: "6881" # qBittorrent torrent
      # more is needed here -- see Gluetun documentation
      # https://github.com/qdm12/gluetun-wiki
      # https://github.com/qdm12/gluetun-wiki/tree/main/setup/providers
    restart: unless-stopped
  qbittorrent:
    image: lscr.io/linuxserver/qbittorrent:latest
    network_mode: "service:gluetun"
    environment:
      TZ: Etc/UTC # Set to your timezone for localization
      WEBUI_PORT: 8080
      TORRENTING_PORT: 6881
    restart: unless-stopped
  mousehole:
    image: tmmrtn/mousehole:latest
    network_mode: "service:gluetun"
    environment:
      TZ: Etc/UTC # Set to your timezone for localization
    volumes:
      # persist cookie data across container restarts
      
"mousehole:/srv/mousehole"
    
restart: unless-stopped
volumes:
  mousehole:

Starter Docker Compose examples:

• ⭐ Gluetun + qBittorrent + Mousehole
• Wireguard + qBittorrent + Mousehole
• Non-VPN Example

Any VPN setup can be adapted to include Mousehole as a sidecar. See Using Mousehole as a Sidecar with Docker Compose for details.

#### Unraid

See the Unraid Installation Guide for instructions.

#### Local

Run the server with:

bun run start

Setting Your MAM Cookie

Once Mousehole is running, navigate to its web UI at http://:5010 in your browser. This is likely to be if you are running it locally.

When running for the first time (or if the cookie gets out of sync), you need to set Mousehole's cookie manually.

On navigating to the Mousehole web interface, you will see a form to set the cookie -- paste your cookie and click the "Set" button.

If you need help getting the cookie, click the "What do I enter here?" button for a tutorial.

Handling Errors

Even with Mousehole up and running, things can still go wrong that Mousehole cannot fix automatically. Here are some of the common ones:

• "Invalid session - ASN mismatch"
• "Invalid session - Invalid cookie"
• "Last Change too recent"

Docker Tags

Mousehole publishes several image tags to Docker Hub:

• SemVer versions (0, 0.1, 0.1.11, etc)
• latest, the latest released version
• edge, the tip of master branch
• Pull requests targeting master for testing, tagged as pr-

Choose latest if you do not know which to pick.

Environment Variables

• MOUSEHOLE_PORT: _(Default 5010)_ The port on which the HTTP server will

listen.

• MOUSEHOLE_STATE_DIR_PATH: _(Default /srv/mousehole)_ The directory where

the service will store its data.

• MOUSEHOLE_USER_AGENT: _(Default mousehole-by-timtimtim/)_ The

user agent to use for requests to MAM.

• MOUSEHOLE_CHECK_INTERVAL_SECONDS: _(Default 300 (5 minutes))_ The interval

in seconds between checks.

• MOUSEHOLE_STALE_RESPONSE_SECONDS: _(Default 86400 (1 day))_ The number of

seconds after which a MAM response is considered stale. This ensures that Mousehole is still talking with MAM at some regular interval and is detecting out-of-band changes to the cookie.

• TZ: _(Default Etc/UTC)_ The timezone for displaying localized times.

Contributing

Want to contribute? Check out the contribution guidelines.

There is also a contrib directory with useful, supplementary functionality.

Links

• Repository
• Docker Hub image
• Forum post

Development

• Start the dev server with:

``bash bun run dev `

• New versions can be tagged, released and pushed to Docker Hub by simply

changing the version in package.json` and pushing to GitHub. The CI workflows will take care of the rest.

Attribution

Mouse Hole by Sergey Demushkin from Noun Project (CC BY 3.0)

--- Tranlated By Open Ai Tx | Last indexed: 2026-04-12 ---