README.md

May 2, 2026 · View on GitHub

gotify-commander

A remote control for your servers. The first Gotify plugin that talks back.

You're at a cafe. Your phone buzzes -- a service is down. You tap restart nginx. Five seconds later: nginx restarted.

No laptop. No SSH. No terminal. Just your phone and the Gotify app you already use.

23 commands. A visual control panel. Multi-machine support. One YAML config. Every other Gotify plugin forwards notifications somewhere else. This one lets you act on them.

Demo

Commands & Service Management	GPS Location

Send commands, get results as notifications	Click to play

How It Works

Phone (Gotify app)
      |
      |  "restart nginx"
      v
  Gotify Server  <------------------------------+
      |                                          |
      v                                          |
gotify-commander plugin                    Web UI (Pico CSS)
      |                                    browser dashboard
      +-- local: systemctl restart nginx   (VPS services)
      +-- SSH:   launchctl unload/load     (Mac services)
                            |
                            v
                      Response sent back
                            |
                            v
                  Phone notification
                  "Restart Nginx -- restarted on VPS (:80)"

Commands and responses flow through a single unified Gotify app -- no separate channels to manage. Send a command, get the reply as the next notification.

Quick Start

Download gotify-commander-linux-amd64.so from Releases
Drop it in Gotify's plugin directory (usually /opt/gotify/data/plugins/)
Restart Gotify: sudo systemctl restart gotify
Open the Gotify WebUI -> Plugins -> gotify-commander -> Configure -> paste your YAML
Enable the plugin
Send help from the Gotify app on your phone

Access the web control panel at https://your-gotify-domain/plugin/gotify-commander/.

Docker Installation

If you run Gotify in Docker, mount the plugin into the container:

# docker-compose.yml
services:
  gotify:
    image: gotify/server:2.6.1
    volumes:
      - ./gotify-data:/app/data
      - ./gotify-commander-linux-amd64.so:/app/data/plugins/gotify-commander.so
    ports:
      - "2006:80"

Download gotify-commander-linux-amd64.so from Releases and place it next to your docker-compose.yml.

Important: The .so file must be compiled with the exact same Go version as your Gotify image. The pre-built binary is compiled against Gotify 2.6.1.

Command Reference

Help command output showing all available commands and configured services

Service Management (7)

Command	Args	Description
`status`	`[service]`	Status of all services, or a specific one
`restart`	`<service>`	Restart a service (supports aliases)
`start`	`<service>`	Start a service
`stop`	`<service>`	Stop a service
`logs`	`<service>`	Tail the last N lines of service logs
`services`	--	List all managed services
`help`	--	Show command reference + control panel link

System Diagnostics (9)

Command	Args	Description
`free`	`[vps/mac]`	Memory usage
`df`	`[vps/mac]`	Disk usage (via duf)
`uptime`	`[vps/mac]`	System uptime + load average
`top`	`[vps/mac]`	Top processes by CPU/memory
`who`	`[vps/mac]`	Currently logged-in users
`ping`	`[vps/mac]`	Connectivity check
`ip`	`[vps/mac]`	IP addresses
`ports`	`[vps/mac]`	Listening ports
`connections`	`[vps/mac]`	Socket statistics

Monitoring & Analytics (4)

Command	Args	Description
`traffic`	`[service]`	Nginx traffic analysis via rhit (last 3 months)
`analytics`	--	Web analytics summary via goaccess
`certs`	--	SSL certificate expiry for all domains
`updates`	--	Pending system updates (apt)

Location (1)

Command	Args	Description
`locate`	`<lat> <lon>`	GPS reverse geocoding via OpenStreetMap

Danger (2)

Command	Args	Description
`reboot`	`<vps/mac>`	Reboot a machine (requires explicit target)
`shutdown`	`<vps/mac>`	Shutdown a machine (requires explicit target)

Universal aliases: mem/memory -> free -- disk/space -> df -- log -> logs -- up -> uptime

Typing just a service name (e.g. nginx) is treated as status nginx.

Web UI Control Panel

Web UI Control Panel showing command buttons, category tabs, and command history

A browser dashboard built with Pico CSS lives at https://your-domain/plugin/gotify-commander/.

Live service status grid -- all services, grouped by category, color-coded
One-click restart / start / stop for any service
Command history with timestamps and results
System metrics (memory, disk, uptime) at a glance
Dynamic favicons fetched from service domains
Dynamic categories from your YAML config -- no hardcoding

Access is secured through your existing Gotify login. No extra credentials.

Configuration

Configure via Gotify WebUI -- no config files to edit manually. See config.example.yaml for the full structure.

gotify:
  server_url: "http://localhost:2006"
  base_url: "https://gotify.example.com"   # public URL for web UI links
  client_token: "your-client-token"        # from Gotify -> Clients
  command_app_id: 1                        # ID of the unified command/response app
  response_app_token: "your-token"         # token for the same app

defaults:
  timeout: 30s
  log_lines: 30

# Categories -- tabs in the web UI
# type: machine (VPS/Mac buttons), service (service list), direct (runs immediately)
categories:
  - label: "Machine"
    type: machine
    commands: [free, df, uptime, who, top, ports, ip, connections, updates, ping]
  - label: "Sites"
    type: service
    commands: [restart, stop, start, logs, traffic]
  - label: "Monitoring"
    type: direct
    commands: [status, analytics, certs, services]
  - label: "Danger"
    type: machine
    danger: true
    commands: [reboot, shutdown]

services:
  nginx:
    description: "Web Server"
    domain: "example.com"
    machine: vps
    port: 80
    aliases: [ng, web]
    systemd: nginx

  homeserver:
    description: "Home Server"
    machine: mac
    port: 8080
    aliases: [home]
    launchd: com.myapp.service

Required fields per machine type:

machine: vps -- requires systemd (unit name for systemctl)
machine: mac -- requires launchd (label for launchctl) + SSH target configured

Getting Your Gotify Tokens

client_token: Go to Gotify WebUI -> Clients -> Create a new client -> copy the token
command_app_id: The plugin creates its own app (ID shown in Plugins page). Set this to that app's ID for unified commands + responses
response_app_token: Not used in unified mode -- can be any valid app token

Multi-Machine

gotify-commander supports two machine types out of the box:

VPS -- commands run locally on the same server where Gotify is installed. Uses systemctl for service management.

Mac -- commands are sent over SSH to a remote Mac Mini or MacBook. Uses launchctl for service management.

ssh_targets:
  mac:                            # must be named "mac" to auto-wire
    host: "100.x.x.x"            # Tailscale IP recommended
    port: 22
    user: "admin"
    key_file: "/home/admin/.ssh/id_rsa"

Once configured, free mac, df mac, uptime mac, and services with machine: mac all route through SSH automatically.

Security

gotify-commander executes real system commands on your server. Treat it with the same caution as SSH access.

Who Can Trigger Commands

Anyone who can send a message to the configured Gotify app can execute commands. This includes Gotify users with access to that application, or anyone who obtains a valid app token.
The web control panel serves its HTML page without authentication. The API endpoints (/execute, /health, /config) are protected by web_password if configured -- but it is not set by default. Without it, anyone who can reach your Gotify server can execute commands through the web UI.

What Can Be Executed

Only the 23 registered commands can run. No arbitrary command execution.
Service names are validated against ^[a-zA-Z0-9][a-zA-Z0-9._-]*$ and must match your configured whitelist.
Most commands use exec.Command (no shell). However, four commands use bash -c: certs, traffic, analytics, and locate. User input reaching these shells is validated (alphanumeric for service names, numeric-only for GPS coordinates), but a shell is invoked.
The plugin runs with the same permissions as the Gotify process.

Hardening Recommendations

Run Gotify behind a VPN (Tailscale, WireGuard). Do not expose Gotify to the public internet. This is the single most important security measure.
Set a strong Gotify admin password.
Set web_password in your config to protect the web control panel.
Use HTTPS for all Gotify traffic.
Restrict Gotify app tokens. Only create tokens for devices you control.

Defense Layers

Layer	Status
Command whitelist (23 commands)	Enforced
Input sanitization (regex)	Enforced
Service name whitelist	Enforced
Execution timeouts (30s default)	Enforced
Gotify authentication	Enforced (Gotify's own auth)
Web UI API authentication	Optional (`web_password`, off by default)
Rate limiting	Not implemented
Per-command authorization	Not implemented
SSH host key verification	Disabled (`InsecureIgnoreHostKey`)

Comparison

Feature	gotify-commander	Telegram Bots	Uptime Kuma
Self-hosted	Yes	No	Yes
Bidirectional	Yes	Yes	No
Runs inside Gotify	Yes	No	No
No third-party services	Yes	No	Yes
Service management	Yes	varies	No
Multi-machine (SSH)	Yes	varies	No
Web control panel	Yes	No	Yes
Traffic & analytics	Yes	No	No
GPS locate	Yes	No	No
Tailscale security	Yes	No	No
Phone app already installed	Yes	Yes	No

External Dependencies

Some commands rely on utilities installed on the server. The plugin works without them, but those specific commands will fail.

Command	Requires	Install	Notes
`df`	duf	`apt install duf`	Required -- command fails if not installed
`traffic`	rhit	Download from releases	Nginx log analyzer
`analytics`	goaccess	`apt install goaccess`	Web analytics from nginx logs
`analytics`	`python3`	Pre-installed on most distros	Parses goaccess CSV output
`locate`	`python3` + `curl`	Pre-installed on most distros	Reverse geocoding via Nominatim
`certs`	`openssl`	Pre-installed on most distros	Reads Let's Encrypt certificates
`ports`	`ss`	Part of `iproute2`	Socket statistics
`top`	`ps`	Part of `procps`	Process listing

All other commands use standard Linux utilities (systemctl, free, uptime, who, hostname, journalctl).

Building from Source

The plugin must be built on Linux with CGO_ENABLED=1 (Go plugins require cgo).

git clone https://github.com/drolosoft/gotify-commander
cd gotify-commander
go build -buildmode=plugin -o gotify-commander.so .
sudo cp gotify-commander.so /opt/gotify/data/plugins/
sudo systemctl restart gotify

Using the Makefile:

make test          # run unit tests
make lint          # go vet
make deploy        # SSH -> build on VPS -> install -> restart Gotify
make deploy-dev    # fast deploy, skip tests

The deploy target connects to your VPS via Tailscale, pulls the latest commit, builds in place, copies the .so, and restarts Gotify in one step.