Skip to content
View as Markdown

Sandbox

Section titled “Sandbox”

Represents a Daytona Sandbox.

Properties:

  • autoArchiveInterval? number - Auto-archive interval in minutes
  • autoDeleteInterval? number - Auto-delete interval in minutes
  • autoStopInterval? number - Auto-stop interval in minutes
  • backupCreatedAt? string - When the backup was created (not returned by list results; call refreshData() on each item to populate)
  • backupState? SandboxBackupStateEnum - Current state of Sandbox backup
  • buildInfo? BuildInfo - Build information for the Sandbox if it was created from dynamic build (not returned by list results; call refreshData() on each item to populate)
  • codeInterpreter CodeInterpreter - Stateful interpreter interface for executing code. Currently supports only Python. For other languages, use the process.codeRun method.
  • computerUse ComputerUse - Computer use operations interface for desktop automation
  • cpu number - Number of CPUs allocated to the Sandbox
  • createdAt? string - When the Sandbox was created
  • disk number - Amount of disk space allocated to the Sandbox in GiB
  • env? Record<string, string> - Environment variables set in the Sandbox (not returned by list results; call refreshData() on each item to populate)
  • errorReason? string - Error message if Sandbox is in error state
  • fs FileSystem - File system operations interface
  • git Git - Git operations interface
  • gpu number - Number of GPUs allocated to the Sandbox
  • id string - Unique identifier for the Sandbox
  • labels Record<string, string> - Custom labels attached to the Sandbox
  • lastActivityAt? string - When the Sandbox last had activity
  • linkedSandboxId? string - ID of the Sandbox this Sandbox is linked to. When set, the Sandbox is co-located on the same runner as the linked Sandbox. (not returned by list results; call refreshData() on each item to populate)
  • memory number - Amount of memory allocated to the Sandbox in GiB
  • name string
  • networkAllowList? string - Comma-separated list of allowed CIDR network addresses for the Sandbox (not returned by list results; call refreshData() on each item to populate)
  • networkBlockAll? boolean - Whether to block all network access for the Sandbox (not returned by list results; call refreshData() on each item to populate)
  • organizationId string - Organization ID of the Sandbox
  • process Process - Process execution interface
  • public boolean - Whether the Sandbox is publicly accessible
  • recoverable? boolean - Whether the Sandbox error is recoverable.
  • snapshot? string - Daytona snapshot used to create the Sandbox
  • state? SandboxState - Current state of the Sandbox (e.g., “started”, “stopped”)
  • target string - Target location of the runner where the Sandbox runs
  • toolboxProxyUrl string
  • updatedAt? string - When the Sandbox was last updated
  • user string - OS user running in the Sandbox
  • volumes? SandboxVolume[] - Volumes attached to the Sandbox (not returned by list results; call refreshData() on each item to populate)

Constructors

Section titled “Constructors”

new Sandbox()

Section titled “new Sandbox()”
new Sandbox(
   sandboxDto: SandboxListItem | Sandbox,
   clientConfig: Configuration,
   axiosInstance: AxiosInstance,
   sandboxApi: SandboxApi): Sandbox

Creates a new Sandbox instance

Parameters:

  • sandboxDto The API Sandbox instance - SandboxListItem | Sandbox
  • clientConfig Configuration
  • axiosInstance AxiosInstance
  • sandboxApi SandboxApi

Returns:

  • Sandbox

Methods

Section titled “Methods”

_experimental_createSnapshot()

Section titled “_experimental_createSnapshot()”
_experimental_createSnapshot(name: string, timeout?: number): Promise<void>

Creates a snapshot from the current state of the Sandbox.

This captures the Sandbox’s filesystem into a reusable snapshot that can be used to create new Sandboxes. The Sandbox will temporarily enter a ‘snapshotting’ state and return to its previous state when complete.

Parameters:

  • name string - Name for the new snapshot
  • timeout? number = 60 - Maximum time to wait in seconds. 0 means no timeout. Defaults to 60-second timeout.

Returns:

  • Promise<void>

Throws:

  • If timeout is a negative number

  • If the snapshot operation fails or times out

Example:

const sandbox = await daytona.get('my-sandbox');
await sandbox._experimental_createSnapshot('my-snapshot');
console.log('Snapshot created successfully');

_experimental_fork()

Section titled “_experimental_fork()”
_experimental_fork(params?: {
  name: string;
}, timeout?: number): Promise<Sandbox>

Forks the Sandbox, creating a new Sandbox with an identical filesystem.

The forked Sandbox is a copy-on-write clone of the original. It starts with the same disk contents but operates independently from that point on.

Parameters:

  • params? Fork parameters
  • name? string - Optional name for the forked Sandbox. If not provided, a unique name will be generated.
  • timeout? number = 60 - Maximum time to wait in seconds. 0 means no timeout. Defaults to 60-second timeout.

Returns:

  • Promise<Sandbox> - The forked Sandbox.

Throws:

  • If timeout is a negative number

  • If the fork operation fails or times out

Example:

const sandbox = await daytona.get('my-sandbox');
const forked = await sandbox._experimental_fork({ name: 'my-fork' });
console.log(`Forked sandbox: ${forked.id}`);

archive()

Section titled “archive()”
archive(): Promise<void>

Archives the sandbox, making it inactive and preserving its state. When sandboxes are archived, the entire filesystem state is moved to cost-effective object storage, making it possible to keep sandboxes available for an extended period. The tradeoff between archived and stopped states is that starting an archived sandbox takes more time, depending on its size. Sandbox must be stopped before archiving.

Returns:

  • Promise<void>

createLspServer()

Section titled “createLspServer()”
createLspServer(languageId: string, pathToProject: string): Promise<LspServer>

Creates a new Language Server Protocol (LSP) server instance.

The LSP server provides language-specific features like code completion, diagnostics, and more.

Parameters:

  • languageId string - The language server type (e.g., “typescript”)
  • pathToProject string - Path to the project root directory. Relative paths are resolved based on the sandbox working directory.

Returns:

  • Promise<LspServer> - A new LSP server instance configured for the specified language

Example:

const lsp = await sandbox.createLspServer('typescript', 'workspace/project');

createSshAccess()

Section titled “createSshAccess()”
createSshAccess(expiresInMinutes?: number): Promise<SshAccessDto>

Creates an SSH access token for the sandbox.

Parameters:

  • expiresInMinutes? number - The number of minutes the SSH access token will be valid for.

Returns:

  • Promise<SshAccessDto> - The SSH access token.

delete()

Section titled “delete()”
delete(timeout: number): Promise<void>

Deletes the Sandbox.

Parameters:

  • timeout number = 60

Returns:

  • Promise<void>

expireSignedPreviewUrl()

Section titled “expireSignedPreviewUrl()”
expireSignedPreviewUrl(port: number, token: string): Promise<void>

Expires a signed preview url for the sandbox at the specified port.

Parameters:

  • port number - The port to expire the signed preview url on.
  • token string - The token to expire the signed preview url on.

Returns:

  • Promise<void>
Section titled “getPreviewLink()”
getPreviewLink(port: number): Promise<PortPreviewUrl>

Retrieves the preview link for the sandbox at the specified port. If the port is closed, it will be opened automatically. For private sandboxes, a token is included to grant access to the URL.

Parameters:

  • port number - The port to open the preview link on.

Returns:

  • Promise<PortPreviewUrl> - The response object for the preview link, which includes the url and the token (to access private sandboxes).

Example:

const previewLink = await sandbox.getPreviewLink(3000);
console.log(`Preview URL: ${previewLink.url}`);
console.log(`Token: ${previewLink.token}`);

getSignedPreviewUrl()

Section titled “getSignedPreviewUrl()”
getSignedPreviewUrl(port: number, expiresInSeconds?: number): Promise<SignedPortPreviewUrl>

Retrieves a signed preview url for the sandbox at the specified port.

Parameters:

  • port number - The port to open the preview link on.
  • expiresInSeconds? number - The number of seconds the signed preview url will be valid for. Defaults to 60 seconds.

Returns:

  • Promise<SignedPortPreviewUrl> - The response object for the signed preview url.

getUserHomeDir()

Section titled “getUserHomeDir()”
getUserHomeDir(): Promise<string>

Gets the user’s home directory path for the logged in user inside the Sandbox.

Returns:

  • Promise<string> - The absolute path to the Sandbox user’s home directory for the logged in user

Example:

const userHomeDir = await sandbox.getUserHomeDir();
console.log(`Sandbox user home: ${userHomeDir}`);

getUserRootDir()

Section titled “getUserRootDir()”
getUserRootDir(): Promise<string>

Returns:

  • Promise<string>
Deprecated
Section titled “Deprecated”

Use getUserHomeDir instead. This method will be removed in a future version.

getWorkDir()

Section titled “getWorkDir()”
getWorkDir(): Promise<string>

Gets the working directory path inside the Sandbox.

Returns:

  • Promise<string> - The absolute path to the Sandbox working directory. Uses the WORKDIR specified in the Dockerfile if present, or falling back to the user’s home directory if not.

Example:

const workDir = await sandbox.getWorkDir();
console.log(`Sandbox working directory: ${workDir}`);

recover()

Section titled “recover()”
recover(timeout?: number): Promise<void>

Recover the Sandbox from a recoverable error and wait for it to be ready.

Parameters:

  • timeout? number = 60 - Maximum time to wait in seconds. 0 means no timeout. Defaults to 60-second timeout.

Returns:

  • Promise<void>

Throws:

  • DaytonaError - If Sandbox fails to recover or times out

Example:

const sandbox = await daytona.get('my-sandbox-id');
await sandbox.recover();
console.log('Sandbox recovered successfully');

refreshActivity()

Section titled “refreshActivity()”
refreshActivity(): Promise<void>

Refreshes the sandbox activity to reset the timer for automated lifecycle management actions.

This method updates the sandbox’s last activity timestamp without changing its state. It is useful for keeping long-running sessions alive while there is still user activity.

Returns:

  • Promise<void>

Example:

// Keep sandbox activity alive
await sandbox.refreshActivity();

refreshData()

Section titled “refreshData()”
refreshData(): Promise<void>

Refreshes the Sandbox data from the API.

Returns:

  • Promise<void>

Example:

await sandbox.refreshData();
console.log(`Sandbox ${sandbox.id}:`);
console.log(`State: ${sandbox.state}`);
console.log(`Resources: ${sandbox.cpu} CPU, ${sandbox.memory} GiB RAM`);

resize()

Section titled “resize()”
resize(resources: Resources, timeout?: number): Promise<void>

Resizes the Sandbox resources.

Changes the CPU, memory, or disk allocation for the Sandbox. Hot resize (on running sandbox) only allows CPU/memory increases. Disk resize requires a stopped sandbox.

Parameters:

  • resources Resources - New resource configuration. Only specified fields will be updated.
    • cpu: Number of CPU cores (minimum: 1). For hot resize, can only be increased.
    • memory: Memory in GiB (minimum: 1). For hot resize, can only be increased.
    • disk: Disk space in GiB (can only be increased, requires stopped sandbox).
  • timeout? number = 60 - Timeout in seconds for the resize operation. 0 means no timeout.

Returns:

  • Promise<void>

Throws:

  • If hot resize constraints are violated, disk resize attempted on running sandbox, disk size decrease is attempted, no resource changes are specified, or resize operation times out.

Example:

// Increase CPU/memory on running sandbox (hot resize)
await sandbox.resize({ cpu: 4, memory: 8 });


// Change disk (sandbox must be stopped)
await sandbox.stop();
await sandbox.resize({ cpu: 2, memory: 4, disk: 30 });

revokeSshAccess()

Section titled “revokeSshAccess()”
revokeSshAccess(token: string): Promise<void>

Revokes an SSH access token for the sandbox.

Parameters:

  • token string - The token to revoke.

Returns:

  • Promise<void>

setAutoArchiveInterval()

Section titled “setAutoArchiveInterval()”
setAutoArchiveInterval(interval: number): Promise<void>

Set the auto-archive interval for the Sandbox.

The Sandbox will automatically archive after being continuously stopped for the specified interval.

Parameters:

  • interval number - Number of minutes after which a continuously stopped Sandbox will be auto-archived. Set to 0 for the maximum interval. Default is 7 days.

Returns:

  • Promise<void>

Throws:

  • DaytonaError - If interval is not a non-negative integer

Example:

// Auto-archive after 1 hour
await sandbox.setAutoArchiveInterval(60);
// Or use the maximum interval
await sandbox.setAutoArchiveInterval(0);

setAutoDeleteInterval()

Section titled “setAutoDeleteInterval()”
setAutoDeleteInterval(interval: number): Promise<void>

Set the auto-delete interval for the Sandbox.

The Sandbox will automatically delete after being continuously stopped for the specified interval.

Parameters:

  • interval number - Number of minutes after which a continuously stopped Sandbox will be auto-deleted. Set to negative value to disable auto-delete. Set to 0 to delete immediately upon stopping. By default, auto-delete is disabled.

Returns:

  • Promise<void>

Example:

// Auto-delete after 1 hour
await sandbox.setAutoDeleteInterval(60);
// Or delete immediately upon stopping
await sandbox.setAutoDeleteInterval(0);
// Or disable auto-delete
await sandbox.setAutoDeleteInterval(-1);

setAutostopInterval()

Section titled “setAutostopInterval()”
setAutostopInterval(interval: number): Promise<void>

Set the auto-stop interval for the Sandbox.

The Sandbox will automatically stop after being idle (no new events) for the specified interval. Events include any state changes or interactions with the Sandbox through the sdk. Interactions using Sandbox Previews are not included.

Parameters:

  • interval number - Number of minutes of inactivity before auto-stopping. Set to 0 to disable auto-stop. Default is 15 minutes.

Returns:

  • Promise<void>

Throws:

  • DaytonaError - If interval is not a non-negative integer

Example:

// Auto-stop after 1 hour
await sandbox.setAutostopInterval(60);
// Or disable auto-stop
await sandbox.setAutostopInterval(0);

setLabels()

Section titled “setLabels()”
setLabels(labels: Record<string, string>): Promise<Record<string, string>>

Sets labels for the Sandbox.

Labels are key-value pairs that can be used to organize and identify Sandboxes.

Parameters:

  • labels Record<string, string> - Dictionary of key-value pairs representing Sandbox labels

Returns:

  • Promise<Record<string, string>>

Example:

// Set sandbox labels
await sandbox.setLabels({
  project: 'my-project',
  environment: 'development',
  team: 'backend'
});

start()

Section titled “start()”
start(timeout?: number): Promise<void>

Start the Sandbox.

This method starts the Sandbox and waits for it to be ready.

Parameters:

  • timeout? number = 60 - Maximum time to wait in seconds. 0 means no timeout. Defaults to 60-second timeout.

Returns:

  • Promise<void>

Throws:

  • DaytonaError - If Sandbox fails to start or times out

Example:

const sandbox = await daytona.getCurrentSandbox('my-sandbox');
await sandbox.start(40);  // Wait up to 40 seconds
console.log('Sandbox started successfully');

stop()

Section titled “stop()”
stop(timeout?: number, force?: boolean): Promise<void>

Stops the Sandbox.

This method stops the Sandbox and waits for it to be fully stopped.

Parameters:

  • timeout? number = 60 - Maximum time to wait in seconds. 0 means no timeout. Defaults to 60-second timeout.
  • force? boolean = false - If true, uses SIGKILL instead of SIGTERM. Defaults to false.

Returns:

  • Promise<void>

Example:

const sandbox = await daytona.get('my-sandbox-id');
await sandbox.stop();
console.log('Sandbox stopped successfully');

updateNetworkSettings()

Section titled “updateNetworkSettings()”
updateNetworkSettings(settings: UpdateSandboxNetworkSettings): Promise<void>

Updates outbound network policy for this sandbox on the runner (for example block all traffic, restore general internet access, or apply a CIDR allow list) without stopping the sandbox.

This maps to the same mechanism as creating a sandbox with networkBlockAll / networkAllowList: the runner applies iptables rules to the sandbox container.

Parameters:

  • settings UpdateSandboxNetworkSettings - At least one of networkBlockAll or networkAllowList must be set. Set networkBlockAll to false to restore outbound access after a block (and clear a stored allow list).

Returns:

  • Promise<void>

Example:

// Pause internet (outbound blocked)
await sandbox.updateNetworkSettings({ networkBlockAll: true });
// Resume internet
await sandbox.updateNetworkSettings({ networkBlockAll: false });

validateSshAccess()

Section titled “validateSshAccess()”
validateSshAccess(token: string): Promise<SshAccessValidationDto>

Validates an SSH access token for the sandbox.

Parameters:

  • token string - The token to validate.

Returns:

  • Promise<SshAccessValidationDto> - The SSH access validation result.

waitForResizeComplete()

Section titled “waitForResizeComplete()”
waitForResizeComplete(timeout?: number): Promise<void>

Waits for the Sandbox resize operation to complete.

This method polls the Sandbox status until the state is no longer ‘resizing’.

Parameters:

  • timeout? number = 60 - Maximum time to wait in seconds. 0 means no timeout.

Returns:

  • Promise<void>

Throws:

  • If the sandbox ends up in an error state or resize times out.

waitUntilStarted()

Section titled “waitUntilStarted()”
waitUntilStarted(timeout?: number): Promise<void>

Waits for the Sandbox to reach the ‘started’ state.

This method polls the Sandbox status until it reaches the ‘started’ state or encounters an error.

Parameters:

  • timeout? number = 60 - Maximum time to wait in seconds. 0 means no timeout. Defaults to 60 seconds.

Returns:

  • Promise<void>

Throws:

  • DaytonaError - If the sandbox ends up in an error state or fails to start within the timeout period.

waitUntilStopped()

Section titled “waitUntilStopped()”
waitUntilStopped(timeout?: number): Promise<void>

Wait for Sandbox to reach ‘stopped’ state.

This method polls the Sandbox status until it reaches the ‘stopped’ state or encounters an error.

Parameters:

  • timeout? number = 60 - Maximum time to wait in seconds. 0 means no timeout. Defaults to 60 seconds.

Returns:

  • Promise<void>

Throws:

  • DaytonaError - If the sandbox fails to stop within the timeout period.

ListSandboxesQuery

Section titled “ListSandboxesQuery”

Properties:

  • createdAtAfter? Date - Include sandboxes created after this timestamp
  • createdAtBefore? Date - Include sandboxes created before this timestamp
  • id? string - Filter by ID prefix (case-insensitive)
  • isPublic? boolean - Filter by public status
  • isRecoverable? boolean - Filter by recoverable status
  • labels? Record<string, string> - Filter by labels
  • lastActivityAfter? Date - Include sandboxes with last activity after this timestamp
  • lastActivityBefore? Date - Include sandboxes with last activity before this timestamp
  • limit? number - Per-page fetch size. Does NOT limit the total number of Sandboxes returned.
  • maxCpu? number - Filter by maximum CPU
  • maxDiskGib? number - Filter by maximum disk space in GiB
  • maxMemoryGib? number - Filter by maximum memory in GiB
  • minCpu? number - Filter by minimum CPU
  • minDiskGib? number - Filter by minimum disk space in GiB
  • minMemoryGib? number - Filter by minimum memory in GiB
  • name? string - Filter by name prefix (case-insensitive)
  • order? SandboxListSortDirection - Sort direction
  • snapshots? string[] - Filter by snapshot names
  • sort? SandboxListSortField - Sort by field
  • states? SandboxState[] - Filter by states
  • targets? string[] - Filter by targets