1. Cookbook
TunnelSats Public Wireguard API
  • Announcements
    • 👋 About our team
    • 💫 What is TunnelSats?
    • 🚀 Introducing the TunnelSats Public API v1
    • 🧩 How the TunnelSats StartOS Package Uses the Public API
    • How TunnelSats Leverages Public APIs for Confined VPN Management
    • 🤖 Autonomous Agent Payments (L402 & x402) & Level 5 Agent-Native Architecture
  • 📡 Discovery
    • List Available WireGuard Servers & Regions
      GET
    • L402 Agent Payment Gateway Discovery Metadata
      GET
  • ⚡ Purchase
    • Create a New WireGuard Subscription (Invoice Generation)
      POST
    • Check Invoice Status & Polling by Payment Hash
      GET
    • Claim WireGuard Configuration After Payment Settlement
      POST
    • Autonomous Agent HTTP 402 Gateway (L402 Purchase + Claim)
      POST
  • 🔄 Lifecycle
    • Get Subscription & Bandwidth Status by WireGuard Public Key
      POST
    • Sync Subscription (Real-Time Server Refresh)
      POST
    • Renew an Existing VPN Subscription (Anonymous)
      POST
    • Request Bandwidth Top-Up ($1 Usage Reset)
      POST
  • 🔑 Account
    • List Account Subscriptions (Authenticated)
      GET
    • Create Referral Code
      POST
    • Get Referral Code
      GET
    • Referral History
      GET
  • 🔧 Tools
    • Lightning Node Network Address Discovery
    • Universal Connectivity & Latency Probe
  • Cookbook
    • 🛠️ Automation & Code Examples
    • 🐚 Bash One-Liners
    • 🚑 Node Health & Upkeep
    • ⚡ Bandwidth Top-Up ($1 Usage Reset)
    • 🛡️ Security & Authentication
    • 🎁 Referral Program: Earn Bonus Months
    • 🛑 Error Codes & Troubleshooting
    • 🤖 Agent Payments: L402 & x402 Protocol
  • Schemas
    • Server
    • InvoiceOrder
    • SubscriptionStatus
    • NodeLookup
    • ConnectivityResult
    • ApiError
    • ClaimResult
    • BandwidthResetResponse
    • PublicKeyStatusResponse
    • SubscriptionListItem
    • ReferralCode
    • ReferralHistory
    • BandwidthResetPaymentStatus
    • RenewalOrder
    • SyncResult
Tunnelsats Github
Tunnelsats Telegram
  1. Cookbook

🚑 Node Health & Upkeep

Maintaining a 24/7 VPN connection is essential for Lightning Node operations. This guide provides scripts to automate the monitoring and recovery of your TunnelSats tunnel.

🔍 1. Monitoring Tunnel Health#

The most reliable way to check if your VPN is truly "Up" is to verify the WireGuard handshake.

Health Check Script#

Save this script as tunnelsats-monitor.sh:
Finding your Interface Name
TunnelSats interface names match your config file. Run wg show | grep interface to confirm yours (usually tunnelsatsv2 or tunnelsats-region).

🛠️ 2. Auto-Healing & IP Migrations#

TunnelSats nodes may occasionally migrate IPs for maintenance. If your handshake fails for more than 5 minutes, our internal logic likely updated the DNS.

The "Auto-Sync" Pattern#

If your tunnel is down, don't just restart WireGuard. Instead, call the Sync API to get fresh data from the VPN server, or the Status API to check by WireGuard key.

Option A: Sync by Payment Hash (Authenticated)#

Force a real-time refresh of subscription data. This verifies your peer is still active on the server.

Option B: Status by WireGuard Key (Unauthenticated)#

Check bandwidth and expiry without needing an API key.

📉 3. Bandwidth Auto-Recovery#

The VPN server does not throttle. When a key uses up its 100 GB monthly allowance, its peer is disabled; a paid reset sets the usage counter back to 0 and re-enables it. The API accepts a reset at any usage, so decide in your client when one is worth it. A common policy is to request a reset only at high usage, as this script does.
Apply your own reset policy
Always apply your own usage policy before paying. Don't rely on the API to reject resets you don't need.
For the full bandwidth-reset documentation, see ⚡ Bandwidth Top-Up ($1 Usage Reset).

📊 4. Checking Server Status#

Before you troubleshoot your local node, check if the TunnelSats region is online.

✅ Node Integration Checklist#

For developers building integrations for Umbrel, Start9, or RaspiBlitz, follow this checklist to ensure a seamless user experience.

The Provisioning Flow#

Server Selection: Use GET /api/public/v1/servers to allow users to pick the region closest to them.
In-App Payment: Display the BOLT11 invoice clearly.
Polling UI: Progress indicator while polling GET /api/public/v1/subscription/{paymentHash}.

Configuration Management#

WireGuard Claim: Always offer a way to "Claim" the config again if the initial download fails.
Self-Healing: If wg show indicates no handshake for >3 minutes, automatically call /sync (authenticated) or /status (by key) to verify the server hasn't migrated.
Bandwidth Monitoring: Periodically check /status and warn users when bandwidth_used_gb reaches 70% of bandwidth_limit_gb. Before offering a reset, show the usage it gives back and bandwidth_resets_this_month / max_resets_per_month.
Custom Keys
We recommend generating keys on our server (leaving wgPublicKey empty) for the easiest setup. However, for maximum privacy, allow advanced users to provide their own wgPublicKey.

Best Practices for Upkeep#

Persist your paymentHash: Store it in a file like /mnt/data/tunnelsats.hash.
Add a Cron Job: Run the health check every 5 minutes: */5 * * * * /path/to/tunnelsats-monitor.sh.
Monitor Latency: If users report high latency, use POST /api/public/v1/ping/test to find a better region.
Modified at 2026-10-16 19:46:33
Previous
🐚 Bash One-Liners
Next
⚡ Bandwidth Top-Up ($1 Usage Reset)
Built with