> ## Documentation Index > Fetch the complete documentation index at: https://docs.stackshift.cloud/llms.txt > Use this file to discover all available pages before exploring further. # Sandbox security, lifecycle, limits, and persistence > Understand Kata isolation, effective network policy, write-only secrets, enforced quotas, sleep, snapshots, recovery, and deletion. Security and persistence are enforced by the platform, not inferred from a disabled dashboard button. Always inspect the sandbox's effective specification and capability decisions: requested settings can be narrowed or denied by account policy, target health, image compatibility, quota, or available capacity. ## Isolation boundary Each untrusted sandbox runs as a separate Kata VM workload on the configured StackShift deployment server. Admission requires a compatible digest-pinned image, sandbox supervisor protocol, healthy containerd/Kata runtime, applicable nftables policy, qualified encrypted block storage, quota, and reservable capacity. The runtime applies CPU, memory, PID, root disk, workspace disk, ephemeral disk, maximum runtime, idle, and TTL limits. Swap is disabled by default. Reaching a limit is observable: execution states distinguish failure, timeout, cancellation, and OOM kill, while the sandbox and operation preserve machine-readable failure details. Isolation does not make executed code trusted. Continue to apply least privilege, minimal network access, short retention, and explicit review before publishing output. ## Network policy Inbound access defaults to none. A listening process is unreachable until an explicit port resource is opened, and private authenticated access is the default. Egress modes are `deny_all`, `allowlist`, and policy-authorized `unrestricted`. The `untrusted` and `plugin` profiles deny public egress by default. Protected loopback, link-local, private, metadata, and control-plane destinations remain denied unless an explicitly authorized private network applies. DNS answers, alternate address encodings, and redirects are revalidated. Do not assume a hostname allowlist is a one-time DNS check. If a destination becomes protected or violates policy, the connection is denied and the event/audit trail identifies the decision without exposing credentials. ## Create and bind secrets The CLI reads plaintext from stdin, trims one trailing newline, rejects empty values, and caps input below 64 KiB. Prefer a prompt or process substitution that does not persist plaintext: ```bash theme={null} printf '%s' "$UPSTREAM_TOKEN" | stackshift --output json sandbox secrets create \ --name github-api \ --type token \ --description 'Read-only GitHub API token' \ --allowed-hosts api.github.com ``` Bind the returned secret ID with an explicit scope, target, and delivery mode: ```bash theme={null} stackshift sandbox secrets bind \ --scope execution \ --target GITHUB_TOKEN \ --delivery proxy \ --allowed-hosts api.github.com ``` Delivery choices: | Mode | Use | Important constraint | | ------- | ----------------------------------------------------------- | --------------------------------------------------------- | | `proxy` | Inject a credential only for an authorized upstream request | Restrict hosts; preferred for untrusted code | | `file` | Mount secret material at an explicit path | Keep the path outside retained/output directories | | `env` | Expose a value to a scoped execution | Higher leakage risk; never log or persist the environment | Secret plaintext is never returned after creation. APIs expose only safe preview, fingerprint, version, policy, expiry, revocation, and attachment metadata. Secrets are excluded from images, snapshots, artifacts, process metadata, logs, events, and crash reports. Rotation creates a new version. New executions use bindings with `latest`; already running processes must restart. Revocation and unbinding require deliberate review because active workloads can fail immediately: ```bash theme={null} printf '%s' "$ROTATED_TOKEN" | stackshift sandbox secrets rotate stackshift --yes sandbox secrets unbind stackshift --yes sandbox secrets revoke ``` ## Persistence matrix | Data | Sleep/resume | Filesystem snapshot | Group snapshot | Destroy | | ------------------------------------ | ---------------------------------------- | ------------------- | --------------------------------------- | --------------------------------------------------- | | Declared workspace filesystem | Preserved | Included | Included | Deleted unless separately retained | | Attached persistent volume | Preserved independently | Not implied | Included only when declared as a member | Volume follows its own ownership/retention | | Managed service sidecar volume | Preserved while service exists | Not included | Included and quiesced | Deleted with owned service unless snapshot retained | | Process/kernel memory | Lost | Excluded | Excluded | Lost | | Ephemeral filesystem | Not guaranteed | Excluded | Excluded | Deleted | | Secret plaintext and volatile mounts | Re-delivered according to binding policy | Excluded | Excluded | Revoked/removed | | Artifact | Independent retention | Not embedded | Not embedded | Retained by artifact policy | Sleep stops compute and preserves declared filesystem/volume state. It is not a memory-preserving pause. Resume provisions runtime state again and reconciles bindings, processes, ports, and readiness under current policy. ## Snapshots, restore, and fork `filesystem` snapshots cover the sandbox filesystem. `group` snapshots create a coordinated recovery point for the workspace and declared sidecar members. Public creation currently requests `crash_consistent`; group processing records actual quiesce evidence in the manifest. A usable snapshot must be `ready` and contain immutable image identity, storage-backend identity, supervisor protocol, member IDs, logical/stored sizes, manifest and chunk checksums, verified encryption, consistency/quiesce evidence, lineage, and confirmation that volatile secrets were excluded. Restore requires a sleeping compatible target. Integrity and compatibility are checked before replacement. The default safety snapshot creates a rollback point. Fork creates an independent sandbox with lineage; it does not share writable storage or credentials with the source. Volumes are ext4, encrypted, hard-capacity resources. They can grow but never shrink. Detach requires a sleeping sandbox; delete requires a detached volume and `--yes`. ## Durable operations and safe retry Create, lifecycle changes, resize, snapshot, restore, fork, recovery, and destroy are durable operations. Keep the operation ID when a request times out. A timeout is an unknown result, not proof that the mutation failed. Use one stable `Idempotency-Key` for logical retries. Reusing it with different input returns `idempotency_conflict`. Resource updates and destroy also require the latest `If-Match` version; refetch after `version_conflict` and review changes before retrying. ## Destroy and expiry Destroy is the successful terminal lifecycle state. It tombstones the sandbox, revokes terminals, ports, writer leases, and secret delivery, stops compute, and asynchronously removes owned runtime/storage. A failed sandbox is not automatically safe to abandon; use recovery when available or destroy it deliberately. Before destroy, review snapshots, independent volumes, artifacts, running processes, open ports, secret bindings, and required audit evidence. Use lifecycle, snapshot, volume, service, and secret commands. Implement idempotency, version checks, operations, and events.