Sandbox

The Daytona SDK core Sandbox functionality.

Provides the main Sandbox class representing a Daytona Sandbox that coordinates file system, Git, process execution, and LSP functionality. It serves as the central point for interacting with Daytona Sandboxes.

The Sandbox must be in a ‘started’ state before performing operations.

Example

// Create and initialize sandbox
const daytona = new Daytona();
const sandbox = await daytona.create();

// File operations
await sandbox.fs.uploadFile(
  '/app/config.json',
  new File(['{"setting": "value"}'], 'config.json')
);
const contentBlob = await sandbox.fs.downloadFile('/app/config.json');

// Git operations
await sandbox.git.clone('https://github.com/user/repo.git');

// Process execution
const response = await sandbox.process.executeCommand('ls -la');
console.log(response.result);

// LSP functionality
const lsp = sandbox.createLspServer('typescript', '/workspace/project');
await lsp.didOpen('/workspace/project/src/index.ts');
const completions = await lsp.completions('/workspace/project/src/index.ts', {
  line: 10,
  character: 15
});
console.log(completions);

Sandbox

Represents a Daytona Sandbox.

A Sandbox provides file system operations, Git operations, process execution, and LSP functionality. It serves as the main interface for interacting with a Daytona sandbox.

Constructors

new Sandbox()

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

Creates a new Sandbox instance

Parameters

Returns

Sandbox

Properties

Methods

toSandboxInfo()

static toSandboxInfo(instance: Workspace): SandboxInfo

Converts an API sandbox instance to a SandboxInfo object.

Parameters

Returns

SandboxInfo

The converted SandboxInfo object

toWorkspaceInfo()

static toWorkspaceInfo(instance: Workspace): SandboxInfo

Converts an API workspace instance to a WorkspaceInfo object.

Parameters

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

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

getPreviewLink(port: number): string

Gets the preview link for the sandbox at a specific port. If the port is not open, it will open it and return the link.

Parameters

Returns

string

The preview link for the sandbox at the specified port

Throws

If the node domain is not found in the provider metadata

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

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

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

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

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

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

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 SandboxCodeToolbox

Methods

getRunCommand()

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

Generates a command to run the provided code

Parameters

Returns

string

SandboxInfo

Structured information about a Sandbox

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

SandboxInfo

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

Properties

SandboxInstance

Extends

• Omit<ApiSandbox, "info">

Properties

SandboxResources

Resources allocated to a Sandbox

SandboxResources

Example

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

Properties