Internal developer quickstart

Set up an internal Grounds workspace, push a plugin, and test local plugin overrides.

This guide starts from a fresh internal development workspace. By the end, you’ll have the CLI authenticated, Gradle ready to resolve grounds-push, and a Velocity stack pushed with local plugin-agones and plugin-player builds.

Examples use ~/grounds as the parent directory. Use any directory you prefer, but keep the app repo and plugin repos under one parent so workspace scans are predictable.

Prerequisites

• A Grounds Account.
• Java 21+.
• A Gradle wrapper in each plugin repository.
• Git access to the internal repositories you work on.
• A GitHub token with read:packages for resolving gg.grounds.push from GitHub Packages.

1. Create your workspace directory

Keep the app repo and plugin repos under one parent directory:

mkdir -p ~/grounds
cd ~/grounds
git clone [e-mail]:groundsgg/plugin-agones.git
git clone [e-mail]:groundsgg/plugin-player.git
mkdir -p sample-plugin-workspace/app

This creates the app workspace used by later commands at ~/grounds/sample-plugin-workspace/app. If you already have an app repo, clone or move it under the same parent and use that path instead.

2. Install and sign in with the CLI

Install the CLI for your operating system:

macOS / Linux (Homebrew)

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

Linux (curl)

curl -fsSL https://raw.githubusercontent.com/groundsgg/grounds-cli/main/install.sh | sh

Windows (Scoop)

scoop bucket add grounds https://github.com/groundsgg/scoop-bucket
scoop install grounds

Sign in with your Grounds Account:

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 stores credentials in its config directory and you only need to repeat this when the session expires.

Verify with:

grounds doctor

You should see green checks on auth, api, and gradle wrapper when run from a project root.

3. Configure GitHub Packages for Gradle

Internal Gradle builds resolve gg.grounds.push from GitHub Packages. Export credentials before running Gradle or grounds push:

export GITHUB_ACTOR=<github-user>
export GITHUB_TOKEN=<token-with-read-packages>

Your plugin repos can also read these values from your shell, Gradle properties, or your CI environment. Do not commit tokens to a repository.

4. Check the app manifest

The app manifest should keep shared release sources. Local workspace mappings replace those sources only for your push.

Use this canonical sample manifest in ~/grounds/sample-plugin-workspace/app/grounds.yaml:

grounds.yaml

name: sample-velocity-plugins
type: plugin-velocity
baseImage: velocity
plugins:
  - id: plugin-agones
    variant: velocity
    source: github:groundsgg/plugin-agones@v0.5.0
  - id: plugin-player
    variant: velocity
    source: github:groundsgg/plugin-player@v0.1.0

See the manifest reference for exact field rules and supported workload shapes.

5. Understand the release-source push

Plain grounds push uses the release sources from grounds.yaml:

cd ~/grounds/sample-plugin-workspace/app
grounds push --target=dev

Use this path when the referenced GitHub releases publish .jar assets. If a release has no JAR asset yet, the push fails during source resolution; continue with local workspace mappings for active development.

When release sources are available, the push flow is:

1. The Gradle plugin assembles the configured artifacts and uploads them with 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 the workload to your personal namespace (user-<your-handle>).
4. Once the pod is Ready, the CLI prints the public URL.

Connect from any Minecraft client using that address. The first connection cold-starts the server; after that it stays warm until idle.

6. Add local workspace mappings

Map each manifest plugin ID to the local repository, build command, and artifact that should replace the release source during local override pushes:

grounds workspace add plugin-agones ~/grounds/plugin-agones \
  --variant velocity \
  --artifact velocity/build/libs/plugin-agones-velocity.jar \
  --build './gradlew :velocity:shadowJar'

grounds workspace add plugin-player ~/grounds/plugin-player \
  --variant velocity \
  --artifact velocity/build/libs/plugin-player-velocity.jar \
  --build './gradlew :velocity:shadowJar'

grounds workspace list
grounds workspace doctor

grounds workspace doctor checks that configured repository paths exist.

7. Push with local plugin overrides

Run a dev push with every enabled workspace mapping applied:

grounds push --target=dev --with-local

The shared grounds.yaml still points at release sources. --with-local rewrites enabled workspace entries for this push only.

8. Inspect the result

Use the CLI output, Portal, and server logs to confirm the pushed stack is using your local builds. For a shareable preview of the same local override set without replacing your dev deployment, push to staging with --with-local:

grounds push --target=staging --with-local

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. See Share staging previews for the full preview workflow, including pinning previews:

grounds preview list
grounds preview pin <id>

Next steps

Local plugin workspaces

Map independent plugin repos into grounds push --local and --with-local.

Multi-plugin stacks

Test Paper, Velocity, or gamemode stacks with multiple plugins in one push.

Debug pushes

Work through local build, upload, Forge build, and deployment failures.

Manifest reference

Check fields, source formats, and workload shapes.