Sandboxes - IDYL Docs

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:

idyl create sandbox --image ubuntu:24.04 --ttl 2h --subnet <subnet>

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

idyl create sandbox --name dev --image ubuntu:24.04 --ttl 2h --subnet <subnet>

Manifest workflows require metadata.name:

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:

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.

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:

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:

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.

​When to use a Sandbox

​Lifecycle

​Names and placement

​Isolation

​Runtime status

​Command scope

​Related pages