Publishing

Third-party mods are published through VibeLands-hosted infrastructure. Local server installation is no longer the public distribution path.

1. Validate Locally

vibelands check .
vibelands check . --review

check catches manifest errors, missing entries, compile errors, forbidden host imports, bundled singleton copies, and budget violations before upload. check --review additionally validates review-metadata.json so marketplace description, support/privacy notes, and permission rationale are ready before submission.

2. Upload Source

vibelands serve .

The CLI uploads a source archive to the hosted sandbox build API on https://playvibelands.com:

POST /api/mods/sandbox/uploads

The sandbox builder compiles, scans, signs, and deploys the mod into your Developer Sandbox. The CLI prints the build/status URL and hosted game URL returned by the service. Use --clone-world <worldId> to test against a copy of one of your worlds.

Use --json when wiring the sandbox loop into CI or a developer portal:

vibelands serve . --json

The structured result includes the build links and sandbox runtime diagnostics, including sandbox.error when the build published but the test runtime could not be prepared.

This creates a sandbox build. It is not yet a public marketplace release.

3. Submit For Review

Public marketplace publishing is a review flow:

vibelands publish <buildId> --metadata review-metadata.json

The publish command targets a sandbox build or uploads a fresh source archive, then creates a review submission. A version already published to Marketplace is immutable and updates require a newer semver. When a reviewer requests changes, the corrected Sandbox build can be resubmitted at the same not-yet-published version.

Browser developers can use Submit Review in /sandbox instead. The dialog loads prior submissions and Marketplace history, then presents the correct first-release, version-update, or reviewer-follow-up flow.

Use a metadata file so reviewers receive the public listing context and permission rationale with the build:

{
  "description": "Adds checkpoint coin races for small community worlds.",
  "tags": ["activity", "racing"],
  "media": ["https://example.com/screenshot.png"],
  "license": "MIT",
  "supportUrl": "https://example.com/support",
  "privacyNotes": "Stores per-world high scores only. Does not export player data.",
  "permissionRationale": {
    "storage": "Persists high scores and active event state.",
    "players.modify": "Grants XP and money rewards when a run is completed."
  },
  "testNotes": "Start the Coin Sprint activity near the town square and complete one lap.",
  "changelog": "Initial marketplace submission."
}

vibelands create generates review-metadata.json; fill it in before your first review submission.

description, tags, and license fall back to the mod manifest when available. The hosted review API rejects missing description, tags, license, valid support URL, privacy notes, changelog, or rationale for a requested permission, so custom clients cannot bypass the publishing form. Missing media and reviewer test notes remain visible as reviewMetadataWarnings.

vibelands publish ... --json returns a machine-readable review submission summary with submissionId, buildId, modId, version, status, submissionUrl, and reviewMetadataWarnings.

Reviewers process submissions through /ops-console or the admin ops API:

• GET /api/admin/ops/mods/review-submissions?status=submitted
• PATCH /api/admin/ops/mods/review-submissions/:id with action: "publish" to create the public marketplace listing/version.

Review requires:

• automated build, scan, signing, and sandbox smoke checks;
• changelog, description, tags, license, support URL, privacy notes, and permission rationale (media and focused reviewer test notes are recommended);
• manual approval before the version becomes public and installable.

Track your submission from the CLI:

vibelands reviews
vibelands review <submissionId>

4. Marketplace Install

Approved versions are installed into worlds by version pin through the hosted control plane. World owners choose when to install or update a mod; runtime startup resolves the pinned version to a signed release artifact.

After approval, verify public discovery from the CLI:

vibelands marketplace <mod-name-or-tag>
vibelands marketplace:show <slug>

World owners can install the approved version from the CLI or the in-game Mod Store:

vibelands marketplace:install <slug> --world-id <worldId>
vibelands marketplace:install <slug> --world-id <worldId> --version <old-version> --allow-downgrade  # rollback
vibelands marketplace:uninstall <slug> --world-id <worldId>
vibelands marketplace:world --world-id <worldId>

For an operator smoke after a review submission exists:

node scripts/mod-marketplace-e2e-smoke.mjs \
  --remote https://playvibelands.com \
  --cookie "vibelands_session=..." \
  --world-id <worldId> \
  --submission-id <reviewSubmissionId>

Use --skip-publish --mod-id <modId> to only verify marketplace install for an already-published listing.

5. Runtime Trust Model

• Third-party browser JavaScript is allowed only as reviewed React/R3F mod bundles produced by the hosted build pipeline.
• Client-facing mod behavior must go through entries.client, shared-module shims, integrity checks, mod SDK APIs, and marketplace review.
• Server logic runs in isolated worker containers.
• Mod workers do not receive database credentials and cannot mutate world state directly.
• The world runtime validates worker-requested effects through permissions, quotas, and circuit breakers.

See the in-repo architecture note: docs/SECURE_MOD_AND_HOSTING_ARCHITECTURE.md.

Local development and version management

Run the app with pnpm dev, then connect the CLI to the frontend origin:

vibelands login --remote http://localhost:5175
vibelands doctor
vibelands builds --mod my-mod

Login saves the selected remote. Use a separate VIBELANDS_CONFIG_PATH for local development if you also use a production login. Vite proxies the API and preserves the frontend origin so login, status and preview links open correctly. An independently deployed API/UI pair must set VIBELANDS_PUBLIC_URL, PUBLIC_SANDBOX_API_URL and PUBLIC_SANDBOX_GAME_URL to their public addresses.

My mods → Projects & versions filters browser and CLI builds and review history by mod. Its Edit links reopen the matching browser project. CLI sources stay in your local repository; builds --json supplies IDs for CI and status <build-id> --logs supplies diagnostics.

Use vibelands version patch (or minor / major) to update the manifest and package version together. Update the changelog, preview, then submit again. Versions in review or already released cannot be overwritten. A reviewer can request changes to allow another build of an unpublished version.

The Marketplace install menu lets you choose a published version. Check Allow rollback from a newer installed version when deliberately reverting. The CLI equivalent is marketplace:install ... --version ... --allow-downgrade. World mod configuration is preserved when no replacement config is supplied.