This repository is a reusable GitHub template that provisions a Minecraft Java server inside a GitHub Codespace.
It brings together the server software, administration panel and public connection tunnel in one cloud environment. The setup script handles most of the installation automatically.
No manual Java installation or local Linux server configuration is required.
| Component | Role |
|---|---|
| PaperMC 1.21.4 | Minecraft Java server |
| Java 21 | Server runtime |
| Crafty Controller | Web-based administration panel |
| Playit.gg | Public Minecraft connection tunnel |
| Python 3.11 | Crafty Controller dependency |
| GitHub Codespaces | Cloud Linux environment |
| Backup scripts | Scheduled world archives |
The environment follows this architecture:
flowchart TB
A["GitHub Template Repository"] --> B["GitHub Codespaces"]
B --> C["Automatic Provisioning"]
C --> D["PaperMC Server"]
C --> E["Crafty Controller"]
C --> F["Playit.gg Agent"]
C --> G["Backup Scheduler"]
H["Minecraft Players"] --> I["Public Playit Tunnel"]
I --> D
J["Administrator"] --> K["Codespaces Port 8443"]
K --> E
G --> L["Local Backup Archives"]
style A fill:#234B32,color:#fff,stroke:#8DBD74
style B fill:#234B32,color:#fff,stroke:#8DBD74
style C fill:#356B45,color:#fff,stroke:#A5B96A
style D fill:#356B45,color:#fff,stroke:#A5B96A
style E fill:#A65335,color:#fff,stroke:#EAA16A
style F fill:#62458A,color:#fff,stroke:#B69CE0
style G fill:#80672C,color:#fff,stroke:#D6B64C
Connection flow: players connect through Playit.gg, which forwards traffic to the PaperMC server running inside the Codespace.
Administration flow: the administrator accesses Crafty Controller through the forwarded Codespaces port.
Click the button below:
Select Create a new repository, choose a name and create it.
In your new repository:
- Open the Code menu.
- Select the Codespaces tab.
- Click Create codespace on main.
The .devcontainer configuration automatically launches the provisioning process.
The main installation script is:
.devcontainer/setup.shIt performs the following operations:
- Installs system utilities.
- Installs PaperMC 1.21.4.
- Accepts the Minecraft EULA automatically.
- Creates the Minecraft server directory.
- Generates the server startup and maintenance scripts.
- Schedules hourly backups.
- Installs Crafty Controller and its Python dependencies.
- Installs the Playit.gg agent.
- Starts the Minecraft server and Crafty Controller.
The first provisioning takes several minutes because it downloads the required software.
What gets installed?
~/minecraft-server/
├── server.jar
├── eula.txt
└── server.properties
~/minecraft-server-backups/
~/start.sh
~/keep-alive.sh
~/backup.sh
/var/opt/minecraft/crafty/
└── crafty-4/
├── .venv/
└── app/
└── config/
Playit.gg is installed automatically, but its agent must be linked to your account.
Run:
playitOpen the authentication URL displayed in the terminal, sign in and claim the agent.
Then create a Minecraft Java tunnel in your Playit.gg dashboard.
Use the local server endpoint:
127.0.0.1:25565
Keep the agent running. To launch it in the background, stop the foreground process with Ctrl+C and run:
playit &Do not launch multiple agents simultaneously.
Open your Playit.gg dashboard, find the public address assigned to your tunnel and share it with your friends.
In Minecraft Java Edition:
Multiplayer
|
+-- Add Server
|
+-- Enter your Playit address
Ready to play
Crafty Controller is installed in the Codespace and exposed through port 8443.
- Open the Ports tab in your Codespace.
- Locate port
8443. - Open the forwarded HTTPS address.
- Sign in using the credentials configured for Crafty.
The initial HTTPS certificate may be self-signed, which can cause a browser security warning.
Crafty Controller documentation
The current Codespaces configuration exposes port 8443 with public visibility.
For a private administration panel, change the port visibility in .devcontainer/devcontainer.json to private.
Important: config/default.json contains a fixed initial administrator password in the repository. It must be replaced with a unique secret. Since the repository is public, treat the existing value as compromised. Change the credentials in Crafty after the first login as well.
The provisioning script creates:
~/start.shThis generated script launches PaperMC with a 2 GB Java heap and G1 garbage collector optimisations.
After restarting a Codespace, start the server with:
~/start.sh &The initial provisioning already starts the server. Do not run this command again while it is running.
Crafty also needs to be restarted after a stopped Codespace:
sudo -u crafty bash -c \
'source /var/opt/minecraft/crafty/crafty-4/.venv/bin/activate && cd /var/opt/minecraft/crafty/crafty-4 && python3 main.py' &playit &The agent must already be claimed and configured in your Playit.gg account.
The template includes:
~/keep-alive.shIt writes a timestamp to keep-alive.log every ten minutes.
This is a lightweight logging process. It does not disable Codespaces inactivity shutdown or guarantee permanent hosting.
The backup script is:
scripts/backup.shIt creates compressed archives containing the available world directories:
world/
world_nether/
world_the_end/
The backup directory is:
~/minecraft-server-backups/
Example archive:
world-20261107-140000.tar.gz
Cron schedules the backup every hour:
0 * * * * /home/codespace/backup.shThe current implementation does not automatically delete old archives. Backups remain inside the Codespace and are not an external storage solution.
Export important world archives before deleting the Codespace.
The template is currently configured around these values:
| Setting | Value |
|---|---|
| Minecraft version | 1.21.4 |
| Server software | PaperMC |
| Java runtime | 21 |
| Initial Java heap | 2 GB |
| Local Minecraft port | 25565 |
| Crafty Controller port | 8443 |
| Backup interval | 1 hour |
| Maximum players in helper configuration | 20 |
PaperMC is downloaded from the Paper API using the latest available build for the pinned Minecraft version.
The repository includes:
scripts/setup-config.shIt interactively generates server.properties and lets the user select:
- Server name / MOTD
- Peaceful, Easy, Normal or Hard difficulty
It currently writes online-mode=false.
Do not use that setting on a public server unless you deliberately intend to run offline mode. Offline mode does not provide normal Minecraft account authentication and allows username impersonation.
There is an implementation distinction: the setup script generates its own ~/start.sh, which does not call scripts/setup-config.sh. The configuration helper is only invoked by the repository's scripts/start.sh when server.properties is missing.
The provisioning script creates:
~/minecraft-server/eula.txt
with:
eula=trueReview the Minecraft EULA before running the server.
This template is intended for temporary cloud hosting and experimentation. It is not a permanent 24/7 hosting service.
GitHub Codespaces has usage quotas and automatic shutdown behaviour.
| Resource | GitHub Free personal account |
|---|---|
| Included compute | 120 core-hours / month |
| Included storage | 15 GB-month |
A two-core machine consumes two core-hours per hour. That means 120 included core-hours provide approximately 60 hours on a two-core machine.
Codespaces normally stops after 30 minutes of inactivity by default. Users can change the timeout setting, but an individual Codespace has a maximum lifetime of 12 hours.
Sources: GitHub Codespaces billing · Codespaces timeout settings
Stopping a Codespace preserves its files, but running processes stop.
Deleting the Codespace removes its local data. This includes:
- Minecraft world files
- Local backup archives
- Server logs
- Local Crafty data
Keep external copies of anything important.
mc-server-template/
│
├── .devcontainer/
│ ├── devcontainer.json
│ └── setup.sh
│
├── Docs/
│ ├── BR.TEMPLATE_GUIDE.md
│ ├── DE.TEMPLATE_GUIDE.md
│ ├── EN.TEMPLATE_GUIDE.md
│ ├── ES.TEMPLATE_GUIDE.md
│ ├── IT.TEMPLATE_GUIDE.md
│ ├── JA.TEMPLATE_GUIDE.md
│ └── RU.TEMPLATE_GUIDE.md
│
├── config/
│ └── default.json
│
├── scripts/
│ ├── backup.sh
│ ├── keep-alive.sh
│ ├── setup-config.sh
│ └── start.sh
│
├── Others README ᓚᘏᗢ.../
│ ├── BR.README.md
│ ├── DE.README.md
│ ├── ES.README.md
│ ├── IT.README.md
│ ├── JA.README.md
│ └── RU.README.md
│
├── LICENSE
└── README.md
Installation guides are available in several languages.
Contributions, suggestions and bug reports are welcome.
- Fork the repository.
- Create a branch.
- Make your changes.
- Push the branch.
- Open a Pull Request.
Example:
git checkout -b feature/my-feature
git add .
git commit -m "Improve server template"
git push origin feature/my-featureThis project is distributed under the MIT License.
See LICENSE for details.
PaperMC, Crafty Controller, Playit.gg and GitHub Codespaces remain subject to their respective licenses and terms of service.
