Skip to content

Sandbox

Represents a Daytona Sandbox.

Properties:

  • fs FileSystem - File system operations interface
  • git Git - Git operations interface
  • id string - Unique identifier for the Sandbox
  • instance SandboxInstance - The underlying Sandbox instance
  • process Process - Process execution interface
  • sandboxApi WorkspaceApi - API client for Sandbox operations
  • toolboxApi ToolboxApi - API client for toolbox operations

Constructors

new Sandbox()

new Sandbox(
   id: string,
   instance: SandboxInstance,
   sandboxApi: WorkspaceApi,
   toolboxApi: ToolboxApi,
   codeToolbox: SandboxCodeToolbox): Sandbox

Creates a new Sandbox instance

Parameters:

  • id string - Unique identifier for the Sandbox
  • instance SandboxInstance - The underlying Sandbox instance
  • sandboxApi WorkspaceApi - API client for Sandbox operations
  • toolboxApi ToolboxApi - API client for toolbox operations
  • codeToolbox SandboxCodeToolbox - Language-specific toolbox implementation

Returns:

  • Sandbox

Methods

toSandboxInfo()

static toSandboxInfo(instance: Workspace): SandboxInfo

Converts an API sandbox instance to a SandboxInfo object.

Parameters:

  • instance Workspace - The API sandbox instance to convert

Returns:

  • SandboxInfo - The converted SandboxInfo object

toWorkspaceInfo()

static toWorkspaceInfo(instance: Workspace): SandboxInfo

Converts an API workspace instance to a WorkspaceInfo object.

Parameters:

  • instance Workspace - The API workspace instance to convert

Returns:

  • SandboxInfo - The converted WorkspaceInfo object
Deprecated

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

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()

createLspServer(languageId: string, pathToProject: string): 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 - Absolute path to the project root directory

Returns:

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

Example:

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

delete()

delete(): Promise<void>

Deletes the Sandbox.

Returns:

  • Promise<void>
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}`);

getUserRootDir()

getUserRootDir(): Promise<undefined | string>

Gets the root directory path for the logged in user inside the Sandbox.

Returns:

  • Promise<undefined | string> - The absolute path to the Sandbox root directory for the logged in user

Example:

const rootDir = await sandbox.getUserRootDir();
console.log(`Sandbox root: ${rootDir}`);

getWorkspaceRootDir()

getWorkspaceRootDir(): Promise<undefined | string>

Returns:

  • Promise<undefined | string>
Deprecated

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

info()

info(): Promise<SandboxInfo>

Gets structured information about the Sandbox.

Returns:

  • Promise<SandboxInfo> - Detailed information about the Sandbox including its configuration, resources, and current state

Example:

const info = await sandbox.info();
console.log(`Sandbox ${info.name}:`);
console.log(`State: ${info.state}`);
console.log(`Resources: ${info.resources.cpu} CPU, ${info.resources.memory} RAM`);

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()

setLabels(labels: Record<string, string>): Promise<void>

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<void>

Example:

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

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()

stop(timeout?: number): 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.

Returns:

  • Promise<void>

Example:

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

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()

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.

SandboxCodeToolbox

Interface defining methods that a code toolbox must implement

Methods

getRunCommand()

getRunCommand(code: string, params?: CodeRunParams): string

Generates a command to run the provided code

Parameters:

  • code string
  • params? CodeRunParams

Returns:

  • string

SandboxInfo

Structured information about a Sandbox

Properties:

  • autoStopInterval number - Auto-stop interval in minutes

  • class CreateNodeClassEnum - Sandbox class

  • env Record<string, string> - Environment variables set in the Sandbox

  • errorReason null | string - Error message if Sandbox is in error state

  • id string - Unique identifier for the Sandbox

  • image string - Docker image used for the Sandbox

  • labels Record<string, string> - Custom labels attached to the Sandbox

  • lastSnapshot null | string - When the last snapshot was created

  • name string - Display name of the Sandbox

  • nodeDomain string - Domain name of the Sandbox node

  • providerMetadata? string - Deprecated - Use state, nodeDomain, region, class, updatedAt, lastSnapshot, resources, autoStopInterval instead.

  • public boolean - Whether the Sandbox is publicly accessible

  • region CreateNodeRegionEnum - Region of the Sandbox node

  • resources SandboxResources - Resource allocations for the Sandbox

  • snapshotCreatedAt null | Date - When the snapshot was created

  • snapshotState null | string - Current state of Sandbox snapshot

  • state WorkspaceState - Current state of the Sandbox (e.g., “started”, “stopped”)

  • target string - Target environment where the Sandbox runs

  • updatedAt string - When the Sandbox was last updated

  • user string - OS user running in the Sandbox

This interface provides detailed information about a Sandbox’s configuration, resources, and current state.

Example:

const sandbox = await daytona.create();
const info = await sandbox.info();
console.log(`Sandbox ${info.name} is ${info.state}`);
console.log(`Resources: ${info.resources.cpu} CPU, ${info.resources.memory} RAM`);

Extends:

  • WorkspaceInfo

SandboxInstance

Extends:

Properties:

  • info? SandboxInfo

  • Omit<ApiSandbox, "info">

SandboxResources

Resources allocated to a Sandbox

Properties:

  • cpu string - Number of CPU cores allocated (e.g., “1”, “2”)
  • disk string - Amount of disk space allocated with unit (e.g., “10Gi”, “20Gi”)
  • gpu null | string - Number of GPUs allocated (e.g., “1”) or null if no GPU
  • memory string - Amount of memory allocated with unit (e.g., “2Gi”, “4Gi”)

Example:

const resources: SandboxResources = {
  cpu: "2",
  gpu: "1",
  memory: "4Gi",
  disk: "20Gi"
};