---
title: "Versions and builds"
description: "Combine isolated editing threads and build immutable source versions for your infrastructure."
canonical_url: "https://hoplite.sh/docs/platform/versions"
markdown_url: "https://hoplite.sh/docs/platform/versions.md"
---

# Versions and builds
URL: /docs/platform/versions
LLM index: /llms.txt
Description: Combine isolated editing threads and build immutable source versions for your infrastructure.

# Versions and builds

Each editing thread starts from an immutable source and owns an isolated workspace. Threads can run concurrently. Your application chooses which results to integrate and which built release to publish.

## Combine concurrent edits

Initialize the project head once with `POST /api/platform/v1/projects/{projectId}/source-head/initialize` and `{"sourceId":"src_..."}`. Start each draft from a source in that head’s history.

Apply a completed draft with `POST /api/platform/v1/projects/{projectId}/threads/{threadId}/apply`. Supply its latest successful `expectedSourceId`, a `clientOperationId`, and a matching `Idempotency-Key`. Poll the returned apply ID through `GET /api/platform/v1/projects/{projectId}/applies/{applyId}`.

Applies are durably serialized per project. Independent edits merge automatically. Conflicts start a billable agent repair by default, using the thread’s model and spend limit. The agent receives base, head, draft, and clean-merge evidence. Repairs stop on cancellation, incompatible intent, three identical invalid candidates, or a 15-minute total budget. Validation and each repair report are available on the apply response.

Set `conflictResolution: "manual"` to receive conflicts without agent repair. To resolve them, submit a new apply with `expectedHeadSourceId` and explicit `resolutions`, such as `[{"path":"index.html","take":"draft"}]`. A changed head rejects the stale decision rather than overwriting newer work.

A failed apply leaves the project head unchanged. An applied draft is sealed; continue in a new thread from the new head. Structural merge checks and agent-reported checks do not replace your application’s build and browser tests.

## Build a pinned source

Call `POST /api/platform/v1/projects/{projectId}/threads/{threadId}/builds`:

```json
{
  "sourceId": "src_...",
  "command": "pnpm install --frozen-lockfile && pnpm build",
  "outputDirectory": "dist",
  "timeoutSeconds": 300
}
```

The build runs in a separate scratch sandbox containing exactly the requested source. Include dependency installation if required; packages from the editing directory are not copied. The thread must be idle. A queued or running build blocks edits and applies on that thread. Hoplite deletes the build sandbox before publishing a terminal result, including on failure; a failed cleanup keeps the build fenced for recovery.

Project and organization deletion returns `409 build_busy` while a build sandbox still needs cleanup. Retry deletion after cleanup completes; this preserves the durable record needed to remove the sandbox.

Poll `GET /api/platform/v1/projects/{projectId}/builds/{buildId}`. When ready, download `/artifact` for the gzip tar archive, `/manifest` for file hashes and sizes, and `/logs` for the saved output. Downloads use the same authentication as status reads. Validate the manifest before extracting an artifact into your deployment storage.

Builds allow up to 10,000 regular output files and 64 MiB of output, with a 600-second maximum command timeout. Unsafe paths, symlinks, hard links, and special files are rejected. A ready build has persisted, validated output; it does not imply browser QA has passed.

## Publish on your infrastructure

Store the artifact in your release storage, run your QA gates, and publish only after your product’s explicit approval action. A published-release pointer can move atomically to a ready artifact; rollback selects an earlier artifact. Hoplite does not provision a deployment or domain for each generated app.

## Sitemap

See the full [sitemap](/docs/sitemap.md) for all pages.
Well-known sitemap: [/docs/.well-known/sitemap.md](/docs/.well-known/sitemap.md).