Daytona

Main class for interacting with the Daytona API.

Provides methods to create, retrieve, and list Sandboxes, and exposes service accessors for Snapshots and Volumes.

Implements AutoCloseable for deterministic HTTP resource cleanup.

Properties:

• CODE_TOOLBOX_LANGUAGE_LABEL String -

Constructors

new Daytona()

public Daytona()

Creates a client using environment variables.

Reads DAYTONA_API_KEY, DAYTONA_API_URL, and DAYTONA_TARGET.

Throws:

• DaytonaException - if required authentication is missing

new Daytona()

public Daytona(DaytonaConfig config)

Creates a client with explicit configuration.

Parameters:

• config DaytonaConfig - SDK configuration containing API key and endpoint settings

Throws:

• DaytonaException - if configuration is invalid or missing credentials

Methods

create()

public Sandbox create()

Creates a Sandbox with default parameters and timeout.

Returns:

• Sandbox - created and started Sandbox

Throws:

• DaytonaException - if creation or startup fails

create()

public Sandbox create(CreateSandboxFromSnapshotParams params)

Creates a Sandbox from snapshot-oriented parameters using default timeout.

Parameters:

• params CreateSandboxFromSnapshotParams - snapshot creation parameters

Returns:

• Sandbox - created and started Sandbox

Throws:

• DaytonaException - if creation or startup fails

create()

public Sandbox create(CreateSandboxFromImageParams params)

Creates a Sandbox from image-oriented parameters using default timeout.

Parameters:

• params CreateSandboxFromImageParams - image creation parameters

Returns:

• Sandbox - created and started Sandbox

Throws:

• DaytonaException - if creation or startup fails

create()

public Sandbox create(CreateSandboxFromSnapshotParams params, long timeoutSeconds)

Creates a Sandbox from snapshot parameters.

Parameters:

• params CreateSandboxFromSnapshotParams - snapshot creation parameters including env vars, labels, and lifecycle options
• timeoutSeconds long - maximum seconds to wait for the Sandbox to reach started

Returns:

• Sandbox - created and started Sandbox

Throws:

• DaytonaException - if creation fails or the Sandbox does not start in time

create()

public Sandbox create(CreateSandboxFromImageParams params, long timeoutSeconds)

Creates a Sandbox from image parameters.

Parameters:

• params CreateSandboxFromImageParams - image creation parameters including image source and optional resources
• timeoutSeconds long - maximum seconds to wait for the Sandbox to reach started

Returns:

• Sandbox - created and started Sandbox

Throws:

• DaytonaException - if creation fails or the Sandbox does not start in time

create()

public Sandbox create(CreateSandboxFromImageParams params, long timeoutSeconds, java.util.function.Consumer<String> onSnapshotCreateLogs)

Creates a new Sandbox from a declarative image with build log streaming.

Parameters:

• params CreateSandboxFromImageParams - creation parameters including the image definition
• timeoutSeconds long - maximum seconds to wait for the Sandbox to reach started
• onSnapshotCreateLogs java.util.function.Consumer<String> - callback for build log lines; null to skip streaming

Returns:

• Sandbox - created and started Sandbox

Throws:

• DaytonaException - if creation fails or the Sandbox does not start in time

get()

public Sandbox get(String sandboxIdOrName)

Retrieves a Sandbox by ID or name.

Parameters:

• sandboxIdOrName String - Sandbox identifier or name

Returns:

• Sandbox - resolved Sandbox

Throws:

• DaytonaException - if the Sandbox is not found or request fails

list()

public Iterable<Sandbox> list()

Iterates over all Sandboxes (no filter, default sort).

Returns a lazily-paged Iterable; see #list(ListSandboxesQuery) for details on partial hydration and Stream usage.

Returns:

• Iterable\<Sandbox\> - iterable over Sandboxes

list()

public Iterable<Sandbox> list(ListSandboxesQuery query)

Iterates over Sandboxes matching the given query.

The returned Iterable lazily fetches pages from the API as iteration proceeds. Sandboxes are hydrated from the list endpoint, so fields marked “Not returned by Daytona.list” on Sandbox (env, networkBlockAll, networkAllowList, volumes, buildInfo, backupCreatedAt) remain null until Sandbox#refreshData() is called. For a Stream variant see #listStream(ListSandboxesQuery).

ListSandboxesQuery query = new ListSandboxesQuery();
query.setLabels(Map.of("env", "dev"));
for (Sandbox sandbox : daytona.list(query)) {
System.out.println(sandbox.getId());
}

Parameters:

• query ListSandboxesQuery - optional filters, sorting, and per-page size

Returns:

• Iterable\<Sandbox\> - iterable over Sandboxes

listStream()

public Stream<Sandbox> listStream()

Streams all Sandboxes (no filter, default sort).

The returned stream should be closed (use try-with-resources).

Returns:

• Stream\<Sandbox\> - stream of Sandboxes

listStream()

public Stream<Sandbox> listStream(ListSandboxesQuery query)

Streams Sandboxes matching the given query.

The returned stream should be closed (use try-with-resources).

try (Stream<Sandbox> stream = daytona.listStream(query)) {
stream.filter(sb -> "started".equals(sb.getState()))
.limit(5)
.forEach(sb -> System.out.println(sb.getId()));
}

Parameters:

• query ListSandboxesQuery - optional filters, sorting, and per-page size

Returns:

• Stream\<Sandbox\> - stream of Sandboxes

snapshot()

public SnapshotService snapshot()

Returns Snapshot management service.

Returns:

• SnapshotService - snapshot service instance

volume()

public VolumeService volume()

Returns Volume management service.

Returns:

• VolumeService - volume service instance

secret()

public SecretService secret()

Returns Secret management service.

Returns:

• SecretService - secret service instance

close()

public void close()

Closes this client and releases underlying HTTP resources.