Sandbox

Represents a Daytona Sandbox instance.

Exposes lifecycle controls and operation facades for process execution, file-system access, and Git. State changes are streamed over WebSocket by default with polling as a safety net, or observed by polling only when the deprecated polling mode is enabled.

Properties:

process Process - Process execution interface for this Sandbox.
fs FileSystem - File-system operations interface for this Sandbox.
git Git - Git operations interface for this Sandbox.
computerUse ComputerUse - Computer use (desktop automation) interface for this Sandbox.
codeInterpreter CodeInterpreter - Stateful code interpreter for this Sandbox (Python).

Methods

createLspServer()

public LspServer createLspServer(String languageId, String pathToProject)

Creates an LSP server instance for the specified language and project.

Parameters:

languageId String - language server to start (e.g. “typescript”, “python”, “go”)
pathToProject String - absolute path to the project root inside the sandbox

Returns:

LspServer - a new LspServer configured for the given language

start()

public void start()

Starts this Sandbox with default timeout.

Throws:

DaytonaException - if the Sandbox fails to start

start()

public void start(long timeoutSeconds)

Starts this Sandbox and waits for readiness.

Parameters:

timeoutSeconds long - maximum seconds to wait; 0 disables timeout

Throws:

DaytonaException - if start fails or times out

stop()

public void stop()

Stops this Sandbox with default timeout.

Throws:

DaytonaException - if the Sandbox fails to stop

stop()

public void stop(long timeoutSeconds)

Stops this Sandbox and waits until fully stopped.

Parameters:

timeoutSeconds long - maximum seconds to wait; 0 disables timeout

Throws:

DaytonaException - if stop fails or times out

waitUntilStopped()

public void waitUntilStopped(long timeoutSeconds)

Waits until Sandbox reaches stopped (or destroyed) state.

Parameters:

timeoutSeconds long - maximum seconds to wait; 0 disables timeout

Throws:

DaytonaException - if timeout is invalid, state becomes error, or timeout expires

delete()

public void delete()

Deletes this Sandbox.

Fires the delete API call and returns immediately without waiting for the Sandbox to reach the destroyed state. Use #delete(long, boolean) with wait=true to block until destruction completes.

Throws:

DaytonaException - if the delete API call fails

delete()

public void delete(long timeoutSeconds)

Deletes this Sandbox.

Fires the delete API call and returns immediately. Use #delete(long, boolean) with wait=true to block until destroyed.

Parameters:

timeoutSeconds long - timeout for the HTTP request (and for waiting when wait is true in #delete(long, boolean))

Throws:

DaytonaException - if the delete API call fails

delete()

public void delete(long timeoutSeconds, boolean wait)

Deletes this Sandbox, optionally waiting for it to reach the destroyed state.

Parameters:

timeoutSeconds long - maximum seconds to wait when wait is true; 0 disables timeout. Ignored when wait is false.
wait boolean - if true, block until the Sandbox is destroyed

Throws:

DaytonaException - if deletion fails or times out

setLabels()

public Map<String, String> setLabels(Map<String, String> labels)

Replaces Sandbox labels.

Parameters:

labels Map<String, String> - label map to apply

Returns:

Map\<String, String\> - updated labels

Throws:

DaytonaException - if label update fails

setAutostopInterval()

public void setAutostopInterval(int minutes)

Sets Sandbox auto-stop interval.

Parameters:

minutes int - idle minutes before automatic stop

Throws:

DaytonaException - if the update fails

setAutoPauseInterval()

public void setAutoPauseInterval(int minutes)

Sets Sandbox auto-pause interval.

Parameters:

minutes int - idle minutes before automatic pause (0 means disabled)

Throws:

DaytonaException - if the update fails

setAutoArchiveInterval()

public void setAutoArchiveInterval(int minutes)

Sets Sandbox auto-archive interval.

Parameters:

minutes int - minutes in stopped state before automatic archive

Throws:

DaytonaException - if the update fails

setAutoDeleteInterval()

public void setAutoDeleteInterval(int minutes)

Sets Sandbox auto-delete interval.

Parameters:

minutes int - minutes before automatic deletion after stop

Throws:

DaytonaException - if the update fails

setTtl()

public void setTtl(int ttlMinutes)

Sets Sandbox TTL (time to live) in minutes. Set to 0 to disable the TTL. The deadline is computed server-side; call #refreshData() and read the updated value via #getAutoDestroyAt().

Parameters:

ttlMinutes int - minutes until the Sandbox is destroyed, or 0 to disable

Throws:

IllegalArgumentException - if ttlMinutes is negative
DaytonaException - if the update fails

updateNetworkSettings()

public void updateNetworkSettings(UpdateSandboxNetworkSettings settings)

Updates outbound network policy on the runner (block all, restore access, or CIDR allow list).

Parameters:

settings UpdateSandboxNetworkSettings - request body; at least one of networkBlockAll or networkAllowList must be set

Throws:

DaytonaException - if the update fails

updateSecrets()

public void updateSecrets(Map<String, String> secrets)

Replaces the set of vault secrets mounted in this Sandbox.

Each key is an environment variable name and each value is the name of an existing organization Secret. Pass an empty map to detach all secrets. Attached, detached, and rotated secrets take effect for outbound requests within seconds. New environment variables are only visible to processes spawned after the update; a Sandbox created without secrets must be restarted for newly attached secrets to work.

Parameters:

secrets Map<String, String> - map of environment variable name to organization Secret name

Throws:

DaytonaException - if the update fails

getUserHomeDir()

public String getUserHomeDir()

Returns home directory path for Sandbox user.

Returns:

String - absolute home directory path

Throws:

DaytonaException - if the request fails

getMetricsLatest()

public SandboxMetrics getMetricsLatest()

Gets the most recent resource usage sample directly from the sandbox daemon.

Unlike #getMetrics, which returns aggregated historical samples, this returns the single current reading without going through the telemetry backend.

Returns:

SandboxMetrics - the current resource usage sample for the sandbox

Throws:

DaytonaException - if the request fails

getMetrics()

public List<SandboxMetrics> getMetrics(OffsetDateTime start, OffsetDateTime end)

Gets historical time-series resource usage metrics for the sandbox.

When the deployment runs a dedicated Analytics API, metrics are fetched from it directly; otherwise they are fetched through the control-plane telemetry proxy. A null start defaults to the sandbox creation time; a null end defaults to the current time. Samples are returned ordered ascending by timestamp.

Parameters:

start OffsetDateTime - start of the time range, or null for the sandbox creation time
end OffsetDateTime - end of the time range, or null for the current time

Returns:

List\<SandboxMetrics\> - time-ordered usage samples over the requested range

Throws:

DaytonaException - if the request fails

getWorkDir()

public String getWorkDir()

Returns current working directory path.

Returns:

String - absolute working directory path

Throws:

DaytonaException - if the request fails

updateEnv()

public void updateEnv(Map<String, String> env)

Updates the Sandbox daemon’s process environment.

Newly spawned processes, sessions, and PTYs inherit the change; already-running processes keep their environment.

Parameters:

env Map<String, String> - environment variables to set in the daemon’s process environment

Throws:

DaytonaException - if the update fails

updateEnv()

public void updateEnv(Map<String, String> env, List<String> unset)

Updates the Sandbox daemon’s process environment.

Newly spawned processes, sessions, and PTYs inherit the change; already-running processes keep their environment.

Parameters:

env Map<String, String> - environment variables to set in the daemon’s process environment; null to set none
unset List<String> - environment variable names to remove; null to remove none

Throws:

DaytonaException - if the update fails

downloadUrl()

public String downloadUrl(String path, Long ttlSeconds)

Creates a pre-signed URL for downloading a file from the Sandbox.

The URL works with any HTTP client without auth headers and stays valid across sandbox restarts (downloads succeed only while the sandbox is running). The signing key is cached locally for up to 15 seconds; if the key was rotated from another client, URLs may be rejected until the cache refreshes.

String url = sandbox.downloadUrl("/home/user/report.pdf", null);
// curl "$url" -o report.pdf

Parameters:

path String - Path to the file in the Sandbox.
ttlSeconds Long - How long the URL stays valid, in seconds. Defaults to 3600. Zero or negative means never expires.

Returns:

String - Pre-signed download URL.

Throws:

DaytonaException - if the signing key cannot be fetched.

downloadUrl()

public String downloadUrl(String path)

Creates a pre-signed URL for downloading a file from the Sandbox.

Parameters:

path String - Path to the file in the Sandbox.

Returns:

String - Pre-signed download URL.

Throws:

DaytonaException - if the signing key cannot be fetched.

uploadUrl()

public String uploadUrl(String path, Long ttlSeconds)

Creates a pre-signed URL for uploading a file to the Sandbox.

Send a POST request with the file as multipart/form-data. The URL works with any HTTP client without auth headers. The signing key is cached locally for up to 15 seconds; if the key was rotated from another client, URLs may be rejected until the cache refreshes.

String url = sandbox.uploadUrl("/home/user/data.bin", null);
// curl -X POST -F "file=@local.bin" "$url"

Parameters:

path String - Destination path for the uploaded file in the Sandbox.
ttlSeconds Long - How long the URL stays valid, in seconds. Defaults to 3600. Zero or negative means never expires.

Returns:

String - Pre-signed upload URL.

Throws:

DaytonaException - if the signing key cannot be fetched.

uploadUrl()

public String uploadUrl(String path)

Creates a pre-signed URL for uploading a file to the Sandbox.

Parameters:

path String - Destination path for the uploaded file in the Sandbox.

Returns:

String - Pre-signed upload URL.

Throws:

DaytonaException - if the signing key cannot be fetched.

rotateSigningKey()

public void rotateSigningKey()

Rotates the sandbox signing key, invalidating all previously signed URLs.

Throws:

DaytonaException - if the signing key rotation fails.

waitUntilStarted()

public void waitUntilStarted(long timeoutSeconds)

Waits until Sandbox reaches started state.

Parameters:

timeoutSeconds long - maximum seconds to wait; 0 disables timeout

Throws:

DaytonaException - if timeout is invalid, state becomes failure, or timeout expires

waitForResizeComplete()

public void waitForResizeComplete(long timeoutSeconds)

Waits for a resize operation to complete.

Parameters:

timeoutSeconds long - maximum seconds to wait; 0 disables timeout

Throws:

DaytonaException - if resize times out or fails

refreshData()

public void refreshData()

Refreshes local Sandbox fields from latest API state. After refresh, all fields — including those not returned by Daytona#list — are populated.

Throws:

DaytonaException - if refresh fails

fork()

public Sandbox fork()

Forks this Sandbox, creating a new Sandbox with an identical filesystem. Uses default timeout of 60 seconds.

Example usage:

Sandbox forked = sandbox.fork();
System.out.println(forked.getId());

Returns:

Sandbox - the forked Sandbox in started state

Throws:

DaytonaException - if the fork operation fails or times out

fork()

public Sandbox fork(String name, long timeoutSeconds)

Forks this Sandbox, creating a new Sandbox with an identical filesystem. The forked Sandbox is a copy-on-write clone of the original.

Example usage:

Sandbox forked = sandbox.fork("my-fork", 120);
System.out.println(forked.getId());

Parameters:

name String - optional name for the forked Sandbox; null for auto-generated
timeoutSeconds long - maximum seconds to wait for the forked Sandbox to start; 0 disables timeout

Returns:

Sandbox - the forked Sandbox in started state

Throws:

DaytonaException - if the fork operation fails or times out

experimentalFork()

public Sandbox experimentalFork()

Forks this Sandbox, creating a new Sandbox with an identical filesystem. Uses default timeout of 60 seconds.

Deprecated: Use #fork() instead. This method will be removed in a future version.

Returns:

Sandbox - the forked Sandbox in started state

Throws:

DaytonaException - if the fork operation fails or times out

experimentalFork()

public Sandbox experimentalFork(String name, long timeoutSeconds)

Forks this Sandbox, creating a new Sandbox with an identical filesystem. The forked Sandbox is a copy-on-write clone of the original.

Deprecated: Use #fork(String, long) instead. This method will be removed in a future version.

Parameters:

name String - optional name for the forked Sandbox; null for auto-generated
timeoutSeconds long - maximum seconds to wait for the forked Sandbox to start; 0 disables timeout

Returns:

Sandbox - the forked Sandbox in started state

Throws:

DaytonaException - if the fork operation fails or times out

createSnapshot()

public void createSnapshot(String name)

Creates a snapshot from the current state of this Sandbox. Uses default timeout of 60 seconds.

Example usage:

sandbox.createSnapshot("my-snapshot");

Parameters:

name String - name for the new snapshot

Throws:

DaytonaException - if the snapshot operation fails

createSnapshot()

public void createSnapshot(String name, long timeoutSeconds)

Creates a snapshot from the current state of this Sandbox. The Sandbox will temporarily enter a ‘snapshotting’ state and return to its previous state when complete.

Example usage:

sandbox.createSnapshot("my-snapshot", 120);

Parameters:

name String - name for the new snapshot
timeoutSeconds long - maximum seconds to wait for the snapshot operation to complete; 0 disables timeout

Throws:

DaytonaException - if the snapshot operation fails

experimentalCreateSnapshot()

public void experimentalCreateSnapshot(String name)

Creates a snapshot from the current state of this Sandbox. Uses default timeout of 60 seconds.

Deprecated: Use #createSnapshot(String) instead. This method will be removed in a future version.

Parameters:

name String - name for the new snapshot

Throws:

DaytonaException - if the snapshot operation fails

experimentalCreateSnapshot()

public void experimentalCreateSnapshot(String name, long timeoutSeconds)

Creates a snapshot from the current state of this Sandbox. The Sandbox will temporarily enter a ‘snapshotting’ state and return to its previous state when complete.

Deprecated: Use #createSnapshot(String, long) instead. This method will be removed in a future version.

Parameters:

name String - name for the new snapshot
timeoutSeconds long - maximum seconds to wait for the snapshot operation to complete; 0 disables timeout

Throws:

DaytonaException - if the snapshot operation fails

pause()

public void pause() throws DaytonaException

Pauses the Sandbox, freezing all running processes. Uses default timeout of 60 seconds.

Throws:

DaytonaException - if the pause operation fails

pause()

public void pause(long timeoutSeconds) throws DaytonaException

Pauses the Sandbox, freezing all running processes. Completes when the Sandbox has left the pausing state — any non-error terminal state (paused, stopped, archived, etc.) is accepted.

Parameters:

timeoutSeconds long - maximum time to wait in seconds (0 = no timeout)

Throws:

DaytonaException - if timeout is negative or the operation fails/times out

getId()

public String getId()

Returns:

String - Sandbox ID.

getName()

public String getName()

Returns:

String - Sandbox name.

getOrganizationId()

public String getOrganizationId()

Returns:

String - organization ID that owns this Sandbox.

getSnapshot()

public String getSnapshot()

Returns:

String - Daytona snapshot used to create this Sandbox, or null if none.

getUser()

public String getUser()

Returns:

String - OS user running in the Sandbox.

getLabels()

public Map<String, String> getLabels()

Returns:

Map\<String, String\> - custom labels attached to the Sandbox.

getPublic()

public Boolean getPublic()

Returns:

Boolean - whether the Sandbox HTTP preview is publicly accessible.

getTarget()

public String getTarget()

Returns:

String - target region/environment where the Sandbox runs.

getCpu()

public int getCpu()

Returns:

int - allocated CPU cores.

getGpu()

public int getGpu()

Returns:

int - allocated GPU units.

isSpot()

public boolean isSpot()

Returns whether this is a spot GPU Sandbox.

Spot Sandboxes may be instantly terminated to free capacity for on-demand GPU Sandboxes.

Returns:

boolean - true when the Sandbox is preemptible.

getSpotEvictedAt()

public String getSpotEvictedAt()

Returns:

String - when the Sandbox was evicted by spot preemption, or null when it was not.

getMemory()

public int getMemory()

Returns:

int - allocated memory in GiB.

getDisk()

public int getDisk()

Returns:

int - allocated disk in GiB.

getState()

public String getState()

Returns:

String - current lifecycle state (e.g. “started”, “stopped”).

getErrorReason()

public String getErrorReason()

Returns:

String - error message if the Sandbox is in an error state, or null.

getRecoverable()

public Boolean getRecoverable()

Returns:

Boolean - whether the Sandbox error is recoverable, or null if unknown.

getBackupState()

public String getBackupState()

Returns:

String - current state of the Sandbox backup as a string, or null.

getAutoStopInterval()

public Integer getAutoStopInterval()

Returns:

Integer - auto-stop interval in minutes (0 means disabled).

getAutoPauseInterval()

public Integer getAutoPauseInterval()

Returns:

Integer - auto-pause interval in minutes (0 means disabled).

getAutoArchiveInterval()

public Integer getAutoArchiveInterval()

Returns:

Integer - auto-archive interval in minutes.

getAutoDeleteInterval()

public Integer getAutoDeleteInterval()

Returns:

Integer - auto-delete interval in minutes (negative means disabled).

getCreatedAt()

public String getCreatedAt()

Returns:

String - when the Sandbox was created, or null.

getUpdatedAt()

public String getUpdatedAt()

Returns:

String - when the Sandbox was last updated, or null.

getLastActivityAt()

public String getLastActivityAt()

Returns:

String - when the Sandbox last had activity, or null.

getAutoDestroyAt()

public String getAutoDestroyAt()

Returns:

String - when the Sandbox expires, or null if no TTL is set.

getToolboxProxyUrl()

public String getToolboxProxyUrl()

Returns:

String - toolbox proxy URL.

getEnv()

public Map<String, String> getEnv()

Returns Sandbox environment variables.

Not returned by Daytona#list; call #refreshData() on each item to populate.

Returns:

Map\<String, String\> - environment map, or null if not yet populated

getNetworkBlockAll()

public Boolean getNetworkBlockAll()

Returns whether all network access is blocked for this Sandbox.

Not returned by Daytona#list; call #refreshData() on each item to populate.

Returns:

Boolean - block-all flag, or null if not yet populated

getNetworkAllowList()

public String getNetworkAllowList()

Returns the comma-separated CIDR allow list, if any.

Not returned by Daytona#list; call #refreshData() on each item to populate.

Returns:

String - allow list, or null

getDomainAllowList()

public String getDomainAllowList()

Returns the comma-separated list of allowed domains, if any.

Not returned by Daytona#list; call #refreshData() on each item to populate.

Returns:

String - allowed domains, or null

getOutboundProxyUrl()

public String getOutboundProxyUrl()

Returns the outbound proxy URL to route the sandbox HTTP(S) traffic through, if any.

Not returned by Daytona#list; call #refreshData() on each item to populate. Applied via the HTTP(S)_PROXY environment variables; combine with domainAllowList for network-layer enforcement.

Returns:

String - outbound proxy URL, or null

getVolumes()

public List<SandboxVolume> getVolumes()

Returns volumes attached to the Sandbox.

Not returned by Daytona#list; call #refreshData() on each item to populate.

Returns:

List\<SandboxVolume\> - immutable list of attached volumes, or null if not yet populated

getBuildInfo()

public BuildInfo getBuildInfo()

Returns build information if the Sandbox was created from a dynamic build.

Not returned by Daytona#list; call #refreshData() on each item to populate.

Returns:

BuildInfo - build info, or null

getBackupCreatedAt()

public String getBackupCreatedAt()

Returns the creation timestamp of the last backup.

Not returned by Daytona#list; call #refreshData() on each item to populate.

Returns:

String - backup timestamp, or null

getProcess()

public Process getProcess()

Returns:

Process - process operations facade.

getFs()

public FileSystem getFs()

Returns:

FileSystem - file-system operations facade.

getGit()

public Git getGit()

Returns:

Git - Git operations facade.