Gotify Commander

Features

Architecture

gotify-commander loads as a native Gotify plugin (.so). It intercepts messages on a unified command app, executes the matching whitelisted command, and sends the result back as a notification on the same app.

The plugin runs inside the Gotify server process: no separate daemon, no extra ports, no external dependencies. Commands go to local systemctl, remote SSH/launchctl or diagnostic tools, as set in the YAML. The web UI is served at the plugin's webhook path.

Quick Start

Download the file for your Gotify version, copy it into the plugin directory and restart Gotify. Under two minutes.

Downloads

Pick the file of your Gotify version; gotify version tells you which one you run. Gotify 3.x needs the Android app 2.10.1 or newer. Earlier versions are on the releases page.

Install

1. Download the file for your Gotify version and architecture, and check it against its .sha256.
2. Copy it to the Gotify plugin directory: usually /opt/gotify/data/plugins/, or the plugins folder of your Docker data volume.
3. Restart Gotify.
4. In the Gotify WebUI, create a client (Clients → Create client) and copy its token now: Gotify 3 shows it only once.
5. Open Plugins → gotify-commander, paste your YAML in Configure and enable the plugin.
6. The plugin page now shows the control panel link and the generated panel password.
7. Send help from the Gotify app on your phone.

Command Reference

27 commands in 6 categories. All of them accept aliases and machine targets.

🔄 Service Management (7)

📊 System Diagnostics (9)

🌐 Monitoring & Analytics (4)

📍 Location (1)

🧰 Operations (4)

The four Operations commands are new in 0.4. docker acts only on the containers listed in docker.allowed_containers, and digest can arrive on its own every day at digest.at when digest.enabled is on.

⚠ Danger (2)

Universal aliases: mem/memory → free · disk/space → df · log → logs · up → uptime. Typing just a service name is treated as status <service>.

Why Gotify Commander?

Every other Gotify plugin forwards notifications somewhere else. This one lets you act on them.

Web Control Panel

A console for your machines in the browser, served by the plugin inside Gotify. The link is on the plugin page, next to the password.

• A command line that suggests commands, machines, services and containers while you type: Tab completes, Enter runs, the up arrow recalls, / or Ctrl+K focuses it
• The commands of your YAML categories beside the output on a wide screen and in tabs on a phone, with a service picker grouped by machine (favicon, description and port)
• A session with every command, whether it worked, how long it took and its output, with buttons to copy it, run it again and remove it. The browser keeps it for 24 hours
• Dangerous commands ask first in a dialog, with Cancel focused
• Answers in Markdown are drawn as tables and links, and locate shows its map
• Light and dark theme that follows the system, a page size from 50 % to 125 % and a padlock that forgets the password

The panel is protected by default. When no password is set, the plugin generates one and shows it only on the plugin page in Gotify; set web_password to use your own. The browser keeps it until you close the tab.

Configuration

All configuration lives in a single YAML file, editable in the Gotify WebUI. Define your services, categories, machines, domains and aliases. A service you add shows up everywhere.

Security

• Panel password: the web control panel is protected by default. When no password is set, the plugin generates one and shows it only on the plugin page in Gotify. Set web_password to use your own.
• Administrators only: only Gotify administrators get a working plugin instance. For other users the plugin page shows a notice and nothing starts.
• Command whitelist: only the 27 registered commands run, with no arbitrary execution. List the ones you want in enabled_commands to allow fewer.
• No shell: commands run through exec.Command without a shell, except two fixed scripts that get your input only as arguments. Service names must match ^[a-zA-Z0-9][a-zA-Z0-9._-]*$ and your configured list.
• Timeouts: every command has a timeout (30 s by default) that kills its whole process group, so nothing is left running.
• SSH host keys: SSH targets are checked against known_hosts, with no fallback to an unverified connection. Add the key as the user that runs Gotify: ssh-keyscan -p <port> <host> >> ~/.ssh/known_hosts.
• Confirmation (optional): commands listed in require_confirm ask for a one-time code before they run when they arrive as a message.
• Rate limit: 20 messages per minute per plugin instance. One over the limit does not run, and the reply says how long to wait.
• Reboot requires a target: reboot alone returns an error, so a machine is never rebooted by accident.
• SSH key only: password authentication is not supported.
• Audit trail: every command is logged with timestamp, command, source, result and duration.
• VPN: run Gotify behind Tailscale or WireGuard and do not expose it to the public internet.

When Gotify restarts

Commands posted while the plugin was offline, for example during a Gotify restart, run when it reconnects if they are younger than the replay window: replay_window, 5 minutes by default, and 0s turns it off.

Platform Compatibility

A Go plugin loads only when it was built with the same Go version and module versions as the Gotify server, so each release ships one file per Gotify version and architecture.

Built With

A single Go plugin (.so) with no runtime dependencies beyond Gotify itself.

• Go Plugin (.so): loads natively inside the Gotify server
• Gotify Plugin API: first-class integration, no hacks
• SSH: remote machine management over standard SSH
• YAML Config: human-readable, editable in the WebUI
• Plain HTML, CSS and JavaScript: the control panel is one page with no framework, served under a strict Content Security Policy
• Gin: lightweight HTTP router for the control panel