Parameter Reference

This page is the complete reference for the POST /vms create request. Only image is required — every other field has a sensible default, so a minimal create is just {"image": "python:3.12-slim"}. The table gives the one-line summary; the sections below explain each field's behavior in detail.

Create request parameters

Identity: name

The name is a display label to help you find sandboxes in lists and the dashboard. If you omit it, the API generates one of the form sandbox-<8 hex chars>. Names are not required to be unique within a project, so treat the sandbox id as the canonical identifier and the name as a human-friendly hint.

Boot source: image

The only required field. It accepts a bare string or a typed object covering five shapes: registry references, named project images, inline Dockerfile builds, and VM-state snapshot restores. A bare string containing / or : is treated as a registry reference; otherwise it is treated as a named project image. The shapes and their tradeoffs are covered in Image sources.

Resources: mode, cpu, vcpus, mem_mib, scratch_mib

mode selects how resource numbers are interpreted. In burstable (the default) they are a guaranteed floor and the sandbox can use idle capacity beyond it; in dedicated the sandbox is shaped exactly as requested. Any other value is rejected with 400. See Burstable vs dedicated.

CPU can be specified two ways, and its meaning depends on mode. cpu is a float; vcpus is an integer alternative used only when cpu is absent (if both are present, cpu wins).

• In burstable mode cpu is a fractional guaranteed floor with a 0.125-core minimum; explicit values below that are clamped up. A bare burstable create — no cpu and no vcpus — defaults to the 0.125 floor (and can still burst higher, best-effort).
• In dedicated mode CPU is whole-integer cores: your request is rounded up to an integer (minimum 1), and that integer is both the guarantee and the pinned boot shape. There is no fractional guarantee in dedicated mode. The maximum is the platform CPU cap (16 cores by default); a larger request is rejected with 400.

Memory (mem_mib) defaults to 1024 MiB. If you set it explicitly, values below 512 are clamped up to 512; burstable sandboxes may not guarantee more than 32768 MiB (requests above that are rejected with 400).

Disk (scratch_mib) is the sandbox's writable storage, defaulting to 512 MiB. Explicitly-set values are clamped up to a 10240 MiB minimum; burstable sandboxes may not guarantee more than 262144 MiB.

Note: The clamp-up rules apply only to explicit values. An omitted field keeps its small default — so a bare burstable create reserves a 0.125-core floor with 1024 MiB / 512 MiB, and bursts into idle capacity above that.

GPU: gpu_host

The number of GPUs to attach to the sandbox, defaulting to 0 (a CPU-only sandbox). Each GPU is dedicated to the sandbox for its lifetime; you request a count, and the platform selects the physical hardware and places the sandbox on a GPU-capable host. Use an image that ships the NVIDIA userspace tools (a CUDA base image). GPU sandboxes are cold-booted and do not support pause/resume in the current release. See GPU sandboxes.

Docker: docker_data_mib

Sets the size of a dedicated ephemeral device mounted at /var/lib/docker, enabling a full Docker daemon inside the sandbox. It is unset by default; sandboxes created from an image built with docker: true automatically get a 10240 MiB (10 GiB) device. The device is recreated fresh on every boot and is excluded from snapshots — see Docker in sandboxes for the full behavior and restrictions.

Networking: ports

Each entry asks the platform to forward an externally reachable port to a port inside the sandbox: {"vm_port": 8080, "proto": "tcp"} (proto defaults to tcp). You do not choose the host port — the platform assigns one and reports it in the sandbox's port_map once running. See Port forwarding.

Storage attachments: volumes and object_store_mounts

volumes attaches persistent, shareable volumes into the sandbox's filesystem. Each entry names the volume (by name or id), an absolute mount_path, and optionally a subpath to mount a subdirectory instead of the volume root. object_store_mounts similarly mounts S3-compatible object stores, with an optional read_only override.

Both share the same rules: at most 8 mounts each, mount_path must be absolute and must not contain .., and the reserved paths /, /proc, /sys, and /dev are rejected. The referenced volume or object store must be in the ready state, otherwise the create fails with 409. Sandboxes that attach volumes cold-boot, so creation is slightly slower than a plain cached-image create.

Configuration: env and secrets

env is a plain name → value map injected into the sandbox verbatim — anything inside the sandbox can read the real values. Names must match [A-Za-z_][A-Za-z0-9_]* and values are limited to 64 KiB. secrets is a list of project secret names; the sandbox only ever sees opaque placeholders, and real values are substituted into outbound requests scoped by each secret's allowed domains. Named secrets must already exist or the create fails with 400. See Environment & secrets.

Durability and pricing: persistent and spot

persistent: true moves the sandbox's write layer onto durable network storage, enabling warm stop/start, pause/resume, and fork — details on Persistent sandboxes. spot: true opts into discounted, reclaimable capacity and is immutable after create — details on Spot sandboxes.

Network egress: egress_policy

Optionally restricts the sandbox's outbound network. When set with enabled: true, the sandbox default-denies all egress except an allow list of IPs, CIDRs, and domains (plus DNS). It is {"enabled": bool, "allow": [string]}, immutable after create, and absent/enabled: false leaves egress open. This is the primary containment control for untrusted code — see Restricting outbound network.

Placement: region

Optionally pins the sandbox to a region. Accepts either a region slug or a global region id (world, us, eu, …); a global region is expanded to one of its member regions at create time. When absent, the region is resolved from the project default, then the organization default, then the platform default. An unknown or disabled region fails the create with 400. GET /regions and GET /global-regions list the available targets — see Regions.

CPU architecture and type: cpu_arch, cpu_type

Both are optional and steer the sandbox onto specific hardware within its region (a region may run a mix of architectures). Omit both and the sandbox lands on the platform default fleet (amd64).

• cpu_arch — "amd64" (default) or "arm64". Selects the CPU architecture; anything else is rejected with 400.
• cpu_type — a hardware-tier slug from GET /cpu-types (for example zen5, zen4, graviton). More specific than cpu_arch, and it implies its architecture — so set one or the other, not both. A slug that isn't in the registry, or one whose architecture contradicts an explicit cpu_arch, fails with 400 (e.g. cpu_arch: "amd64" with cpu_type: "graviton" is invalid because graviton is arm64).

Each CPU type carries an ordered tier (1 = lowest) within its architecture, returned in the tier field of GET /cpu-types. Like the host classes below, placement prefers an exact match and only falls back upward to a higher tier of the same architecture when no exact-tier host is available — you never get a lower CPU tier than you asked for. Tiers are compared only within an architecture, so an amd64 request never falls back onto an arm64 host.

The image you boot must be available for the requested architecture. See Architecture support for image, snapshot, and caching implications.

Host classes: network_class, disk_class

Both are optional and steer the sandbox onto hosts with specific NIC and NVMe hardware within its region. Omit them and the sandbox lands on any available host.

• network_class — a NIC-class slug from GET /network-classes (for example 10g, 25g, 100g).
• disk_class — an NVMe-class slug from GET /disk-classes (for example nvme-gen3, nvme-gen4, nvme-gen5).

Each class has an ordered tier (1 = lowest), returned in the tier field of the discovery endpoints. When you pin a class, placement prefers an exact match and only falls back upward to a higher tier when no exact-tier host is available — it never places you on a lower tier than you asked for. So a 100g request never lands on a 25g host, but a 25g request may land on a 100g host when no 25g host is free (you get at least the class you requested, sometimes better). This is a floor, not a fixed assignment.

A slug that isn't in the registry fails the create with 400. These constraints are not supported for GPU or Windows sandboxes (they route to dedicated fleets) and fail with 400 if combined.

If no host at the requested class or higher is available, the create waits and is canceled after the platform's create max-queue-time (default 60s), landing failed with a "not picked up" error.

Validation notes

• Explicitly-set resources are clamped up to platform minimums; omitted fields use defaults without clamping.
• Burstable requests above the burst caps are rejected (400).
• Unknown fields are silently ignored — watch for typos.
• env names must match [A-Za-z_][A-Za-z0-9_]*.
• Secret names must exist in the project or the create is rejected (400).

SDK parameter mapping

The SDKs use idiomatic field names that map onto the REST fields:

Note (known gaps): The SDK resources.memory / resources.disk fields and labels are not applied by the API yet — only resources.cpu and resources.gpu map. To set memory or disk, call the REST API directly with mem_mib / scratch_mib. Similarly, region is REST-only: the SDKs do not send it.

Full example

A "kitchen-sink" create exercising most parameters:

from rlp import (
    Daytona, CreateSandboxFromImageParams, Resources,
    PortRequest, VolumeMount, ObjectStoreMount,
)
 
daytona = Daytona()
sandbox = daytona.create(CreateSandboxFromImageParams(
    name="worker-1",
    image="python:3.12-slim",
    mode="burstable",
    resources=Resources(cpu=0.5),
    env_vars={"LOG_LEVEL": "debug"},
    secrets=["OPENAI_API_KEY"],
    ports=[PortRequest(vm_port=8080)],
    volumes=[VolumeMount(volume_id="training-data", mount_path="/data")],
    object_store_mounts=[ObjectStoreMount(object_store="results", mount_path="/results")],
    persistent=True,
    spot=True,
))

import { Daytona } from 'rlpsdk'
 
const daytona = new Daytona()
const sandbox = await daytona.create({
  name: 'worker-1',
  image: 'python:3.12-slim',
  mode: 'burstable',
  resources: { cpu: 0.5 },
  envVars: { LOG_LEVEL: 'debug' },
  secrets: ['OPENAI_API_KEY'],
  ports: [{ vmPort: 8080 }],
  volumes: [{ volumeId: 'training-data', mountPath: '/data' }],
  objectStoreMounts: [{ objectStore: 'results', mountPath: '/results' }],
  persistent: true,
  spot: true,
})

curl -X POST https://api.rl.trydaytona.com/vms \
  -H "Authorization: Bearer $RLP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "worker-1",
    "image": "python:3.12-slim",
    "mode": "burstable",
    "cpu": 0.5,
    "mem_mib": 2048,
    "scratch_mib": 20480,
    "env": {"LOG_LEVEL": "debug"},
    "secrets": ["OPENAI_API_KEY"],
    "ports": [{"vm_port": 8080, "proto": "tcp"}],
    "volumes": [{"volume": "training-data", "mount_path": "/data"}],
    "object_store_mounts": [{"object_store": "results", "mount_path": "/results"}],
    "persistent": true,
    "spot": true,
    "region": "us-east",
    "cpu_type": "zen5"
  }'