Everything you need to run BadgerOS

Getting started

BadgerOS installs directly on the same machine as your Minecraft server(s) and manages them locally — start/stop, console, backups, players, plugins, and more, all from one dashboard. It doesn't run your server for you or move it anywhere; it finds the server(s) you already have on disk and gives you a proper control panel for them.

Two ways to get going:

• Guided setup — answers a couple of questions, hands you one command to paste into your VPS.
• curl -fsSL https://badgerstudios.net/install.sh | bash — if you already know what you're doing.

Requirements

• A Linux VPS or server with bash, curl, openssl, and python3 (the installer checks for all four and tells you exactly what's missing).
• An existing Minecraft server (or Velocity/Waterfall/BungeeCord proxy) already on disk — BadgerOS finds and manages what's there, it doesn't provision a new one for you.
• Outbound internet access to badgerstudios.net — every install, free or Premium, registers here once to get its unique id and license. There's no offline install path.

Installing

Guided setup

The setup wizard asks your server's name, your OS family, and your Minecraft server type, then generates a single install command tailored to your answers. Paste it into your VPS and the wizard's progress bar picks up automatically once your server registers — no need to copy anything back and forth.

Direct install

curl -fsSL https://badgerstudios.net/install.sh | bash

Non-interactively (for scripts/CI), set the server name and skip prompts with an environment variable:

curl -fsSL https://badgerstudios.net/install.sh | BADGEROS_PANEL_NAME="My Server" bash

What install.sh does

1. Confirms the control plane is actually reachable over the internet — the install fails here on purpose if it isn't, since every install needs its own id and license.
2. Asks your Minecraft server's name. This becomes the name shown on your panel.
3. Generates an Ed25519 keypair locally. The private key never leaves your machine.
4. Registers with the control plane, which assigns a unique agent id and immediately issues a signed Free-plan license certificate — no waiting, no browser step required for Free. Optionally asks for an email too, so a badgerstudios.net account can find this install later — entirely separate from Premium, and skippable.
5. Offers to upgrade to Premium right away. Say yes and it walks you through checkout and pastes back a signed Premium certificate; say no and upgrade any time later from the same claim link.
6. Downloads the actual panel software from the same signed release channel later updates use, verifies its signature and checksum, installs it, and starts it as a systemd service (survives reboots). Also sets up a hosted dashboard link (a badgerstudios.net subdomain via a Cloudflare Tunnel) on a best-effort basis, then prints your one-time owner login and how to reach the dashboard.
7. Prints the exact ufw commands to open the ports your Minecraft server(s) need.

Your hosted dashboard link

Every install gets a badgerstudios.net subdomain that tunnels straight to your panel — Cloudflare's edge is the only thing actually public; your panel still only listens on 127.0.0.1, exactly like an SSH tunnel would reach it, just without you needing to open one by hand. This is set up automatically near the end of install.sh and printed as "Your dashboard" when it finishes. It's best-effort — if it can't be set up (no outbound access to Cloudflare, an unsupported CPU architecture), the install still succeeds and falls back to the SSH-tunnel instructions below.

The address itself is auto-generated from your server's name on Free; Premium accounts can instead choose their own from the dashboard.

Signing in without a password every time

Visiting the hosted link directly still shows your panel's own login screen — the same owner account and password as always. If you'd rather not re-type it, create a free account at badgerstudios.net using the email you linked during install (optional, and separate from Premium — install.sh asks for one either way). Signing in there and picking a server hands you off to your panel already signed in, using a short-lived, signed one-time link rather than a second password — your panel's own login is still the only real credential that exists.

Supported server types

BadgerOS auto-detects your server software — start/stop/console/backups work identically across all of them, no configuration needed:

Not sure what you're running? Pick "Not sure yet" in the setup wizard — BadgerOS detects it for you after install.

Firewall & ports

At the end of a successful install, you'll see something like this — paste it as shown:

sudo ufw allow 25565/tcp comment 'Minecraft'
sudo ufw allow 25566/tcp comment 'Minecraft (secondary)'
sudo ufw reload

Don't open port 8770 — the dashboard binds to 127.0.0.1 only, by design, so nothing on the internet can reach it directly no matter what your firewall allows. Reach it over an SSH tunnel (ssh -L 8770:127.0.0.1:8770 you@your-server) or put an HTTPS reverse proxy in front of it — the installer prints both options when it finishes.

Free vs Premium

AI Assistant add-on — $20/mo

A separate add-on rather than a plan tier: it stacks on top of Free or Premium and doesn't change whichever one you're on. It puts a chat bubble in your dashboard (and a badgeros agent chat command in your terminal) backed by an AI that can actually operate the server — start, stop and restart it, run console commands, read the console, and read or edit config and plugin files.

Every shell command it runs is confined to that one server's directory by a bubblewrap sandbox, so it cannot reach the rest of your box even if something goes wrong or the model is fed a malicious instruction inside a file it reads. It's owner-only — administrators don't get it by default, because it's the same trust level as handing out shell access.

You supply the model: bring your own key from Anthropic or OpenRouter, or point it at a local Codex CLI. Buy it from the same claim link you'd use to upgrade; it switches on automatically within a few hours, or immediately if you paste the activation code.

Upgrading to Premium

Every install prints a claim link (also shown on the install script's Free-plan confirmation). Opening it asks for the email you'd like the subscription tied to, then takes you through Stripe Checkout. When payment completes, the page shows a short activation code — paste that code back into the terminal where the install script is waiting (or re-run install.sh and answer "yes" to the upgrade prompt at any time). That's the one manual step: activation has to happen on your own machine, since it's what actually unlocks your local panel.

Custom themes (Premium)

Premium accounts can upload their own CSS file from Settings to restyle the dashboard — colors, layout, fonts, imagery, almost anything, without ever touching the panel's own code. It's loaded after every built-in stylesheet, so it has the final say. Free accounts get the default Badger Violet theme; Premium unlocks four more built-in themes plus custom uploads.

Where files live

That directory holds your agent keypair (agent.key / agent.pub), your agent id, license.json (the signed certificate your panel checks locally to know its own plan), the panel software itself under app/, and FIRST_RUN_PASSWORD.txt — your one-time owner login, printed once by the installer and safe to delete once you've signed in and changed it.

Troubleshooting

"Could not reach the control plane"

Check this machine's outbound internet access (a corporate firewall or restrictive security group is the usual cause), then re-run the install command. Nothing is written until this check passes.

Re-running the installer

Safe to do any time. If an agent keypair already exists in the state directory, it's reused rather than regenerated — your agent id and plan stay the same.

Lost your claim link

It's https://badgerstudios.net/claim/<your-agent-id> — your agent id is saved in the state directory (see above) if you need to find it again.

Error codes

Every failure BadgerOS can report has a code. Your panel shows these under Settings › Error log, along with what each one means and what to do about it. Quote the code if you contact support — it is far more useful than a screenshot of the message.

FAQ

Does BadgerOS see my Minecraft data?

No. It runs entirely on your own server; the control plane only ever handles registration, licensing, and billing.

Can I self-host without any of this?

The control-plane registration step is required for every install — it's how your unique license is issued. There's no offline mode.

What happens if I downgrade from Premium?

Your dashboard falls back to the free default theme and Premium-only features lock again, but nothing about your Minecraft server itself changes.