Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.mistle.dev/llms.txt

Use this file to discover all available pages before exploring further.

Persistent sandboxes are experimental. Use them when preserved workspace state is valuable enough to justify the additional storage lifecycle, cleanup, and isolation considerations.

​
Overview

Persistent sandboxes let selected sandbox filesystem state survive after the sandbox compute runtime stops or expires. By default, session sandboxes are ephemeral. When persistence is enabled for an organization and a sandbox profile opts in, sessions from that profile can run in persistent mode.

​
Why Persistence Matters

Sandbox providers can impose hard limits on how long a compute sandbox may run. When provider compute stops, expires, or is replaced, an ephemeral sandbox has no durable filesystem state to recover. Persistent sandboxes decouple compute from selected filesystem state. Mistle can replace the compute sandbox while keeping selected paths in durable storage and reattaching them later. Use persistent sandboxes for workflows where one session’s working state should survive compute lifecycle changes, such as:
  • checked-out repositories
  • dependency caches
  • generated build artifacts
  • agent workspace state
  • long-running project setup that should not be repeated after every provider restart

​
Persistent Sandboxes Vs Snapshots

Persistent sandboxes and snapshots solve different problems.
FeatureWhat it preservesScopeMain use case
SnapshotsPrepared sandbox imageSandbox profile versionMake future sessions start from a prebuilt profile image
Persistent sandboxesSelected filesystem pathsSandbox instanceKeep one sandbox’s working state across compute stops or provider expiry
Use Snapshots when many future sessions should start from the same prepared environment. Use persistent sandboxes when the state belongs to a specific sandbox instance and should remain available when that sandbox’s compute is stopped or replaced. Snapshots do not preserve ongoing per-session work. Persistent sandboxes do not create a reusable image for other sessions.

​
Enable Persistent Sandboxes

Persistent sandboxes require both organization-level enablement and profile-level opt-in.

​
1. Enable Persistence For The Organization

Organization owners and admins can enable the option from the dashboard:
  1. Open Settings.
  2. Go to Organization > Sandboxes.
  3. Turn on Allow persistent sandboxes.
  4. Save the settings.
Self-hosted deployments also need a supported durable storage backend. Read Self-Hosted Configuration for sandbox storage configuration.

​
2. Enable Persistence On A Sandbox Profile

After organization persistence is enabled, opt in from a draft sandbox profile:
  1. Open the sandbox profile.
  2. Edit the draft version.
  3. Turn on Use persistent sandboxes.
  4. Publish the profile version.
  5. Start sessions from that published profile version.
If a profile enables persistent sandboxes while organization persistence is disabled, sessions from that profile are still created in non-persistent mode.

​
What Is Persisted

Persistent storage is intentionally scoped. It is not a full snapshot of the whole sandbox filesystem. The current persistent storage layout preserves:
Sandbox path
/root
/etc/codex
Secrets should still not be written directly into the sandbox. Use Integrations for managed access to external systems.

​
Experimental Limits

Important considerations:
  • persisted state is scoped to a sandbox instance
  • persisted paths are currently limited to /root and /etc/codex
  • setup and workflows must not assume the sandbox starts empty
  • storage backends add cost and lifecycle management
  • cleanup, partial attachment, provider failures, and state drift are still being hardened

​
Next Steps