kevina1724/tmhi-watchdog repository overview

⁠TMHI Gateway Watchdog

TMHI Gateway Watchdog is a lightweight, self-hosted Docker application that monitors your internet connection and automatically reboots a supported T-Mobile Home Internet gateway when the cellular connection becomes unresponsive.

It is designed for the situation where your devices remain connected to Wi-Fi or Ethernet and the gateway is still reachable locally at 192.168.12.1, but the gateway has lost internet connectivity to the T-Mobile cellular network.

Instead of requiring someone to unplug the gateway, TMHI Gateway Watchdog signs in through the gateway's local management API and requests a reboot automatically.

⁠Features

• Continuously monitors internet connectivity
• Uses multiple independent connectivity checks
• Requires a sustained outage before taking action
• Confirms the gateway is still reachable locally
• Authenticates through the gateway's local API
• Automatically requests a gateway reboot
• Safe dry-run mode enabled by default
• Startup and post-reboot grace periods
• Reboot cooldown protection
• Maximum reboot limit per 24 hours
• Persistent SQLite event history
• Built-in web dashboard
• REST API and interactive API documentation
• Manual gateway reachability and login tests
• Docker health checks
• Supports AMD64 and ARM64 systems
• Runs entirely on your local network

⁠Supported Gateways

TMHI Gateway Watchdog currently supports gateways that use the newer local TMI/v1 API:

• Arcadyan KVD21
• Arcadyan TMOG4AR
• Sagemcom Fast 5688W
• Sercomm TMOG4SE

The Nokia 5G21 uses a different CGI-based API and is not currently supported.

Gateway compatibility may change if T-Mobile releases firmware updates that modify the local API.

⁠Docker Image

docker pull kevina1724/tmhi-watchdog:latest

Available architectures:

• linux/amd64
• linux/arm64

⁠Quick Start

Create a new directory:

mkdir -p tmhi-watchdog
cd tmhi-watchdog

Create an environment file:

nano .env

Paste the following configuration:

# Dashboard/API port
WEB_PORT=8088

# T-Mobile gateway local API
GATEWAY_HOST=192.168.12.1
GATEWAY_PORT=8080
GATEWAY_USERNAME=admin
GATEWAY_PASSWORD=replace-with-your-gateway-admin-password

# Keep enabled during initial setup
DRY_RUN=true
WATCHDOG_ENABLED=true

# Internet monitoring
CHECK_INTERVAL_SECONDS=20
FAILURE_THRESHOLD_SECONDS=180
STARTUP_GRACE_SECONDS=60

# Reboot-loop protection
POST_REBOOT_GRACE_SECONDS=480
REBOOT_COOLDOWN_SECONDS=1800
MAX_REBOOTS_PER_24H=3

# Connectivity probes
PROBE_TIMEOUT_SECONDS=5
MINIMUM_SUCCESSFUL_PROBES=2
PROBE_URLS=https://connectivitycheck.gstatic.com/generate_204,https://www.cloudflare.com/cdn-cgi/trace,http://www.msftconnecttest.com/connecttest.txt

# Protects manual API actions
API_TOKEN=replace-with-a-long-random-token

# Storage and logging
DATABASE_PATH=/data/watchdog.db
LOG_LEVEL=INFO

# Optional comma-separated origins for a separate frontend
CORS_ORIGINS=

Generate a secure API token:

openssl rand -hex 32

Copy the generated value into:

API_TOKEN=your-generated-token

Create docker-compose.yml:

nano docker-compose.yml

Paste:

services:
  tmhi-watchdog:
    image: kevina1724/tmhi-watchdog:latest
    container_name: tmhi-watchdog
    restart: unless-stopped
    pull_policy: always

    env_file:
      - .env

    ports:
      - "${WEB_PORT:-8088}:8000"

    volumes:
      - tmhi_watchdog_data:/data

    security_opt:
      - no-new-privileges:true

    cap_drop:
      - ALL

volumes:
  tmhi_watchdog_data:

Start the container:

docker compose up -d

Check its status:

docker compose ps

View logs:

docker compose logs -f tmhi-watchdog

⁠Dashboard

Open the dashboard from another device on your network:

http://YOUR-DOCKER-SERVER-IP:8088

Find your Docker server's IP on Linux:

hostname -I

Useful URLs:

• Dashboard: http://SERVER-IP:8088/
• Health check: http://SERVER-IP:8088/healthz
• API documentation: http://SERVER-IP:8088/docs
• Current status: http://SERVER-IP:8088/api/status
• Current configuration: http://SERVER-IP:8088/api/config

Do not use localhost from your phone or another computer. Use the Docker server's LAN IP address.

⁠Safe Initial Testing

Keep this enabled during setup:

DRY_RUN=true

Dry-run mode allows the application to detect outages and test reboot decisions without actually rebooting the gateway.

⁠Test the health endpoint

curl http://127.0.0.1:8088/healthz

⁠Test internet detection

docker compose exec tmhi-watchdog \
  python -m tmhi_watchdog.cli connectivity

A working internet connection should report:

{
  "online": true
}

⁠Test gateway reachability and authentication

docker compose exec tmhi-watchdog \
  python -m tmhi_watchdog.cli gateway-test

Expected result:

{
  "reachable": true,
  "authenticated": true
}

• reachable: true means the container can reach the gateway locally.
• authenticated: true means the configured administrator password works.

⁠Test a reboot request safely

Retrieve your API token:

TOKEN=$(sed -n 's/^API_TOKEN=//p' .env)

Send a manual reboot request:

curl -X POST \
  -H "X-API-Token: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"force":false}' \
  http://127.0.0.1:8088/api/reboot

With DRY_RUN=true, the gateway will not reboot.

Check the logs:

docker compose logs --tail=100 tmhi-watchdog

You should see a message similar to:

DRY RUN: gateway reboot would have been requested

⁠Enable Real Automatic Reboots

Only enable real reboots after both the connectivity test and gateway authentication test succeed.

Edit .env:

DRY_RUN=false

Recreate the container:

docker compose up -d --force-recreate

Confirm the setting:

curl http://127.0.0.1:8088/api/config

The response should include:

{
  "dry_run": false
}

Perform your first real reboot test while you are physically home and able to manually recover the gateway if necessary.

⁠Default Watchdog Behavior

By default, TMHI Gateway Watchdog:

1. Checks internet connectivity every 20 seconds.
2. Tests multiple independent endpoints.
3. Requires at least two probes to succeed.
4. Waits for three continuous minutes of failure.
5. Confirms the gateway is still reachable locally.
6. Authenticates with the gateway.
7. Requests a reboot.
8. Waits eight minutes for the gateway to restart and reconnect.
9. Prevents another reboot for 30 minutes.
10. Limits automatic reboots to three within 24 hours.

⁠Configuration

⁠Updating

Pull the newest image:

docker compose pull

Recreate the container:

docker compose up -d

Remove unused older images:

docker image prune -f

⁠Stopping the Application

docker compose down

The event database remains stored in the Docker volume.

To also permanently delete the stored event database:

docker compose down -v

⁠Troubleshooting

⁠Dashboard does not open

Check the container:

docker compose ps

Check the logs:

docker compose logs --tail=100 tmhi-watchdog

Verify the port is listening:

curl http://127.0.0.1:8088/healthz

⁠Gateway authentication fails

Verify that:

• The gateway address is 192.168.12.1
• The API port is 8080
• The username is admin
• The configured password is the gateway administrator password
• The Docker host is connected to the gateway's local network

After changing .env, recreate the container:

docker compose up -d --force-recreate

⁠The application detects an outage but does not reboot

Confirm:

DRY_RUN=false
WATCHDOG_ENABLED=true

Review the logs for:

• Startup grace period
• Post-reboot grace period
• Reboot cooldown
• Daily reboot limit
• Gateway reachability failure
• Authentication failure

⁠Port 8088 is already in use

Change:

WEB_PORT=8090

Recreate the container:

docker compose up -d --force-recreate

Then open:

http://SERVER-IP:8090

⁠Security

• Keep the dashboard available only on your trusted local network.
• Do not expose port 8088 directly to the public internet.
• Never include your gateway password or API token in a public Compose file.
• Never commit .env to GitHub.
• Use a long random API_TOKEN.
• The gateway's local API uses plain HTTP, so local network security matters.
• Use a VPN such as Tailscale for remote dashboard access while internet service is working.

⁠Important Limitations

This application can reboot the gateway only when:

• The Docker host still has power.
• The Docker host remains connected to the local network.
• The gateway's local interface remains responsive.
• The gateway still accepts local API requests.

It cannot reboot a gateway that is completely frozen, powered off, or no longer reachable through the local network. A locally controlled power relay may be useful as a hardware fallback.

⁠Source Code

GitHub:

https://github.com/kevin1724/tmhi-watchdog

Docker Hub:

https://hub.docker.com/r/kevina1724/tmhi-watchdog

⁠Disclaimer

TMHI Gateway Watchdog is an independent community project.

It is not affiliated with, endorsed by, maintained by, or supported by T-Mobile, Arcadyan, Sagemcom, Sercomm, or the HINT Control project.

Use this software at your own risk. Gateway firmware updates may change or disable the local management API.

⁠License

MIT License