Daytona SDK v0.21.0: Breaking Changes & Migration Guide

Why This Matters

In v0.21.0, we’re introducing a more robust architecture centered around snapshots, replacing the legacy pre-built image flow. This refactor enables better caching, more declarative sandbox provisioning, and consistent behavior across TypeScript and Python implementations.

This upcoming release includes breaking changes, which means if you're using v0.20.2 or earlier, you’ll need to update your integration to keep things working as expected, especially if you rely on the declarative image builder.

Migration Timeline

• Old version: v0.20.2

• New version: v0.21.0

• Compatibility: The refactored backend is temporarily backward-compatible, but declarative image builder support will break for v0.20.2.

• Recommended action: Upgrade to v0.21.0 now to access new features and ensure continued support.

🛠 Maintenance Notice

To support this SDK upgrade, scheduled downtime will occur on Sunday, June 15th, from 03:00 to 03:30 Pacific Time. Services may be temporarily unavailable during this window.

🔄 Key Changes Overview

1. Image creation → Snapshot creation
   A more powerful snapshot abstraction replaces pre-built images.

2. New parameter types for sandbox creation
   CreateSandboxParams is now split into more explicit types.

3. New Resources object
   Resource configuration is standardized and explicit.

4. Renamed callback parameters
   All callback-related options now reflect the snapshot-based flow.

5. New Snapshot Service
   Easily list, create, delete, and inspect snapshots from your SDK.

6. Removed SandboxTargetRegion enum
   Define target region using a plain string value.

7. Reduced verbosity of method for retrieving a single Sandbox
   A more concise get method is now available on the Daytona object.

8. Removed deprecated aliases for Sandbox methods
   Using deprecated workspace methods is no longer supported.

9. Flattened Sandbox instance information
   Sandbox details are now only available as top-level properties.

10. Removed legacy Sandbox properties
    Name and class are no longer present on the Sandbox object.

11. Improved functionality for refreshing Sandbox information
    The new method updates the Sandbox object properties directly.

12. Removed deprecated method for Sandbox removal in the TypeScript SDK
    Using daytona.remove(sandbox) is no longer supported.

1. Images → Snapshots

Snapshots now power sandbox creation. Here’s how the change looks in practice:

TypeScript

Before:

// Creating a pre-built image
const imageName = `example:${Date.now()}`;
await daytona.createImage(imageName, image, { onLogs: console.log });
// Using the pre-built image
const sandbox = await daytona.create(
  { image: imageName }
);

After:

// Creating a snapshot
const snapshotName = `example:${Date.now()}`;
await daytona.snapshot.create(
  {
    name: snapshotName,
    image,
    resources: {
      cpu: 1,
      memory: 1,
      disk: 3,
    },
  },
  { onLogs: console.log }
);
// Using the snapshot
const sandbox = await daytona.create({
  snapshot: snapshotName,
});

Python

Before:

# Creating a pre-built image
image_name = f"python-example:{int(time.time())}"
daytona.create_image(image_name, image, on_logs=print)
# Using the pre-built image
sandbox = daytona.create(
    CreateSandboxParams(image=image_name),
)

After:

# Creating a snapshot
snapshot_name = f"python-example:{int(time.time())}"
daytona.snapshot.create(
    CreateSnapshotParams(
        name=snapshot_name,
        image=image,
        resources=Resources(
            cpu=1,
            memory=1,
            disk=3,
        ),
    ),
    on_logs=print,
)
# Using the snapshot
sandbox = daytona.create(
  CreateSandboxFromSnapshotParams(snapshot=snapshot_name)
)

2. New Parameter Types for Sandbox Creation

We’ve replaced the all-in-one CreateSandboxParams with more specific options, depending on whether you’re creating from an image or a snapshot.

TypeScript

🧩 Old SDK – Single Parameter Class

// Basic creation
const sandbox = await daytona.create({
  language: "typescript",
});

// With image and callback
const sandbox = await daytona.create(
  {
    image: Image.debianSlim("3.12"),
    resources: {
      cpu: 2,
      memory: 4,
      disk: 20,
    },
  },
  { onImageBuildLogs: console.log }
);

// With language and resources
const sandbox = await daytona.create({
  language: "typescript",
  resources: {
    cpu: 2,
    memory: 4,
  },
});

🚀 New SDK – Specific Parameter Classes

// Basic creation (unchanged for simple use cases)
const sandbox = await daytona.create({
  language: "typescript",
});

// Creating from image. A dynamic snapshot will be created and used to initialize the sandbox.
const sandbox = await daytona.create(
  {
    image: Image.debianSlim("3.12"),
    resources: {
      cpu: 2,
      memory: 4,
      disk: 20,
    },
  },
  {
    onSnapshotCreateLogs: console.log, // renamed from onImageBuildLogs
  }
);

// Creating from snapshot
const sandbox = await daytona.create({
  snapshot: "my-snapshot-name",
});

Python

🧩 Old SDK – Single Parameter Class

# Basic creation
params = CreateSandboxParams(language="python")
sandbox = daytona.create(params)

# With image
params = CreateSandboxParams(
    language="python",
    image=Image.debian_slim("3.12")
)
sandbox = daytona.create(params, on_image_build_logs=print)

# With language and resources
params = CreateSandboxParams(
    language="python",
    resources=SandboxResources(
        cpu=1,
        memory=1,
        disk=3,
    ),
)
sandbox = daytona.create(params)

🚀 New SDK – Specific Parameter Classes

# Basic creation (unchanged for simple cases)
params = CreateSandboxFromSnapshotParams(language="python")
sandbox = daytona.create(params)

# Creating from image. A dynamic snapshot will be created and used to initialize the sandbox.
params = CreateSandboxFromImageParams(
    image=Image.debian_slim("3.12"),
    language="python",
    resources=Resources(
        cpu=1,
        memory=1,
        disk=3,
    ),
)
sandbox = daytona.create(params, timeout=150, on_snapshot_create_logs=print)

# Creating from snapshot
params = CreateSandboxFromSnapshotParams(
    snapshot="my-snapshot-name",
    language="python",
)
sandbox = daytona.create(params)

3. Standardized Resource Configuration

We've unified resource definitions under a single Resources object across SDKs.

This improves clarity and aligns with our declarative execution model.

4. Updated Callback Names

To reflect the shift to snapshots:

5. New Snapshot Service

You can now manage snapshots directly via a dedicated SDK interface.

TypeScript

// Access snapshot operations
await daytona.snapshot.create(params);
await daytona.snapshot.list();
await daytona.snapshot.get(snapshotName);
await daytona.snapshot.delete(snapshot);

Python

# Access snapshot operations
daytona.snapshot.create(params)
daytona.snapshot.list()
daytona.snapshot.get(snapshot_name)
daytona.snapshot.delete(snapshot)

6. Removed SandboxTargetRegion Enum

Target region has to be specified using a simple string value instead of an enum. Here’s how the change looks in practice:

TypeScript

Before:

const daytona: Daytona = new Daytona({
    target: SandboxTargetRegion.US
});

After:

const daytona: Daytona = new Daytona({
    target: "us"
});

Python

Before:

config = DaytonaConfig(
    target=SandboxTargetRegion.EU
)

daytona = Daytona(config)

After:

config = DaytonaConfig(
    target="eu"
)

daytona = Daytona(config)

7. Reduced Verbosity of Method for Retrieving a Single Sandbox

A more concise get method is now available on the Daytona object. Here’s how the change looks in practice:

TypeScript

Before:

// Get sandbox by id
const sandbox = daytona.getCurrentSandbox(id)

After:

// Get sandbox by id
const sandbox = daytona.get(id)

Python

Before:

# Get sandbox by id
sandbox = daytona.get_current_sandbox(id)

After:

# Get sandbox by id
sandbox = daytona.get(id)

8. Removed Deprecated Aliases for Sandbox Methods

Using deprecated workspace methods is no longer supported. Here’s how the change looks in practice:

TypeScript

Before:

// Get workspace by id
const workspace = daytona.getCurrentWorkspace(id)

// Get the root directory path
const dir = workspace.getWorkspaceRootDir()

// Search for all symbols containing "TODO"
const lsp = await workspace.createLspServer('typescript', 'workspace/project')
const symbols = await lsp.workspaceSymbols('TODO');

// Convert an API workspace instance to a WorkspaceInfo object
const info = Workspace.toWorkspaceInfo(apiWorkspace)

After:

// Get sandbox by id
const sandbox = daytona.get(id)

// Get the root directory path
const dir = sandbox.getUserRootDir()

// Search for all symbols containing "TODO"
const lsp = await sandbox.createLspServer('typescript', 'workspace/project')
const symbols = await lsp.sandboxSymbols('TODO');

// Convert an API sandbox instance to a SandboxInfo object
const info = Sandbox.toSandboxInfo(apiSandbox)

Python

Before:

# Get workspace by id
workspace = daytona.get_current_workspace(id)

# Get the root directory path
dir = workspace.get_workspace_root_dir()

# Search for all symbols containing "TODO"
lsp = workspace.create_lsp_server("python", "workspace/project")
symbols = lsp.workspace_symbols("TODO")

# Wait for workspace to reach "started" state
workspace.wait_for_workspace_start()

# Wait for workspace to reach "stopped" state
workspace.wait_for_workspace_stop()

After:

# Get sandbox by id
sandbox = daytona.get(id)

# Get the root directory path
sandbox.get_user_root_dir()

# Search for all symbols containing "TODO"
lsp = sandbox.create_lsp_server("python", "workspace/project")
symbols = lsp.sandbox_symbols("TODO")

# Wait for sandbox to reach "started" state
sandbox.wait_for_sandbox_start()

# Wait for sandbox to reach "stopped" state
sandbox.wait_for_sandox_stop()

9. Flattened Sandbox Instance Information

Sandbox details are now available only as top-level properties. Here’s how the change looks in practice:

TypeScript

Before:

const state = sandbox.instance.state
const autoStopInterval = sandbox.instance.autoStopInterval
const domain = sandbox.instance.info?.nodeDomain

After:

const state = sandbox.state;
const autoStopInterval = sandbox.autoStopInterval
const domain = sandbox.runnerDomain

Python

Before:

state = sandbox.instance.state
auto_stop_interval = sandbox.instance.auto_stop_interval
domain = sandbox.instance.info.node_domain

After:

state = sandbox.state
auto_stop_interval = sandbox.auto_stop_interval
domain = sandbox.runner_domain

10. Removed Legacy Sandbox Properties

Name and class are no longer present on the Sandbox object. Here’s how the change looks in practice:

TypeScript

Before:

// Valid
const sandboxName = sandbox.instance.name
const sandboxClass = sandbox.instance.info?.class

After:

// Invalid
const sandboxName = sandbox.name;
const sandboxClass = sandbox.class

Python

Before:

# Valid
name = workspace.instance.name
class_name = workspace.instance.info.class_name

After:

# Invalid
name = workspace.name
class_name = workspace.class_name

11. Improved Functionality for Refreshing Sandbox Information

The new method updates the Sandbox object properties directly. Here’s how the change looks in practice for some of the Sandbox properties:

TypeScript

Before:

// Get up-to-date sandbox info
const info = await sandbox.info()

After:

// Update sandbox with up-to-date info
await sandbox.refreshData()

Python

Before:

# Get up-to-date sandbox info
info = sandbox.info()

After:

# Update sandbox with up-to-date info
sandbox.refresh_data()

12. Removed Deprecated Method for Sandbox Removal in the TypeScript SDK

Using daytona.remove(sandbox) is no longer supported. Here’s how the change looks in practice:

TypeScript

Before:

// Deprecated
await daytona.remove(sandbox)

After:

// Option 1
await sandbox.delete()

// Option 2
await daytona.delete(sandbox)

✅ Migration Checklist

For TypeScript Users

• Replace all daytona.createImage() calls with daytona.snapshot.create()

• Use CreateSandboxFromImageParams or CreateSandboxFromSnapshotParams when creating sandboxes

• Replace all instances of SandboxResources with Resources

• Rename onImageBuildLogs callbacks to onSnapshotCreateLogs

• Replace SandboxTargetRegion enum with plain string values (e.g., "us", "eu")

• Replace retrieving a single Sandbox using daytona.getCurrentSandbox(id) to daytona.get(id)

• Replace deprecated daytona.getCurrentWorkspace(id) with daytona.get(id)

• Replace deprecated workspace.getWorkspaceRootDir() with sandbox.getUserRootDir()

• Replace deprecated lspServer.workspaceSymbols(query) with lspServer.sandboxSymbols(query)

• Replace deprecated Workspace.toWorkspaceInfo(apiWorkspace) with Sandbox.toSandboxInfo(apiSandbox)

• Update reading Sandbox details to use top-level properties instead of reading from sandbox.instance

• Remove references to legacy sandbox properties (name, class)

• Replace using sandbox.info() to get up-to-date Sandbox info with sandbox.refreshData() to update the Sandbox properties directly

• Replace using daytona.remove(sandbox) with sandbox.delete() or daytona.delete(sandbox)

For Python Users

• Replace all daytona.create_image() calls with daytona.snapshot.create()

• Import and use: CreateSnapshotParams, CreateSandboxFromImageParams, CreateSandboxFromSnapshotParams, and Resources

• Replace all usage of CreateSandboxParams with the appropriate class (CreateSandboxFromImageParams or CreateSandboxFromSnapshotParams)

• Replace all usage of SandboxResources with Resources

• Rename on_image_build_logs callbacks to on_snapshot_create_logs

• Replace SandboxTargetRegion enum with plain string values (e.g., "us", "eu")

• Replace retrieving a single Sandbox using daytona.get_current_sandbox(id) to daytona.get(id)

• Replace deprecated daytona.get_current_workspace(id) with daytona.get(id)

• Replace deprecated workspace.get_workspace_root_dir() with sandbox.get_user_root_dir()

• Replace deprecated lsp_server.workspace_symbols(query) with lsp_server.sandbox_symbols(query)

• Replace using deprecated methods workspace.wait_for_workspace_start() and workspace.wait_for_workspace_stop() with sandbox.wait_for_sandbox_start() and sandbox.wait_for_sandbox_stop()

• Update reading Sandbox details to use top-level properties instead of reading from sandbox.instance

• Remove references to legacy sandbox properties (name, class_name)

• Replace using sandbox.info() to get up-to-date Sandbox info with sandbox.refresh_data() to update the Sandbox properties directly

Final Notes

This release unlocks a more powerful and flexible infrastructure model across all SDKs.

If you're using Cursor, you can find an example here that you can add to your Project Rules to help with the migration.

If you need help migrating or want to discuss your use case, reach out via:

• In-app support widget

• Slack

• Email: support@daytona.io

We’re excited to see what you build with it.

📚 You can also find full API and SDK reference at daytona.io/docs.