A build can succeed while its preview URL points to yesterday’s artifact. The browser sees a page, the API says “ready,” and nobody can prove which commit is being reviewed. Fix that handoff with a preview resource whose identity includes the build and whose expiry is explicit.
This is a proposed vertical-slice contract, not a description of MonkeyCode internals.
{
"preview_id": "prv_01",
"workspace_id": "ws_01",
"build_id": "bld_01",
"commit_sha": "40-hex-replace-me",
"state": "PROVISIONING",
"url": null,
"created_at": "2026-07-27T10:00:00Z",
"expires_at": "2026-07-27T11:00:00Z",
"version": 1
}
Allowed transitions are deliberately small:
REQUESTED -> BUILDING -> PROVISIONING -> READY -> EXPIRED -> DELETED
| | |
+----------> FAILED <-----+
READY -> SUPERSEDED -> DELETED
POST /previews accepts workspace ID, immutable build ID, expected commit SHA, and an idempotency key. GET /previews/{id} returns the resource above. DELETE is idempotent and moves toward DELETED; it never resurrects a preview. Authorization checks workspace membership on every operation, not only creation.
The UI may render a link only when state is READY, URL is present, current time precedes expiry, and the displayed commit equals the review target. Poll with the resource version or use events carrying monotonically increasing sequence numbers. A late READY event cannot overwrite SUPERSEDED, EXPIRED, or DELETED.
| Cross-layer case | Expected response | UI behavior |
|---|---|---|
| build fails | preview becomes FAILED | show build evidence, no link |
| provision times out | bounded retry on same ID | keep non-ready state |
| newer build created | old preview SUPERSEDED | disable old review action |
| URL returns wrong marker | integrity check fails | block approval |
| expiry during viewing | 410 / expired state | remove action, offer rebuild |
| delete repeated | same terminal result | confirm cleanup once |
A minimal integrity route can serve preview_id, build_id, and commit_sha from the deployed artifact. The client compares all three with the API resource before enabling review. Do not use a mutable branch name as identity.
For the happy path, create from an immutable successful build, wait for readiness, fetch the marker, verify identity, inspect, then delete. For failure, capture operation ID and terminal evidence, revoke the URL, mark the resource failed or expired, and prevent stale retries from publishing it. Cleanup jobs should query nonterminal previews past deadline and drive them to deletion.
Limitations: a matching marker does not prove the whole artifact is correct, URLs may leak through logs, caches can outlive origin deletion, and clocks can disagree. Production design still needs access control, rate limits, audit retention, cache invalidation, and provider-specific teardown verification. The schema and endpoints here are unexecuted examples.
Run the slice in a temporary environment
Official current MonkeyCode material presents the overseas hosted option as “Free to start.” It describes integrated models and managed server-side cloud development environments supporting build, test, and preview—the right surface for examining this contract. It does not promise that every model or server is free. Confirm changing availability, quotas, regions, duration, pricing, and terms in the current console.
The lifecycle fixture can begin from the official campaign entry: https://ly.cyberserval.tech/iIETXiF
Finish by expiring/revoking the preview, deleting its workspace, checking terminal API and console state, and retaining only sanitized contract evidence. A URL that still resolves or a version that cannot be reconciled sends the path to failure cleanup.
Disclosure: This article promotes MonkeyCode using an official campaign link. I’m a MonkeyCode user, not affiliated with the project, and I receive no commission from this link.
AI assistance disclosure: This article was drafted with AI assistance and reviewed against the cited project materials.
Top comments (0)