Daytona (client)

Daytona is the top-level client in the rlp module. It owns sandbox create/get/list/delete, delegates lifecycle helpers to Sandbox, and exposes the resource services as attributes. Construct it with an optional DaytonaConfig — configuration and environment-variable fallbacks are covered on the Python SDK page.

Python

from rlp import Daytona
 
daytona = Daytona()

Services

Attribute	Service	Manages
`daytona.snapshot`	`SnapshotService`	Image aliases and Dockerfile builds
`daytona.volume`	`VolumeService`	Persistent volumes
`daytona.object_store`	`ObjectStoreService`	S3-compatible bucket mounts
`daytona.secret`	`SecretService`	Project-scoped secrets
`daytona.fn`	`FunctionService`	Managed serverless functions

create()

Creates a sandbox and blocks until it reaches the started state. Creation is asynchronous server-side, so the client polls the sandbox until it is running (or errors, or the timeout elapses). Exactly one image source is required: snapshot (a snapshot name) or image (a registry ref).

Python

def create(
    params: CreateSandboxFromSnapshotParams | CreateSandboxFromImageParams | None = None,
    timeout: int = 60,
) -> Sandbox

Parameter	Type	Default	Description
`params`	`CreateSandboxFromSnapshotParams` \| `CreateSandboxFromImageParams`	`None`	Sandbox parameters; see the table below.
`timeout`	`int`	`60`	Seconds to wait for `started`. `0` waits indefinitely.

Both params dataclasses share these fields (plus snapshot: str or image: str respectively):

Field	Type	Default	Description
`name`	`str`	`None`	Optional sandbox name.
`env_vars`	`Dict[str, str]`	`{}`	Environment variables injected with their real values.
`labels`	`Dict[str, str]`	`{}`	Key/value labels (see the note below).
`resources`	`Resources`	`None`	`cpu` (may be fractional), `gpu`, `memory` (GiB), `disk` (GiB).
`mode`	`str`	`None`	`"burstable"` (default) or `"dedicated"`.
`ports`	`List[PortRequest]`	`None`	Ports to expose: `PortRequest(vm_port, proto="tcp")`.
`docker_data_mib`	`int`	`None`	Size of a dedicated `/var/lib/docker` device, in MiB.
`volumes`	`List[VolumeMount]`	`None`	Persistent volumes to attach.
`object_store_mounts`	`List[ObjectStoreMount]`	`None`	Object stores to FUSE-mount.
`secrets`	`List[str]`	`None`	Names of project secrets to attach.
`persistent`	`bool`	`None`	Persistent write layer — enables warm `stop()`/`start()`, `pause()`/`resume()`, `fork()`.
`spot`	`bool`	`None`	Spot tier: discounted but reclaimable.

Returns: a started Sandbox.

Raises: DaytonaValidationError if neither snapshot nor image is set, or timeout is negative; DaytonaTimeoutError if the sandbox is not started in time; DaytonaError if the sandbox lands in the error state.

Note: resources.memory, resources.disk, and labels are sent by the SDK but not applied by the API yet — only resources.cpu maps today. Use the REST API's mem_mib / scratch_mib to size memory and disk; region is also REST-only. See sandbox parameters.

Python

from rlp import CreateSandboxFromImageParams, PortRequest, Resources
 
sandbox = daytona.create(CreateSandboxFromImageParams(
    image="python:3.12-slim",
    resources=Resources(cpu=0.5),
    ports=[PortRequest(vm_port=8000)],
    persistent=True,
))

get()

Fetches a single sandbox by its id or name and returns a hydrated handle.

Python

def get(id_or_name: str) -> Sandbox

Returns: a Sandbox. Raises: DaytonaNotFoundError if no sandbox matches.

Python

sandbox = daytona.get("my-sandbox")
print(sandbox.state)

list()

Lists the project's sandboxes, optionally filtered client-side by id prefix, name prefix, and count.

Python

def list(query: ListSandboxesQuery | None = None) -> List[Sandbox]

Parameter	Type	Default	Description
`query.id`	`str`	`None`	Keep sandboxes whose id starts with this prefix.
`query.name`	`str`	`None`	Keep sandboxes whose name starts with this prefix.
`query.limit`	`int`	`None`	Truncate the result to at most this many sandboxes.

Returns: a list of Sandbox handles.

Python

from rlp import ListSandboxesQuery
 
for sb in daytona.list(ListSandboxesQuery(name="build-", limit=10)):
    print(sb.id, sb.state)

Lifecycle helpers

Each helper simply delegates to the same-named method on the sandbox handle — see Sandbox for full semantics, including which operations require a persistent sandbox.

Python

def start(sandbox: Sandbox, timeout: int = 60) -> None   # warm-start a stopped persistent sandbox
def stop(sandbox: Sandbox) -> None                       # warm-stop (persistent only)
def pause(sandbox: Sandbox) -> None                      # memory-preserving pause (persistent only)
def resume(sandbox: Sandbox, timeout: int = 60) -> None  # resume a paused sandbox
def delete(sandbox: Sandbox) -> None                     # delete any sandbox

Python

daytona.stop(sandbox)    # later...
daytona.start(sandbox)   # warm start on any capable runner
daytona.delete(sandbox)

See stop & start and pause & resume for lifecycle guides.

Services

create()

get()

list()

Lifecycle helpers

On this page