Description

Monitor and auto-reconnect Astrill VPN on Ubuntu Linux (deb GUI package). Detects dropped connections via tun interface + ping, then reconnects using Astrill...

README (SKILL.md)

astrill-watchdog

Name: Astrill Watchdog
Author: littlejakub

Monitors Astrill VPN on Ubuntu (deb GUI package) and automatically restarts it when the StealthVPN tunnel drops.

What it does

Watches tun0 + ping every 30 seconds. On failure, performs a full Astrill restart:

pkill astrill kills the process tree (root-owned children asproxy/asovpnc die with the parent — no sudo needed)
setsid /autostart relaunches Astrill with the full desktop environment (DISPLAY, DBUS, WAYLAND_DISPLAY) so it can initialize its GUI/Wayland stack from a systemd service context
Astrill auto-connects to the last used server

On restart failure: logs a CRITICAL block, resumes checking next cycle. Never exits.

Requirements

Ubuntu Linux, Astrill deb GUI package (/usr/local/Astrill/astrill)
ping, ip, pgrep, pkill, setsid (Ubuntu defaults)
Active desktop session (DISPLAY/DBUS/WAYLAND) — required for Astrill relaunch

Installation

bash setup.sh

No sudo. Installs the watchdog, creates a systemd user unit, and starts the service. Enabled on login automatically.

Usage

astrill-watchdog.sh start    # start watchdog (also done by systemd on login)
astrill-watchdog.sh stop     # stop watchdog
astrill-watchdog.sh status   # health summary + last 20 log lines
astrill-watchdog.sh once     # single health check + restart if needed, then exit

Files

Path	Purpose
`~/.config/astrill-watchdog/astrill-watchdog.sh`	Watchdog script
`~/.config/systemd/user/astrill-watchdog.service`	Systemd user unit
`~/.local/state/astrill-watchdog/watchdog.log`	Log file (rotates at 5000 lines)
`~/.local/state/astrill-watchdog/watchdog.pid`	PID file

Configuration

Edit the config block at the top of astrill-watchdog.sh:

CHECK_INTERVAL=30      # seconds between health checks
RECONNECT_WAIT=60      # seconds to wait after restart before health check
PING_HOST="8.8.8.8"
PING_COUNT=3
PING_TIMEOUT=3
LOG_MAX_LINES=5000

After editing, restart: systemctl --user restart astrill-watchdog.service

Diagnostics

# Live log tail
tail -f ~/.local/state/astrill-watchdog/watchdog.log

# Systemd journal
journalctl --user -u astrill-watchdog.service -n 30

# Full status summary
astrill-watchdog.sh status

Usage Guidance

This skill appears to do exactly what it advertises: it installs a systemd user unit and a watchdog script that will periodically check tun0 and ping and, if needed, kill and relaunch the Astrill GUI binary at /usr/local/Astrill/astrill. Before installing: (1) verify you trust the Astrill binary at /usr/local/Astrill/astrill (the watchdog will automatically relaunch whatever executable lives at that path); (2) confirm you want a service enabled on login that can kill and restart Astrill processes; (3) review the included scripts locally (they are small and readable) and back up any important config; (4) ensure you have a systemd user session and prefer user-level services. If any of these are concerns (e.g., you do not want automatic relaunch or you do not trust the installed Astrill binary), do not enable the service.

Capability Analysis

Type: OpenClaw Skill Name: astrill-watchdog Version: 2.0.0 The astrill-watchdog skill is a legitimate utility designed to monitor the Astrill VPN client on Ubuntu and restart it if the connection drops. It uses standard Linux networking tools (ping, ip) and process management commands (pgrep, pkill, setsid) to maintain the VPN tunnel. The installation process via setup.sh correctly configures a systemd user service and adheres to XDG directory standards without requiring root privileges. No evidence of data exfiltration, malicious code execution, or prompt injection was found.

Capability Assessment

✓ Purpose & Capability

The name/description match the files and instructions: the code checks tun0, pings a host, pkill/pgrep the Astrill binary path, and relaunches it. It requires the Astrill binary and a systemd user session — both expected for this functionality.

✓ Instruction Scope

SKILL.md and the scripts confine actions to user-level paths (~/.config, ~/.local/state) and the systemd user unit. The runtime behavior (killing/restarting Astrill, writing logs, using DISPLAY/DBUS/WAYLAND) matches the stated goal. There are no instructions to read unrelated system files, exfiltrate data, contact external endpoints, or access secrets.

✓ Install Mechanism

No remote downloads or package installs; setup.sh is included and copies scripts into user config and writes a systemd user unit. Installation is local, no sudo required, and uses standard user config/state paths.

✓ Credentials

The skill requests no environment variables or credentials. It forwards desktop-related env vars (DISPLAY, DBUS_SESSION_BUS_ADDRESS, WAYLAND_DISPLAY) to relaunch Astrill, which is proportional to restarting a GUI/Wayland app from a service context.

✓ Persistence & Privilege

The skill enables a systemd user service (starts on login) and writes only to user config/state; it does not require always:true, does not modify system-wide configuration, and does not request elevated privileges.

Version History

v2.0.0

**Major update: Simplified and streamlined Astrill VPN watchdog with updated restart mechanism.** - Full process restart now uses `pkill astrill` and `setsid /autostart` for reliable recovery and GUI compatibility. - Only one reconnect method: kills whole Astrill tree and restarts with proper desktop session variables. - Setup and usage instructions simplified; just run `setup.sh` (no sudo needed), systemd user service included. - Configuration is now centralized at the top of `astrill-watchdog.sh`, with easy comments for adjusting key options. - All relevant paths, files, and commands are clearly listed for transparency and troubleshooting. - README.md removed; documentation now included directly in SKILL.md.

v1.1.0

- Refactor: tun_up() calls ip link once instead of twice. - Refactor: desktop env vars consolidated into DESKTOP_ENV array. - Refactor: reconnect() uses method/wait arrays instead of a case block. - Refactor: ASTRILL_USER detection uses pgrep | ps -o user= instead of fragile ps aux | grep | awk. - No functional changes.

v1.0.8

- Added metadata file (_meta.json) to the project. - No changes to functionality or documentation; version remains at 1.0.7 in SKILL.md.

v1.0.7

- Fix: Added default.target to After= so the service waits for the full user session, preventing the Ubuntu 25.10 supplementary groups error. - Fix: Increased RestartSec from 10s to 15s to allow more time for session stabilisation on boot.

v1.0.6

- Fix: PID file is now written at the start of watch_loop, ensuring it’s created even when launched directly by systemd. cmd_stop and cmd_status now reliably detect the running process. - Fix: Corrected homepage URL in SKILL.md to the published ClawHub listing.

v1.0.5

- Fixed: log and PID files are now explicitly created at startup with secure permissions (600), ensuring they are never world-readable regardless of umask.

v1.0.4

- Refactor: compacted script from 312 to ~200 lines; same logic, fully visible in ClawHub preview - No functional changes; all reconnect logic, health checks, log paths and user enforcement identical to 1.0.3

v1.0.3

- Changed log storage location to a private directory (`~/.local/state/astrill-watchdog/`) with restricted permissions (mode 700). - Updated documentation to reflect new log path (`~/.local/state/astrill-watchdog/watchdog.log`) instead of `/tmp/astrill-watchdog.log`. - Clarified the `LOG_DIR` tunable parameter in the setup instructions.

v1.0.2

- Added enforcement to require the watchdog runs as the same user as the Astrill GUI process; if mismatched, the script now logs an error and exits cleanly. - Updated documentation to reflect this new user check limitation. - No other functional or behavioral changes.

v1.0.1

**Improved process handling and added no-sudo, user-service setup for the Astrill VPN Watchdog.** - No longer requires sudo; all recovery actions run as the logged-in user. - Added a `setup.sh` script to auto-install a persistent, user-level systemd service. - Reconnect escalation now cleanly restarts Astrill via `/autostart`, matching desktop autostart behavior. - Improved documentation on installation, limitations, and verification for end users. - Clarified compatibility: works only with the GUI deb package, not the CLI `.sh` installer.

v1.0.0

Initial release of astrill-watchdog. - Monitors and auto-recovers dropped Astrill VPN connections on Ubuntu (GUI deb package only). - Detects drops using tun interface state and ping checks; reconnects via Astrill's built-in /reconnect command. - Fails over through escalating recovery: reconnect command, process restart, full app restart. - Configurable intervals, logging, and check parameters. - Includes agent trigger phrases for hands-free control and systemd user service setup instructions.

Metadata

Slug astrill-watchdog

Version 2.0.0

License —

All-time Installs 1

Active Installs 1

Total Versions 11

Frequently Asked Questions

What is Astrill Watchdog?

Monitor and auto-reconnect Astrill VPN on Ubuntu Linux (deb GUI package). Detects dropped connections via tun interface + ping, then reconnects using Astrill... It is an AI Agent Skill for Claude Code / OpenClaw, with 453 downloads so far.

How do I install Astrill Watchdog?

Run "/install astrill-watchdog" in the OpenClaw or Claude Code chat to install it in one step — no extra setup required.

Is Astrill Watchdog free?

Yes, Astrill Watchdog is completely free (open-source). You can download, install and use it at no cost.

Which platforms does Astrill Watchdog support?

Astrill Watchdog is cross-platform and runs anywhere OpenClaw / Claude Code is available (cross-platform).

Who created Astrill Watchdog?

It is built and maintained by LittleJakub (@littlejakub); the current version is v2.0.0.

More Skills

Astrill Watchdog