Portal

The web UI at portal.platform.grnds.io — projects, apps, members, Minecraft access, pushes, previews, platform access, and platform base images.

The portal is the visual side of the platform. Sign in with your Grounds Account at portal.platform.grnds.io; membership in any project lands you on a project switcher.

The CLI and the portal share the same forge backend — every operation in one is visible in the other.

What’s where

Project switcher

Top-left dropdown. Switch active project; affects every page below it. The selected project is remembered in your browser’s local storage.

If you open a direct link to an app or other resource that belongs to another project you can access, the portal switches to that project and shows the resource instead of leaving you on a 404.

Apps

The apps overview shows current deployments grouped by manifest name. Each app row shows type, status, latest activity, and whether the workspace is paused.

Open an app to drill into per-app surfaces:

• Overview — status, runtime metrics, active deployment, and quick actions.
• Logs — live pod logs, SSE-tailed.
• Pushes — every push that targeted this app, newest first.
• Previews — preview environments scoped to this app.
• Env — per-app environment variables. User-defined values cannot shadow platform-managed GROUNDS_* keys.
• Settings — runtime resource overrides, Minecraft access for Minecraft app types, and the app delete flow.

Pushes

The history list for the current project: status badge, name, type, target, short push hash, and creation time. Click a row to open the push detail page with the full build + deploy log stream (SSE-tailed if still running, replayed if completed).

Empty state explains how to make your first push if you haven’t yet.

From a push detail page you can retry a failed push, promote ready staging pushes, and roll back an app to a previously deployed push when the action is available.

Previews

Active preview environments for the current project. Per-row dropdown menu has:

• Pin (skip auto-cleanup) — sets pinned=true, env survives past TTL.
• Unpin (re-enable cleanup) — sets pinned=false, TTL recomputed from now.

Status badges reflect the underlying push: ready, received, building, deploy_failed, etc. The hostname is a clickable external link when status is ready for web services. Minecraft previews show the server address to paste into Minecraft.

Base images

Users with BASE_IMAGES_MANAGE can manage the runtime catalog under Platform → Base images.

• Overview — source cards for each runtime family, including the source key, workload type, registry repository, sync status, and version count.
• Source detail — paginated version list for one source.
• Sources — add, edit, delete, and manually sync source definitions.
• Version actions — add a version, promote it to stable, deprecate it, undeprecate it, or delete it when no channel uses it.

Developers reference source keys in grounds.yaml, for example baseImage: paper. Forge resolves the source to the stable catalog version during push. See Base images.

Control Center

Users with CONTROL_CENTER_VIEW can open the Platform Control Center from the header. The first module is Access, which manages platform users, access roles, permissions, identity mappings, direct grants, and access audit events.

See Control Center access for the access-management workflow and Control Center step-up for protected mutation authentication.

App details and actions

Use the app detail pages when something is currently broken — the latest push might have succeeded but the pod is now crashlooping, or the new release introduced a bug you want to roll back.

Available app actions include:

• Retry — re-run a failed push using the server-stored JAR and manifest.
• Roll back — redeploy an earlier push image without rebuilding.
• Promote — copy a ready staging artifact into a new dev push.
• Push command — copy the Gradle command to upload a new push from your terminal.
• Runtime overrides — override CPU and memory without editing grounds.yaml.
• Delete app — tear down the app Service and Deployment. The image remains in the registry.

Members

Project members with roles. Owners can:

• Add member by handle (works only for already-signed-up users).
• Invite link — generate a single-use URL, pick role + expiry.
• Per-row: change role (owner/editor/viewer), remove member.
• Self-removal (Leave project) is allowed for any member; forge enforces last-owner protection.

The Members page also manages project-wide Minecraft access:

• Linked members — project members with a linked Minecraft Java account inherit access to Minecraft apps in the project.
• Project-wide players — Minecraft usernames added directly to the project whitelist. These players can join Minecraft apps without being project members.
• Owners and editors can add or remove project-wide players. Linked member entries are read-only in the whitelist list; update the member or their linked identity instead.

Minecraft access

Minecraft apps combine three access sources:

Source	Where it is managed	Applies to
Linked member	Members page	Every Minecraft app in the project
Project-wide	Members page → Minecraft whitelist	Every Minecraft app in the project
App-specific	App settings → Minecraft whitelist	One Minecraft app

On an app settings page, the Minecraft access card shows the effective list for that app. Inherited linked member and project-wide entries are shown as read-only. App-specific entries can be added or removed there by owners and editors.

When you add a player, enter the Minecraft Java username. Forge resolves it to a Mojang UUID when the entry is created, so later username changes do not break access.

API tokens

Project owners can create, filter, and revoke project-scoped API tokens from the API tokens page. See CI tokens.

Audit

The Audit page shows recent project activity, including member, token, project, deployment, push, Minecraft whitelist, and base image catalog events.

Account settings

The account settings page shows your Grounds Account identity, linked Minecraft Java username and UUID, theme selector, kubeconfig shortcut, and sign-out button.

Account

Top-right avatar:

• Linked identity (your Grounds Account email + handle).
• Theme toggle: System / Light / Dark.
• Sign out.

Theme

The portal supports system, light, and dark themes via the data-mode attribute on <html>. Your choice is persisted per browser. The CLI is unaffected (it uses your terminal’s theme).

What it can’t do (yet)

The portal is feature-complete for observation, member/token management, Minecraft access management, platform access management, and base image catalog management. Things still CLI-only:

• Uploading a new push artifact. The portal can show the push command, but the upload still runs from the CLI or Gradle plugin.
• Bulk operations on pushes or previews.

Day-to-day operations after the initial push — rolling back, promoting a staging push to dev, editing env vars, adjusting resources, managing the whitelist — all live in the portal.