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

# Sandboxes

> Use Sandbox resources to create disposable Linux environments inside IDYL subnets.

A Sandbox is a disposable Linux environment created inside an IDYL subnet. Use
Sandboxes for short-lived work that needs a clean runtime boundary, a clear
expiry, and the same placement model as other IDYL workloads.

A Sandbox is a first-class workload resource. It has `kind`, `metadata`,
`spec`, and read-only `status` fields, and it uses a pod template to describe
the Linux environment to run.

## When to use a Sandbox

Use a Sandbox when you need a temporary environment for:

* Agent workspaces.
* Experiments.
* Tests.
* Builds.
* Debugging.
* Preview environments.

## Lifecycle

Every Sandbox has a required `spec.ttl`. The TTL uses duration strings such as
`15m`, `2h`, or `24h`. IDYL removes the Sandbox after the duration expires
unless it is deleted earlier.

Use `idyl delete sandbox <name>` to remove a Sandbox before expiry.

## Names and placement

The imperative CLI workflow can generate a Sandbox name:

```bash theme={null}
idyl create sandbox --image ubuntu:24.04 --ttl 2h --subnet <subnet>
```

Use `--name` when you want to choose the name:

```bash theme={null}
idyl create sandbox --name dev --image ubuntu:24.04 --ttl 2h --subnet <subnet>
```

Manifest workflows require `metadata.name`:

```yaml theme={null}
kind: Sandbox
metadata:
  name: dev
  subnet: <subnet>
spec:
  ttl: 2h
  template:
    spec:
      containers:
        - name: main
          imageURI: ubuntu:24.04
          command: ["sleep", "infinity"]
```

Use `metadata.subnet` in manifests or `--subnet` in CLI commands to choose the
subnet where the Sandbox should run.

## Isolation

Sandboxes can request a workload isolation class when allowed by the target
subnet:

```bash theme={null}
idyl create sandbox \
  --image ubuntu:24.04 \
  --ttl 2h \
  --subnet <subnet> \
  --isolation-class microvm
```

Supported public isolation class values are:

| Isolation class | Use                                |
| --------------- | ---------------------------------- |
| `container`     | Standard container isolation.      |
| `microvm`       | MicroVM-backed workload isolation. |

The isolation class is part of the Sandbox pod template. The target subnet and
compatible provider capacity must admit the requested value.

For the broader isolation model, see
[Workload isolation](/concepts/workload-isolation).

## Runtime status

When available, Sandbox status reports the associated pod for the environment.
Inspect the Sandbox to see TTL, expiry, image, and associated pod information:

```bash theme={null}
idyl get sandbox dev
```

Use `idyl get sandboxes` to list Sandboxes in the current namespace.

## Command scope

The documented Sandbox CLI workflow is create, inspect, apply, and delete:

```bash theme={null}
idyl create sandbox --image ubuntu:24.04 --ttl 2h --subnet <subnet>
idyl get sandboxes
idyl get sandbox dev
idyl apply -f sandbox.yaml
idyl delete sandbox dev
```

Sandbox-specific `shell`, `exec`, `cp`, `logs`, `wait`, and `scale` commands
are not part of the documented Sandbox CLI workflow. Use the published workload
commands for behavior documented outside the Sandbox workflow.

## Related pages

* [Create a Sandbox](/build/create-a-sandbox)
* [Subnets](/concepts/subnets)
* [Namespaces](/concepts/namespaces)
* [Workloads](/concepts/workloads)
* [Workload isolation](/concepts/workload-isolation)
* [Sandbox reference](/resources/reference/generated/sandbox)