Installing the Tickwise agent

Tickwise is an open-source plugin for Minecraft server monitoring on Paper, Purpur and Velocity. It reads the server log, strips secrets and personal data out of it and recognises known problems using a local, signed signature pack. The agent only starts sending data to the cloud after you explicitly link the server, and it cannot run commands on your server.

This guide covers the Paper plugin install, the Velocity proxy install, linking to the Telegram bot and what to do when something goes wrong. Setup takes a couple of minutes per server.

Requirements

The plugin is built against paper-api 1.21.11 and velocity-api 3.5.1. Not every version combination has been tested on live servers yet.

Getting the plugin

There are no public releases yet. Build the jars from the repository:

./gradlew :agent-paper:shadowJar :agent-velocity:shadowJar

Each jar ships with a signed signature pack and the public keys needed to verify it, so local diagnostics work straight after installation.

Installing on Paper and Purpur

1. Put Tickwise-Paper-0.1.0.jar into the plugins/ folder.
2. Restart the server.
3. Check the console: the agent reports that it has started.

The agent currently prints its console messages in Russian. The lines below are translated.

Settings live in plugins/Tickwise/config.yml, created on first start. After editing it, run /tickwise reload.

The agent detects the server role itself: backend if proxies.velocity.enabled is on in config/paper-global.yml or settings.bungeecord: true is set in spigot.yml, otherwise standalone.

If the agent fails to start, it logs that it is disabling itself and switches off only itself. The server keeps running.

Installing on Velocity

1. Put Tickwise-Velocity-0.1.0.jar into the proxy's plugins/ folder.
2. Restart the proxy.
3. Settings live in plugins/tickwise/config.toml. There is no reload command on Velocity: restart the proxy after editing the config.

Velocity networks and backends

For the cloud to merge a failure on the proxy and its cause on a backend into one incident:

• install the agent on the proxy and on every backend;
• link all servers from one Telegram chat and into one network (called default unless you name it);
• the backend's name in Tickwise must match its name in the [servers] section of velocity.toml. Set it in server.name, or in server.proxy-alias if the names differ.

server:
  name: "lobby"

Linking to the cloud and Telegram

Nothing is sent before linking. Only the console or a player with the tickwise.owner permission can start it.

1. Set the cloud address in cloud.endpoint. The default in the template is a placeholder, so the address has to be set explicitly. Only https:// is allowed.

   cloud:
     endpoint: "https://<cloud address>"
   

2. Run tickwise link in the console, optionally followed by a server name. The agent prints a one-time code valid for 15 minutes.

3. Send the code to the Tickwise bot in Telegram: /link CODE [server-name] [network]. You can do this in a private chat or in a group; in a group the bot accepts the command only from chat administrators. The bot shows the agent's name, platform, version and masked IP — make sure it is your server.

4. Confirm the link in the console.

The chat that sent the first /link becomes the organisation: all servers linked from that chat see each other, and server crash alerts arrive in Telegram in that chat. What the bot can do after linking is described on the Telegram bot page.

For Docker and automation there is cloud.auto-link: true: linking starts by itself five seconds after startup and prints the code to the console. You still have to send it to the bot in Telegram.

Commands and permissions

Without arguments the command runs status. Every command is available from the console.

Operators get tickwise.admin by default. Nobody gets tickwise.owner by default, not even op — grant it explicitly through your permissions plugin. On Velocity, your permissions plugin grants both.

What works without the cloud

Without linking, or while the cloud is unreachable, the agent still:

• reads the log and recognises known problems with the bundled signature pack, writing findings to the console;
• answers status, diagnose and privacy;
• parses new crash reports and hs_err_pid*.log files on startup and detects crash loops (three failed starts within 30 minutes).

Without the cloud there are no Telegram alerts, no incident page, no merging of proxy and backend errors and no signature pack updates. If the cloud is unreachable after linking, data queues on disk (up to 50 MB by default) and is sent once the connection is back.

Troubleshooting

The first step is always tickwise status in the console: it shows the cloud state, the last send error and when the next attempt is due. The messages below are paraphrased from the Russian originals.

The agent also recognises problems in the Velocity network itself. The most common ones when setting up forwarding: modern forwarding mismatch, forwarding secret mismatch and backend unreachable from the proxy. The full list is in the error knowledge base.

Unlinking and removal

tickwise unlink in the console deletes the token from the server and stops sending; local diagnostics keep working. The cloud is not told: the server stays in the bot's list as offline. To remove the server from Tickwise and revoke its token, open the server card in the bot and press “🔌 Отвязать” (Unlink; the bot currently speaks Russian).

Unsent data stays in the outbox/ folder and goes out with the next link. If you don't want that, delete outbox/ before running tickwise link.

Full removal:

1. tickwise unlink.
2. Stop the server or proxy.
3. Delete the jar from plugins/.
4. Delete the data folder: plugins/Tickwise/ on Paper or plugins/tickwise/ on Velocity. It holds the token, the pseudonymisation salt, the queue and downloaded signature packs.

How the agent handles data is covered in detail on the Security page.