> ## 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.

# Templates, admission, capacity, and quotas

> Choose an immutable qualified image, preflight a sandbox request, and understand single-server capacity and tenant limits.

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:

```json theme={null}
{
  "name": "reserved_memory",
  "current": 12288,
  "requested": 4096,
  "limit": 14336,
  "unit": "MiB"
}
```

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.

<CardGroup cols={2}>
  <Card title="Sandbox overview" href="/ai-sandboxes/overview">Create and operate a sandbox.</Card>
  <Card title="Troubleshooting" href="/ai-sandboxes/troubleshooting">Handle admission and capability errors.</Card>
</CardGroup>