Starting a Sandbox
There are two ways to start a sandbox: warm start from a reusable template or snapshot, or cold start directly from an OCI image.
From a Template or Snapshot
Before using a warm start, create a template or a snapshot. You can then start any number of sandboxes from its alias or ID:
Usage:
aenv start <template-or-snapshot> [options]
Example:
# Start by alias
aenv start my-python-template
# Start by ID
aenv start 018f0d93-aaaa-bbbb-cccc-0123456789ab
Warm-start options:
| Argument or option | Default | Description |
|---|---|---|
<template-or-snapshot> | Required | Template or snapshot ID or alias. |
--timeout <seconds> | 300 | Set the sandbox TTL. The sandbox auto-pauses when it reaches the TTL; see Auto-Eviction. |
--volume <mount-path>=<volume> | None | Mount a persistent volume by ID or name. Repeat the option to mount multiple volumes. |
-d, --detach | Off | Print the sandbox ID and exit instead of attaching an interactive shell. |
Without --detach, aenv start waits for the sandbox to become ready and then
attaches an interactive shell. CPU, memory, and disk settings are inherited
from the template or snapshot and cannot be overridden on a warm start. The CLI
always enables secure sandbox authentication and manages the envd access token
automatically; see Secure Sandbox Authentication.
To retrieve the current state and configuration of one sandbox, use the HTTP API:
curl -H 'X-API-Key: test-key' \
http://127.0.0.1:8000/sandboxes/<sandbox-id>
Cold Start from an OCI Image
A cold start resolves an OCI image directly and prepares a fresh writable root filesystem at runtime:
Usage:
aenv start --cold <image> [options]
Example:
aenv start --cold ubuntu:24.04
aenv start --cold ubuntu:24.04 --cpu 4 --memory 4096 --disk-size-mb 65536
Cold-start options:
| Argument or option | Default | Description |
|---|---|---|
<image> | Required | External OCI image reference. |
--cold | Required for an OCI image | Cold start directly from <image>. |
--timeout <seconds> | 300 | Set the sandbox TTL. The sandbox auto-pauses when it reaches the TTL; see Auto-Eviction. |
--cpu <count> | [machine].vcpu_count from your AgentENV config file | Set the sandbox’s vCPU count. Alias: --cpu-count. |
--memory <MiB> | [machine].mem_size_mib from your config file | Set sandbox memory. Aliases: --memory-mb, --mem. |
--disk-size-mb <MiB> | Source image virtual size | Set root filesystem size. The value must be greater than zero and divisible by 1024 MiB. Alias: --disk-mb. |
--volume <mount-path>=<volume> | None | Mount a persistent volume by ID or name. Repeat the option to mount multiple volumes. |
-d, --detach | Off | Print the sandbox ID and exit instead of attaching an interactive shell. |
Cold-started sandboxes also use secure sandbox authentication by default.
The AgentENV config file is config/default.toml by default, or the file
specified by AENV_CONFIG_PATH.
An OverlayBD-native image can start without downloading the complete image first; its filesystem data is loaded from the registry on demand. See On-Demand Loading.
Growth of the disk size is allowed by
default. Shrinking below the source image size requires
ublk.overlaybd.allow_shrink = true in your AgentENV config file. Resizing
applies only when creating a fresh writable root filesystem, not to read-only
images, images with an existing upper layer, or snapshot resume. Sandbox
responses report the effective size as diskSizeMB.