Skip to main content
Templates are reusable supply-chain resources. A sandbox ultimately runs an immutable OCI digest whose architecture, runtime contract, supervisor protocol, scan evidence, policy status, and storage capabilities are compatible with StackShift’s configured deployment server.

​
Select an exact template version

In Sandboxes → Templates & images, inspect:
  • active and previous immutable versions;
  • image reference and sha256 digest;
  • source revision and build provenance when visible to your role;
  • architecture and required supervisor protocol;
  • vulnerability/malware scan result and policy decision;
  • CycloneDX SBOM and its ETag;
  • deprecation, blocked, or activation status;
  • warm-pool eligibility and observed readiness.
Use the exact digest in automation. A mutable tag can identify a build input, but it is resolved and recorded as an immutable digest before execution. “Trusted” is never a cosmetic label: provenance, scans, runtime compatibility, and current policy must all qualify. Template API resources are:
  • GET /api/v1/template-versions and GET /api/v1/template-versions/{versionId};
  • GET /api/v1/template-versions/{versionId}/sbom;
  • POST /api/v1/template-versions/{versionId}/activate;
  • GET|POST /api/v1/template-builds and GET /api/v1/template-builds/{buildId}.
Build creation is idempotent and accepts an immutable source revision. Poll build detail with after_sequence to receive ordered stage/log updates. Activation changes which immutable version is current; it does not mutate history.

​
Use admission preflight

The creation wizard calls POST /api/v1/sandboxes/admission-preflight before create. Submit the intended normalized specification and review the returned effective request, policy changes, quota impact, and capability decisions. Preflight answers four different questions:
  1. Is the caller authorized for this profile, image, resource size, network mode, secrets, and volumes?
  2. Does the account have quota for total/running sandboxes, CPU, memory, disk, snapshots, executions, egress, TTL, and profile access?
  3. Does the configured server report compatible Kata, supervisor, storage, snapshot, networking, image, and architecture capabilities?
  4. Can current reservable capacity satisfy the request without unsafe overcommit?
Preflight is advisory at a point in time. Create performs admission transactionally again because capacity or quota may change between requests.

​
Understand single-server capacity

StackShift currently admits sandboxes to one configured deployment server. There is no public region, zone, node, or deployment-target selector and no cross-region migration/failover claim. The platform evaluates server heartbeat, drain/maintenance state, allocatable and reserved CPU/memory/PIDs/disk, storage backend, cached image/snapshot digests, and required policy features. A transactional reservation prevents concurrent creates from overcommitting the same capacity. Reservations release on sleep, destroy, failed provisioning, or expired provisioning lease. capacity_unavailable and deployment_server_unavailable are operational conditions, not quota failures. Retry only when the error says it is retryable and use backoff with the same idempotency key.

​
Read quota failures

A quota_exceeded error includes:
Use those exact values to reduce the request, sleep/destroy unused sandboxes, remove retained data, or request a policy/plan change. Do not substitute a generic “upgrade” message for a capacity, permission, policy, or runtime-health failure.

​
Warm starts

Warm-pool entries are prebooted from qualified immutable template versions and sanitized before assignment. Allocation still creates a new tenant-owned sandbox resource, applies its current policy/secrets/volumes, and records the same durable operation and audit trail. Warm availability is an optimization, not a lifecycle guarantee; clients must tolerate cold provisioning.

​
Dashboard state

The Fleet summary shows timestamped counts, requested resources, storage, quota pressure, and server availability only when backed by aggregate endpoints. Filters and cursor pagination are server-owned. Capability messages explain whether an action is forbidden, plan-limited, quota-limited, capacity-limited, unsupported, unhealthy, or invalid for current state.

Sandbox overview

Create and operate a sandbox.

Troubleshooting

Handle admission and capability errors.