Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.grounds.gg/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks through your first push. By the end you’ll have a Paper plugin running on managed infrastructure, reachable at a public *.mc.grnds.io address.

​
Prerequisites

  • A Grounds Account (talk to your org admin if you don’t have one yet)
  • Java 21+ and Gradle (a Gradle wrapper in your project is fine)
  • macOS, Linux, or Windows (WSL2 works)

​
Install the CLI

brew install --cask groundsgg/tap/grounds
grounds version

​
Sign in

grounds login
The CLI opens your browser to Grounds Account. Sign in with your Grounds Account and approve the device code shown in the terminal — the CLI persists tokens in your OS keyring and you only need to repeat this when the session expires (usually weekly). Verify with: 
grounds doctor
You should see green checks on auth, api, and gradle wrapper (if run from a project root).

​
Set up the Gradle plugin

Grounds builds straight from Gradle. Add the plugin to your build.gradle.kts: 
plugins {
    `java-library`
    id("gg.grounds.push") version "0.x" // see Releases for current
}

groundsPush {
    // Reads ~/.config/grounds/credentials.json by default; no extra config needed.
}

dependencies {
    compileOnly("io.papermc.paper:paper-api:1.21.4-R0.1-SNAPSHOT")
}
Then create a grounds.yaml next to build.gradle.kts: 
name: my-plugin
type: plugin-paper
baseImage: paper
jar: build/libs/my-plugin-0.1.0.jar
The baseImage field selects the runtime: paper, velocity, minestom, or service. Each maps to a vetted image we keep up to date.

​
Your first push

grounds push --target=dev
What happens:
  1. The Gradle plugin assembles your JAR and uploads it + the manifest to the Grounds API.
  2. Forge runs a Kaniko build inside the cluster, pushes the resulting OCI image to the internal registry, and signs it with cosign.
  3. Forge applies a Deployment + Service to your personal namespace (user-<your-handle>).
  4. Once the pod is Ready, the CLI prints the public URL.
Output looks like: 
✔ Build complete (image sha256:abc…)
✔ Deploy ready
  → minecraft://my-plugin-yourname.mc.grnds.io
Connect from any Minecraft client using that address. The first connection cold-starts the server (~15s); after that it stays warm until idle.

​
Ephemeral preview env

For sharing a build with playtesters without polluting your dev environment: 
grounds push --target=staging
This creates a fresh preview-<id> namespace with a 7-day TTL. Hostname pattern: <name>-pr<id>.mc.grnds.io. Grounds garbage-collects the env automatically once the TTL expires — pin it to keep it longer: 
grounds preview list           # find the id
grounds preview pin <id>       # opt out of auto-cleanup

​
Next steps

CLI reference

Every subcommand and flag.

Concepts

Projects, dev clusters, preview envs — what they are and how they relate.

Troubleshooting

Common errors and how to fix them.

API reference

Forge HTTP API for custom integrations.