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. cpu is a float and allows fractional guarantees like 0.5; explicit values below the platform minimum are clamped up to 0.125. vcpus is an integer alternative (default 2) that is used only when cpu is absent — if both are present, cpu wins.

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 create gets 2 vCPU / 1024 MiB / 512 MiB without any clamping.

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.

Placement: region

Optionally pins the sandbox to a region. 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 lists available regions — see Regions.

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 maps. 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 '@rlp/sdk'
 
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"
  }'