carbon-panel

module
v1.0.39 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 28, 2026 License: MIT

README

A self-hosted, Docker-native control plane for Minecraft servers.
Every server in its own container — players routed by hostname, modpacks shipped straight from CurseForge and Modrinth.

Continuous Integration Go 1.26 Docker

Website • Quick start • Features • Fleet • Issues

11+
server types
0 B
idle RAM with deep-sleep
∞
machines, one panel
MPL-2.0
permanently open

Why Carbon Panel?

Hosting servers shouldn't feel like babysitting.

One flaky plugin, one forgotten backup, one accidental rm -rf and the whole night is gone. Carbon Panel treats your worlds the way production teams treat state: isolated, observable, and recoverable.

The usual way

Hand-rolled scripts and bare JVM processes on a shared host.
  • One bad mod corrupts every world sharing the host
  • Port-forwarding a new server means editing firewall rules
  • Backups are a cron job nobody has ever restored from
  • Idle servers burn RAM all night, every night
The Carbon way

Every server is a Docker container with real limits, routes and history.
  • Blast radius is one container, never the host
  • New server = new hostname, routed automatically
  • World-aware backups with retention and offsite copies
  • Deep-sleep to zero RAM, wakes when a player connects

Features

A control plane, not a start button. From container orchestration to modpack distribution, Carbon Panel ships the whole toolchain — opinionated where it matters, self-hosted everywhere.

Docker-native server management

Deploy vanilla, Paper, Purpur, Fabric, Quilt, Forge, NeoForge and Bedrock in seconds — each in its own container with CPU and RAM limits, automatic Java selection, and Aikar-tuned JVM presets.

vanilla paper fabric forge bedrock
One port, every server

A handshake-aware reverse proxy routes players by hostname through a single ingress — with Velocity forwarding, PROXY protocol, and Bedrock UDP built in.

:25565 SRV velocity bedrock udp
Modpack Studio

Search CurseForge and Modrinth without an API key, resolve dependencies and loader versions automatically, and export to .mrpack or packwiz.

curseforge modrinth packwiz
Live console & RCON

Stream ANSI-rendered logs over WebSocket with command history and an interactive RCON shell.

websocket ansi mclo.gs
Full file manager

Browse, edit, zip and bulk-download files with resumable uploads and SHA-256 verified remote pulls.

resumable zip / unzip
Backups that restore

World-aware snapshots pause saves through RCON, respect retention rules, and push offsite to S3-compatible storage.

S3 / MinIO retention
Your machines, one panel

Add your home machine, a homelab box, or a cloud VPS as a node — then place each server wherever it makes sense. Routes and state stay in sync.

home lab cloud VPS placement
Automation & scheduling

Cron, interval and event-driven task chains — commands, backups, webhooks, even Chunky pre-generation and Git modpack updates.

cron chains webhooks
Security & access

Role-based access control, OIDC single sign-on, scoped API tokens, invite links, and an audit log of everything.

RBAC OIDC audit
Typed, observable API

Protocol Buffers over Connect RPC & gRPC, with a live OpenAPI viewer, reflection, and Prometheus metrics endpoints.

Connect RPC OpenAPI Prometheus
Sleep, freeze, wake on join — Empty servers can freeze in place at ~0% CPU, or stop entirely at zero RAM while the proxy keeps answering pings. Either way, a player joining brings them back — nothing to start by hand, no admin in the loop.

freeze deep-sleep 0 B wake-on-connect

One panel. Every machine.

Carbon Panel runs Minecraft servers wherever you have machines — the PC in your room, a box in the closet, a VPS in the cloud — and manages them as one fleet behind one address. Put each world on the machine that suits it, spread the load across the hardware you already own, and move anything between nodes as your players change.

Live migration Move a server to another node from the panel. The world transfers, the route is repointed and the container starts on the target — same hostname the whole way.
Standby replicas Keep a copy of a world warm on a second machine. Promote it and players are back on the same address with the last state that reached the replica.
Scheduled backups Snapshots run on a cron or interval schedule, flush saves through RCON first, respect retention rules, and upload to any S3-compatible bucket.
Capacity guard Every placement is measured against the target node's real memory headroom, so a migration or a wake never oversubscribes a machine.

Quick start

1. Build the image

git clone https://github.com/athNdev/carbon-panel.git
cd carbon-panel

docker build -f docker/Dockerfile.carbon-panel -t carbon-panel:latest .

2. Bring the stack up

docker compose up -d

Then open http://localhost:8080.

Deploy with docker run instead
docker run -d \
  --name carbon-panel \
  --restart unless-stopped \
  --network host \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ./data:/app/data \
  -v ./backups:/app/backups \
  -v ./tmp:/app/tmp \
  -v ./config.yaml:/app/config.yaml:ro \
  -e CARBONPANEL_DATA_DIR=/app/data \
  -e CARBONPANEL_HOST_DATA_PATH="$(pwd)/data" \
  -e TZ=UTC \
  carbon-panel:latest
Build from source

Requirements: Go (v1.26+) and Bun (v1.2+).

# Generate the RPC/API code using buf in docker (optional if pre-generated)
docker run --rm -v "$(pwd):/workspace" -w /workspace bufbuild/buf:latest generate

# Install dependencies and build the frontend
cd web/carbon-panel && bun install && bun run build && cd ../..

# Build the backend
go build -o carbon-panel cmd/carbon-panel/main.go

# Start Carbon Panel
./carbon-panel
Live development (hot reloading)

Starts the Go backend (Air live reload) and the SvelteKit frontend (Vite HMR) together:

# Bun
bun run dev

# or Make
make dev

# or Windows (PowerShell)
.\scripts\dev.ps1

# or Linux/macOS (Bash)
./scripts/dev.sh

Docker deployment

The Compose file in the repository is the recommended shape. Host networking keeps the proxy and every server port reachable without extra mapping; bridge mode works too and Carbon Panel attaches itself to the managed Docker network on startup.

services:
  carbon-panel:
    image: carbon-panel:latest
    container_name: carbon-panel
    restart: unless-stopped

    # Recommended: host network mode
    network_mode: host

    # Bridge mode with port mapping
    # ports:
    #   - "8080:8080"         # Carbon Panel web interface
    #   - "25565:25565"       # Minecraft default proxy port
    #   - "25565-25665:25565-25665/tcp"

    volumes:
      # Docker socket for orchestrating server containers
      - /var/run/docker.sock:/var/run/docker.sock
      # Data directories on the host
      - ./data:/app/data
      - ./backups:/app/backups
      - ./tmp:/app/tmp
      #- ./config.yaml:/app/config.yaml:ro

    environment:
      - CARBONPANEL_DATA_DIR=/app/data
      - CARBONPANEL_HOST_DATA_PATH=/opt/carbon-panel/data
      - TZ=UTC

    extra_hosts:
      - "host.docker.internal:host-gateway"

Configuration

Carbon Panel loads configuration from config.yaml or environment variables:

server:
  port: "8080"
  host: "0.0.0.0"

storage:
  data_dir: "./data"
  backup_dir: "./backups"

proxy:
  enabled: true
  base_url: "minecraft.yourdomain.com"
  listen_ports: [25565]

API & extensibility

A comprehensive Connect-RPC & gRPC API, typed end to end with Protocol Buffers:

# List managed servers
curl http://localhost:8080/carbonpanel.v1.ServerService/ListServers

# Restart a server
curl -X POST http://localhost:8080/carbonpanel.v1.ServerService/RestartServer \
  -H "Content-Type: application/json" \
  -d '{"id": "your-server-id"}'

How it compares

Purpose-built for Minecraft servers — a quick look at how Carbon Panel compares with the common alternatives.

Capability Carbon Panel Raw Docker Compose Typical free panel
Per-server container isolation ✅ Built-in ✅ Manual ◐ Sometimes
Hostname-based player routing ✅ One port ❌ DIY ❌ Rare
Modpack studio (CurseForge / Modrinth) ✅ Keyless ❌ — ◐ Add-ons
Multi-node clustering ✅ First-class ◐ DIY ◐ Paid tiers
Deep-sleep & wake-on-connect ✅ Zero-RAM idle ❌ — ❌ —
Typed API & Prometheus metrics ✅ Connect RPC ❌ Shell ◐ Varies
Open source & self-hosted ✅ MPL-2.0 ✅ Yours ◐ Varies

Comparison reflects publicly documented, commonly available capabilities and is a general guide — evaluate each option against your own requirements.


Acknowledgments & credits

Carbon Panel (formerly MineServer) is built upon the open-source foundation of the original DiscoPanel project created by nickheyer.


License

Carbon Panel's own code is licensed under the Mozilla Public License 2.0 (LICENSE.MPL-2.0) — free as in cost, free as in speech, and permanently open.

Material inherited from DiscoPanel remains under the MIT License (LICENSE), Copyright (c) 2025 Nicholas W. Heyer. LICENSING.md documents the file-by-file boundary between the two.

Directories

Path Synopsis
cmd
carbon-fault-harness command
carbon-fault-harness is an explicit, opt-in runner for isolated Docker integration environments.
carbon-fault-harness is an explicit, opt-in runner for isolated Docker integration environments.
carbon-panel command
carbon-storage command
carbon-storage is a line-oriented JSON worker intended to run locally now and over Docker attach/exec in a later transport adapter.
carbon-storage is a line-oriented JSON worker intended to run locally now and over Docker attach/exec in a later transport adapter.
geyser command
geyser/pin
Package pin downloads one checksummed Geyser standalone jar.
Package pin downloads one checksummed Geyser standalone jar.
knowledge-lint command
Command knowledge-lint validates the repository knowledge base.
Command knowledge-lint validates the repository knowledge base.
status command
internal
backupcrypt
Package backupcrypt implements the versioned authenticated encrypted backup artifact format (OSS-236).
Package backupcrypt implements the versioned authenticated encrypted backup artifact format (OSS-236).
db
nodestorage
Package nodestorage routes server file, configuration and content I/O through the node that owns the server (ADR 0005).
Package nodestorage routes server file, configuration and content I/O through the node that owns the server (ADR 0005).
operation
Package operation recovers server mutations that were interrupted by a panel crash or restart.
Package operation recovers server mutations that were interrupted by a panel crash or restart.
plugindb
Package plugindb provides per-server plugin database provisioning (MINE-191).
Package plugindb provides per-server plugin database provisioning (MINE-191).
reconciler
Package reconciler contains the event-source foundation for a future self-healing reconciler (MINE-107).
Package reconciler contains the event-source foundation for a future self-healing reconciler (MINE-107).
rpc
s3
sftp
Package sftp provides a chrooted per-server SFTP entry point (MINE-190).
Package sftp provides a chrooted per-server SFTP entry point (MINE-190).
testharness
Package testharness contains opt-in Docker API fault-injection helpers.
Package testharness contains opt-in Docker API fault-injection helpers.
worldstore
Package worldstore provides a node-scoped local filesystem implementation for server world operations.
Package worldstore provides a node-scoped local filesystem implementation for server world operations.
ws
pkg
web

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL