Installation

Runs on

Velocity

Minecraft

1.7 → 26.3

Java

21+

Requirements

Proxy software	Velocity 4.2+ (Velocity-CTD works too)
Java	21 or newer
Players	Java Edition, and Bedrock through Geyser + Floodgate
Optional	packetevents for Velocity (the clickable menu), Floodgate (to recognise Bedrock players)

Kalkan runs only on the proxy. Your backend servers (Paper, Folia, Canvas or anything else) need nothing.

Install

1. Stop the proxy.
2. Put Kalkan-1.1.1.jar into the Velocity plugins/ folder. For the clickable menu, add packetevents for Velocity as well.
3. Start the proxy. Kalkan writes plugins/kalkan/config.yml, takes the license key from your download and checks it. The console says License OK — Kalkan is active. and the data file (about 10 MB) downloads in the background. It refreshes every 10 minutes after that.
4. Kalkan starts in monitor mode: nobody is kicked yet. Optional: add your own countries, for example /kalkan country home add US.
5. After a day, look at /kalkan report. When the numbers look right, switch to block mode with /kalkan mode block or the Mode button in the menu.

The license

• One license covers two proxies. Moving to a new machine needs no ticket: when both places are taken, a proxy that has been offline for 24 hours gives its place to the new one by itself. For more proxies at once, open a ticket in our Discord.
• Moved servers or key leaked? Open kalkan.teamatlantis.xyz/reset and enter your license key. Reset servers (IP reset) removes your old servers from the license at once, up to 3 times a day. Get a new key gives you a new key once you download Kalkan from BuiltByBit within the next hour: the page then shows the new key, kalkan license <new-key> in the console switches to it without a restart, and the old key stops working everywhere within 30 minutes.
• Kalkan checks the license when the proxy starts and every 30 minutes. If the license server can’t be reached, a key it accepted in the last 7 days keeps working.
• kalkan license shows the state: the key (shortened), this proxy’s id and the last check. kalkan license <key> sets a new key and checks it right away.
• Updating keeps your license. Every download of a new version carries the same key, and your proxy keeps its place in the count. If we renew your key, for example after it leaked, download Kalkan again and replace the jar: it switches to the new key by itself.
• If the key is unknown, revoked or over the proxy limit, the console says so in a framed message and repeats it every 30 minutes. Staff with kalkan.admin see the same line in chat when they join.

Permissions

Permission	What it gives
kalkan.admin	/kalkan, the menu and every subcommand. Every menu click checks it again.
kalkan.alerts	Chat alerts: the attack-mode warning, and every blocked login when staff-alerts is on.

With LuckPerms on Velocity, for example: lpv user Steve permission set kalkan.admin true.

Files it creates

plugins/kalkan/
  config.yml                      settings; the menu rewrites this file
  trusted.tsv                     the days each player joined from a clean address
  data/kalkan.db                  the data file (downloaded)
  data/server-id                  a random id for this proxy, for the license's proxy count
  data/license.dat                when the license was last accepted (for the 7-day grace)
  logs/decisions-YYYY-MM-DD.tsv   one line per login decision
  logs/ping-YYYY-MM-DD.tsv        ping probe measurements (experimental)

Bringing your join history

To make your regulars trusted from day one, put a trusted-seed.tsv into plugins/kalkan/ before you start the proxy. One player per line: the name, a tab, then the dates they joined from a home or mobile connection, separated by commas.

steve	2026-10-01,2026-10-04,2026-10-09
alex	2026-10-02,2026-10-03

Kalkan merges it into trusted.tsv on startup and renames the file to trusted-seed.tsv.loaded.

Next: How it decides.