> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hiloop.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Resources and capabilities

> Request CPU and memory for a sandbox, and understand how a deployment refuses what it cannot serve.

Sandbox creation can request compute resources. A deployment either serves the request exactly or
refuses it at admission.

```json theme={null}
{
  "resources": {
    "cpu_millis": 50,
    "memory_mb": 4096
  }
}
```

## Resources

| Field         | Meaning                                                                                                                                |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `cpu_millis`  | Requested CPU in milliCPU, from 50 through 128000. `1000` is one CPU. Omit to use the deployment default (1000).                       |
| `memory_mb`   | Requested memory in MB, where MB means mebibytes (1024 MB = 1 GiB), from 1 through 1048576. Omit to use the deployment default (2048). |
| `gpus.count`  | Requested accelerator count. Refused on the current runtime; see [accelerators](#accelerators).                                        |
| `gpus.models` | Ordered fallback list of acceptable accelerator models. Requires a nonzero count.                                                      |

Requests are burstable: a sandbox is guaranteed its requested shape and may use idle node capacity
beyond it. A sizing field you leave unset resolves to the deployment default. A value you set
explicitly is honored as requested, or the create fails. A create is never accepted and then
silently provisioned at a different shape.

There is no disk-size or architecture field. `/workspace` sizing follows the
[storage class](/concepts/sandboxes#workspace) you select, not a per-create budget.

The CLI exposes sizing directly on create:

```sh theme={null}
hiloop sandbox create trainer --cpus 4 --memory-mb 8192
```

`--cpus` accepts exact decimal cores with up to three fractional digits, such as `0.05`, `0.125`,
or `1.5`. The API and JSON responses use integer `cpu_millis` so clients never depend on
floating-point rounding. Omit either flag to take the deployment default. Accelerator model
preferences are expressed through the API's `gpus.models` field rather than a CLI flag.

## Placement classes

`--placement-class standard` is the default. It adds no node constraint: the deployment remains
spot-first and may fall back to on-demand capacity when spot is unavailable.

`--placement-class non-preemptible` requires capacity the infrastructure provider does not reclaim
for capacity reasons. A deployment that has not bound that class to matching nodes refuses the
create with `unsupported_capability`; it never silently runs the request on spot. The class does
not promise dedicated tenancy or immunity from host failure, provider health events, node drains,
or operator action. It currently uses the same create authorization and has no separate billing
gate. It may take about a minute to create when a matching node must cold-provision.

Placement is immutable for a sandbox. A stop/start keeps its original class and node binding. A
new sandbox created from a snapshot chooses independently and defaults to `standard` unless the
create names `--placement-class non-preemptible` again.

## Accelerators

<Warning>
  GPU requests are refused on the current runtime. `--gpus` and the API's `resources.gpus` field
  are part of the contract, but no deployment advertises schedulable accelerator capacity, so a
  nonzero count is rejected at admission with `unsupported_capability` and the message
  `gpu resources have no schedulable capacity in this deployment`. No sandbox is created and the
  name is not consumed.
</Warning>

There is no runtime profile or accelerator-model flag on `hiloop sandbox create`. A sandbox's
environment comes from an image or a snapshot; see [sandboxes](/concepts/sandboxes#environment).

## How a deployment refuses

Capabilities are not discovered through an endpoint. A deployment states what it cannot serve by
refusing the request that needs it, at admission, with a named error:

| Error                    | Meaning                                                                                                                                                                                                              |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `unsupported_capability` | The deployment has no transport for what was asked. The message names the missing piece. Rendered as HTTP 422.                                                                                                       |
| `invalid_argument`       | The request is malformed or out of range, such as a model list with no count.                                                                                                                                        |
| `quota_exceeded`         | The request is well formed but exceeds one of your organization's limits. `details.quota.metric` names it: `sandboxes.running` frees when a sandbox stops or is deleted, `sandboxes.total` only when one is deleted. |

Requests refused this way on the current runtime are accelerator counts, volume mounts, and secret
bindings, plus `--storage-class durable` on a cluster that names
no backing storage class, and `--placement-class non-preemptible` on a deployment with no binding
for it. [What's live today](/sandboxes/overview#whats-live-today) is the current
list.

Admission never weakens a request to make it fit. If a deployment cannot enforce exactly what you
asked for, you get an error instead of a sandbox that quietly differs from it.

For the fixed network floor and fail-closed secret admission, see
[egress and secrets](/sandboxes/egress-secrets).