---
title: "Lifecycle and reliability"
description: "Control idle workspaces, retain immutable source, and recover uncertain API requests."
canonical_url: "https://hoplite.sh/docs/platform/operations"
markdown_url: "https://hoplite.sh/docs/platform/operations.md"
---

# Lifecycle and reliability
URL: /docs/platform/operations
LLM index: /llms.txt
Description: Control idle workspaces, retain immutable source, and recover uncertain API requests.

# Lifecycle and reliability

Source versions outlive sandboxes. A completed run has a durable source result; terminating an idle runtime does not discard that version. Reopening restores files into a new runtime. Installed dependencies, running processes, and local Git history are not part of the source bundle.

## Set an editor’s idle deadline

Call `POST /api/platform/v1/projects/{projectId}/threads/{threadId}/workspace/activity` with `{"idleTimeoutMinutes":20}` when a user starts or continues editing. The timeout accepts 1–60 minutes. Repeat with a new idempotency key for new activity; replaying an old key does not renew the deadline.

Read `/workspace/policy` for the saved policy, expiry and `workspaceStatus`. Wait for `archived` to verify that the idle policy took effect. A null policy means the organization’s default idle policy applies. Completing an edit starts a fresh idle interval. Background preview polling does not extend it.

The worker checks the persisted deadline and archives after active work drains. It saves source before terminating the runtime. Storage or provider failures can delay termination; they must not cause unsaved work to be discarded. Send activity from your authenticated backend, based on actual user interaction rather than an unattended timer.

## Source limits and retention

A bundle can contain up to 10,000 files, 8 MiB per decoded file, and 32 MiB of decoded contents in total. The JSON request limit is 64 MiB. Files may use UTF-8 or canonical padded base64. Executable files retain mode `0755`; others restore as `0644`.

Paths must be relative, unique ignoring case, and free of traversal. `.git`, `.context`, and `.hoplite` are reserved. Symlinks and non-regular files cannot be saved. Keep large media assets in your own object storage and include their approved references in the source.

Saved sources, builds, and registered upload objects are retained while the project exists. Deleting a thread does not delete its source history. Deleting the project removes its source/build metadata and durably queues deletion of the corresponding object-storage keys, including interrupted registered uploads. Cleanup starts after a one-hour grace period for in-flight transfers and retries failed deletions. This is asynchronous cleanup, not immediate erasure.

## Retry without duplicating work

Every service-credential write needs an `Idempotency-Key`. Use a new key for a new operation and preserve it across network retries. Changing the payload under the same key returns a conflict. For an uncertain receipt, inspect `GET /api/operations/{operationId}` before starting another operation.

Missing source storage returns `source_storage_unavailable`; missing execution configuration returns `source_workspace_unavailable`. New work fails admission when a required dependency is unavailable. A failed editing run leaves the last successful result unchanged. If a runtime disappears unexpectedly, recovery uses the last saved source; unsaved changes can be lost.

Build commands are not automatically rerun after an uncertain worker failure, because the first command may still be executing. Admission stays locked until that execution can no longer be live, then the build fails and can be resubmitted.

## Progress, cancellation, and cost

Use the existing Direct API message and event endpoints for live progress. Persist your event cursor and use replay after reconnecting. The [event stream reference](/docs/api/streamPublicEvents) and [webhook reference](/docs/api/createWebhook) describe their delivery contracts; build/apply status endpoints remain the authority for those operations.

Stop an agent run through the [Direct API stop operation](/docs/api/stopRun). Repair runs use the same control and incur ordinary agent charges. Read [thread usage](/docs/api/getThreadUsage) and enforce the thread’s lifetime spend limit for editing and repairs. A browser disconnect is not a cancellation request.

Keep your organization membership checks in your backend. Scope Hoplite credentials to the required projects and permissions, and handle 403/404 responses without exposing whether another tenant’s source exists.

## Sitemap

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