Upgrade to Daytona v2
Daytona v2 is the next version of the Daytona platform.
Daytona v0 is the current platform, with SDK and CLI releases numbered 0.x. Daytona v2 has its own API, dashboard, and resource model, with SDK and CLI releases numbered 2.x.
Upgrading the SDK and moving a workload to Daytona v2 are separate steps. SDK 2.x calls both platforms from the same client, through a separate namespace for each platform. Installing SDK 2.x does not move existing sandboxes or change which platform serves them. Move workloads to Daytona v2 call by call, on your own schedule.
Your account, organization, members, API keys, and billing carry over to Daytona v2. Daytona syncs API keys and container registries between the platforms, and registers container snapshots as Daytona v2 images. Sandboxes stay on Daytona v0 until you import them.
| Term | Daytona v0 | Daytona v2 |
|---|---|---|
| SDK and CLI versions | 0.x | 2.x |
| SDK namespace | daytona.v0 | daytona.v2 |
| API | https://app.daytona.io/api | https://api.daytona.com |
| Dashboard | app.daytona.io | app.daytona.com |
| Documentation | daytona.io/docs | daytona.com/docs |
1. Upgrade the SDK
Section titled “1. Upgrade the SDK”SDK 2.x is available for Python and TypeScript. It targets Daytona Cloud: it has no API URL setting, and it calls the Daytona Cloud APIs of both platforms. Applications that use a custom API URL stay on SDK 0.x. The Go, Ruby, and Java SDKs stay on 0.x and call Daytona v0.
If you use the upgrade tool, run it before you install SDK 2.x.
The Python SDK includes the Daytona v0 namespace in an optional extra. Install the extra when your code calls Daytona v0, or both platforms in the same project. Without the extra, importing the Daytona v0 namespace raises an error that names the extra.
# Daytona v0 code, or Daytona v0 and Daytona v2 in the same projectpip install "daytona[v0-sdk]==2.0.0a13"
# Daytona v2 code onlypip install "daytona==2.0.0a13"The TypeScript SDK includes the Daytona v0 namespace in the package. No extra install is required. Projects that depend on the older package name replace it with the package of SDK 2.x. The TypeScript SDK requires Node.js 22.15 or later.
npm install @daytona/sdk@2.0.0-alpha.13| Package | SDK 2.x |
|---|---|
@daytona/sdk | The package of SDK 2.x. |
@daytonaio/sdk | Replace it with @daytona/sdk. |
1.1 Upgrade tool
Section titled “1.1 Upgrade tool”The upgrade tool upgrades a project from SDK 0.x to SDK 2.x and keeps it on Daytona v0. It updates the Daytona dependency, adds the Daytona v0 namespace to client calls, and moves the imports of Daytona v0 resource types and errors to the Daytona v0 module. It does not move calls to Daytona v2 and does not install packages. Each language has its own tool: the Python tool changes only Python code, and the TypeScript tool changes only TypeScript and JavaScript code.
The tool changes only the calls it can prove belong to the Daytona client. It marks a call it cannot prove, but can link to Daytona, with a FIXME(daytona-upgrade) comment and lists it as a manual item in its output. Calls with no link to Daytona get no comment, so review the changes and run your tests before you deploy them. The tool refuses to run when the project sets a custom API URL in its code, environment files, or deployment files.
The tool runs from the project directory and requires a clean Git working tree. Run it before you install SDK 2.x: the TypeScript tool uses the installed SDK 0.x types to find client calls. The Python tool requires Python 3.9 or later, and the TypeScript tool requires Node.js 20 or later.
Each release of the tool has the same version as an SDK release and upgrades the project to that SDK release. While SDK 2.x is in alpha, the tool pins the exact SDK version in the dependency file. Run the tool by its exact version: without a version, the command runs an older release of the tool that writes a version range matching no SDK release.
# Preview the changesuvx daytona-upgrade@2.0.0a13 --dry
# Upgrade the projectuvx daytona-upgrade@2.0.0a13 . --yesThe tool sets the dependency to daytona[v0-sdk]==2.0.0a13. SDK 2.x requires Python 3.10 or later, and the tool reports a project that supports earlier versions.
# Preview the changesnpx @daytona/upgrade@2.0.0-alpha.13 --dry
# Upgrade the projectnpx @daytona/upgrade@2.0.0-alpha.13 . --yesThe tool sets the dependency to @daytona/sdk@2.0.0-alpha.13 and replaces @daytonaio/sdk.
SDK 2.x runs one 0.x release as the Daytona v0 namespace. SDK 2.0.0a13 (2.0.0-alpha.13 in TypeScript) runs 0.x release 0.230.0. The tool reads the 0.x version of the project from its lockfile, or from the dependency file, and compares it with that release:
| Installed 0.x version | Result |
|---|---|
| The same release | No report. |
| An older release, or a newer patch release | A warning. Calls on the Daytona v0 namespace run the 0.x release of SDK 2.x. Review the 0.x changes between the two releases, then run your tests. |
| A newer minor release | The tool refuses to run. The 0.x release of SDK 2.x lacks the newer 0.x methods. Use a later release of the tool, or pass --allow-newer-v0. |
| Unknown | A warning. |
| Option | Description |
|---|---|
[path] | The project directory. Defaults to the current directory. The Python tool also accepts a single file. |
--dry | Print the changes as a diff. Writes nothing. |
--print | Print the changed files. Writes nothing. |
--json | Print the report as JSON. |
--yes | Skip the confirmation prompt. |
--force | Run on a Git working tree with uncommitted changes. |
--drop-api-url | Accept API URLs the tool cannot verify, such as URLs read from variables, as Daytona Cloud URLs. |
--strict | Exit with code 1 when manual items remain. |
--allow-newer-v0 | Upgrade a project on a newer 0.x minor release than the 0.x release of SDK 2.x, with a warning. |
--suggest-v2 | Add comments with the Daytona v2 equivalent of each call. See move workload. |
--remove-suggestions | Remove the comments added by --suggest-v2. |
Analysis covers the whole project and takes longer on large projects. In a large repository, run the tool on the directories that use Daytona, with their tests and dependency file, instead of the repository root.
2. Update your code
Section titled “2. Update your code”SDK 2.x moves every resource operation into a version namespace. The client and its configuration are still imported from the package root. Resource types and errors for Daytona v0, such as sandboxes, sandbox create parameters, and the not found error, move to the Daytona v0 module. The upgrade tool makes these changes where it can. Resolve each FIXME(daytona-upgrade) comment and each manual item it reported, and apply the same rules to the calls it did not change.
Add the Daytona v0 namespace to every call on the client. The client has no resource methods of its own in SDK 2.x: a call without a namespace fails. The application keeps calling Daytona v0, and code that already uses the namespace needs no change.
| Item | Python | TypeScript |
|---|---|---|
| Client and configuration | daytona | @daytona/sdk |
| Errors shared by both platforms | daytona | @daytona/sdk |
| Daytona v0 resource types and errors | daytona.v0 | @daytona/sdk/v0 |
| Daytona v2 resource types and errors | daytona.v2 | @daytona/sdk/v2 |
| Daytona v0 calls | daytona.v0.create() | daytona.v0.create() |
| Daytona v2 calls | daytona.v2.create() | daytona.v2.create() |
# Before (SDK 0.x)from daytona import CreateSandboxFromSnapshotParams, Daytona, Sandbox
daytona = Daytona()
sandbox: Sandbox = daytona.create(CreateSandboxFromSnapshotParams(language="python"))snapshots = daytona.snapshot.list()# After (SDK 2.x)from daytona import Daytonafrom daytona.v0 import CreateSandboxFromSnapshotParams, Sandbox
daytona = Daytona()
sandbox: Sandbox = daytona.v0.create(CreateSandboxFromSnapshotParams(language="python"))snapshots = daytona.v0.snapshot.list()// Before (SDK 0.x)import { Daytona, Sandbox } from '@daytona/sdk'
const daytona = new Daytona()
const sandbox: Sandbox = await daytona.create({ language: 'typescript' })const snapshots = await daytona.snapshot.list()// After (SDK 2.x)import { Daytona } from '@daytona/sdk'import { Sandbox } from '@daytona/sdk/v0'
const daytona = new Daytona()
const sandbox: Sandbox = await daytona.v0.create({ language: 'typescript' })const snapshots = await daytona.v0.snapshot.list()Configuration
Section titled “Configuration”One API key serves both namespaces. The client reads it from the environment or from the client configuration. The following table lists the API key and the settings that change in SDK 2.x:
| Setting | SDK 2.x |
|---|---|
DAYTONA_API_KEY | Unchanged. The same key serves .v0 and .v2. |
api_url, toolbox_url | Removed. The client configuration raises an error when either is set. Remove a setting that names the default Daytona v0 API URL. Applications that use a custom API URL stay on SDK 0.x. |
target | Deprecated. It applies to .v0 only. Pass target to each Daytona v0 sandbox create, or region_id (regionId in TypeScript) to each Daytona v0 snapshot create. |
DAYTONA_API_URL | Ignored by .v0. When set, it overrides the Daytona v2 API URL. Unset a DAYTONA_API_URL left from SDK 0.x, or .v2 calls the Daytona v0 API. |
DAYTONA_V2_API_URL | Ignored by .v0. When set, it overrides the Daytona v2 API URL and takes precedence over DAYTONA_API_URL. |
.env files | Read by .v0. .v2 reads only the environment of the process. |
| Missing API key | Reported on the first .v0 access, not by the client constructor. Code that catches a missing key around the constructor must access .v0 inside the same try block. |
DaytonaConfig (Python) | A dataclass, not a Pydantic model. Replace model_dump() with dataclasses.asdict(), model_copy() with dataclasses.replace(), and model_validate() with DaytonaConfig(**data). |
Errors
Section titled “Errors”Every error that the Daytona v0 namespace raises is a Daytona v0 error class. The Daytona v0 error classes keep the constructor and fields of SDK 0.x, so code that catches, raises, or subclasses errors works as before when it imports them from the Daytona v0 module.
The errors at the package root are shared by both namespaces. For example, the not found error at the package root catches a not found error from both platforms. A root error class takes only a message when you construct it, and its instances carry none of the fields of SDK 0.x. Import errors from the package root when you move calls to Daytona v2, and import errors specific to one platform from the module of that platform.
Verify the upgrade
Section titled “Verify the upgrade”Run the type checker and tests of the project. A call on the client without a namespace fails in SDK 2.x, so a test that reaches it reports the call. If no test calls Daytona, run a short script that creates a Daytona v0 sandbox, runs a command in it, and deletes it.
from daytona import Daytona
daytona = Daytona()
sandbox = daytona.v0.create()response = sandbox.process.exec("echo 'Daytona v0'")print(response.result)sandbox.delete()import { Daytona } from '@daytona/sdk'
const daytona = new Daytona()
const sandbox = await daytona.v0.create()const response = await sandbox.process.executeCommand("echo 'Daytona v0'")console.log(response.result)await sandbox.delete()3. Move workload
Section titled “3. Move workload”Move a workload to Daytona v2 by moving its calls from the Daytona v0 namespace to the Daytona v2 namespace. Both namespaces work in the same application with the same client, so you can move one workflow at a time. A sandbox created on Daytona v0 is reachable only through the Daytona v0 namespace, and a sandbox created on Daytona v2 only through the Daytona v2 namespace.
from daytona import Daytona
daytona = Daytona()
v0_sandbox = daytona.v0.create() # Daytona v0v2_sandbox = daytona.v2.create("{imageName}") # Daytona v2
for sandbox in daytona.v0.list(): # Daytona v0 sandboxes only print(sandbox.id)import { Daytona } from '@daytona/sdk'
const daytona = new Daytona()
const v0Sandbox = await daytona.v0.create() // Daytona v0const v2Sandbox = await daytona.v2.create('{imageName}') // Daytona v2
for await (const sandbox of daytona.v0.list()) { // Daytona v0 sandboxes only console.log(sandbox.id)}The upgrade tool adds a comment above each Daytona v0 call with its Daytona v2 equivalent, the differences in behavior, and the other calls in the same sandbox workflow. Workflows that stop, start, pause, or archive a sandbox are marked to stay on Daytona v0, because sandbox lifecycle differs on Daytona v2. The comments start with daytona-v2:. The tool does not change calls or dependencies in this mode, and running it again replaces the comments. The migration reference lists the Daytona v2 equivalent of every Daytona v0 call.
# Add the commentsuvx daytona-upgrade@2.0.0a13 --suggest-v2
# Remove the commentsuvx daytona-upgrade@2.0.0a13 --remove-suggestions# Add the commentsnpx @daytona/upgrade@2.0.0-alpha.13 --suggest-v2
# Remove the commentsnpx @daytona/upgrade@2.0.0-alpha.13 --remove-suggestionsRemoving the comments deletes every comment line that starts with daytona-v2:, including comments you wrote. Do not use this prefix for your own comments.
Daytona v2 has its own resource model. The following concepts differ between the platforms:
| Daytona v0 | Daytona v2 |
|---|---|
| Snapshot: an image that sandboxes are created from | Image. A Daytona v2 snapshot saves the memory and disk of a running sandbox. |
| Organization | Organization with projects. Resources belong to a project. |
| Sandbox | Sandbox: a virtual machine with its own kernel. See the sandbox lifecycle of Daytona v2. |
| Volume | Volume. Volumes do not carry over: volumes on Daytona v0 stay on Daytona v0. |
The Daytona v2 CLI calls Daytona v2 only. It installs as daytona, and the Daytona v0 CLI installs as daytona-v0, so both CLIs install side by side. Both CLIs keep their configuration in separate files, so neither overwrites the other. Keep the Daytona v0 CLI for Daytona v0 sandboxes until you no longer need it. See the CLI reference of Daytona v2.
What carries over
Section titled “What carries over”Daytona v2 uses the same account and organization as Daytona v0, with the same organization ID. Resources from Daytona v0 belong to the default project of the organization on Daytona v2. Only the default project syncs with Daytona v0. Other Daytona v2 projects are Daytona v2 only.
| Resource | On Daytona v2 |
|---|---|
| Account and organization | The same account and organization, including personal organizations. |
| Members | Organization members carry over. Owners become admins, and members stay members. |
| API keys | The same API key works on both platforms. Keys sync in both directions through the default project. |
| Container registries | Organization registries sync in both directions through the default project. |
| Billing | The same balance, credits, payment method, and invoice. Usage on both platforms is billed together. |
| Snapshots | Container snapshots appear as images in the default project. |
| Sandboxes | Sandboxes stay on Daytona v0. Import archived container sandboxes as persistent sandboxes. |
| Volumes | Volumes stay on Daytona v0. |
| Secrets and webhooks | Secrets and webhooks stay on Daytona v0. |
| Audit logs | The audit log of Daytona v0 stays on Daytona v0. |
API keys
Section titled “API keys”API keys sync between Daytona v0 and the default project on Daytona v2. A synced key has the same secret on both platforms, so the same API key works for both namespaces. A key created on one platform works on the other shortly after it is created. Revoking a key on either platform revokes it on both.
Keys created in the default project on Daytona v2 sync to Daytona v0, unless the key is turned off for Daytona v0 when it is created or later. Daytona v0 has no read permissions, so the Daytona v0 copy of a key can read every sandbox, snapshot, and registry of the organization, whatever the permissions of the key. Keys imported from Daytona v0 always sync and cannot be turned off. Keys created in other Daytona v2 projects, service account keys, organization keys, and the default key of the dashboard are Daytona v2 only.
When a key name already exists on the other platform, the synced key is renamed with a suffix:
| Synced from | Synced to | Suffix |
|---|---|---|
| Daytona v0 | Daytona v2 | (v1), then (v1 {first 8 characters of the key hash}) |
| Daytona v2 | Daytona v0 | (v2), then (v2 {first 8 characters of the key hash}) |
Each Daytona v0 permission maps to its Daytona v2 permission. A key synced from Daytona v0 also gets the read permissions for sandboxes, images, and registries. On Daytona v2, the role of the key owner still limits what the key can do.
| Daytona v0 | Daytona v2 |
|---|---|
write:sandboxes, delete:sandboxes | write:sandboxes, delete:sandboxes |
write:snapshots, delete:snapshots | write:images, delete:images |
write:registries, delete:registries | write:registries, delete:registries |
read:volumes, write:volumes, delete:volumes | read:volumes, write:volumes, delete:volumes |
manage:secrets | read:secrets, write:secrets, delete:secrets |
read:limits, read:runners | read:limits, read:runners |
manage:api_keys, read:billing, manage:billing, manage:sso, read:audit_logs, write:regions, delete:regions, write:runners, delete:runners | No equivalent. Not carried over. |
Container registries
Section titled “Container registries”Organization container registries sync between Daytona v0 and the default project on Daytona v2, in both directions. Registries sync by host: a synced registry keeps its host and credentials, and the registry name, URL path, and project of Daytona v0 do not carry over. Daytona v0 registries on the same host become one Daytona v2 registry. Amazon ECR registries that use a role carry over without changes in AWS.
Billing
Section titled “Billing”Billing continues on Daytona v2 with the same balance, credits, payment method, and invoice history. Usage on Daytona v0 and Daytona v2 is billed together, on one invoice.
Snapshots
Section titled “Snapshots”Active container snapshots on Daytona v0 appear as images in the default project on Daytona v2. Daytona-provided snapshots, Linux VM snapshots, and Windows snapshots do not carry over. Daytona registers the image without copying it, in an older image format. The image converts to the current format on its first Linux sandbox create, so the first sandbox from the image waits in the queued state while the conversion runs. GPU sandboxes, functions, and builds that use the image as their source refuse it until it is converted. Windows sandboxes cannot use the image.
Convert the image ahead of time to remove the wait from the first create. The request requires the permission to write images.
curl 'https://api.daytona.com/images/{imageId}/convert' \ --request POST \ --header 'Authorization: Bearer YOUR_API_KEY'The image keeps the snapshot name, with the following changes:
| Snapshot name | Image name |
|---|---|
Characters other than letters, digits, ., _, and - | Replaced with -. |
| Name already taken on Daytona v2 | {name}-v1, then {name}-v1-{first 8 characters of the snapshot ID} |
The snapshot on Daytona v0 stays the source of the image: an image deleted on Daytona v2 is registered again while the snapshot is active. Deleting the snapshot on Daytona v0 removes the image, unless the image is converted or in use. A converted image stays on Daytona v2.
Import sandboxes
Section titled “Import sandboxes”Import a sandbox to copy it from Daytona v0 to Daytona v2. The import creates a persistent sandbox in the default project from the latest backup of the Daytona v0 sandbox. The Daytona v0 sandbox keeps working and gets a label with the ID of the Daytona v2 sandbox. The two sandboxes are independent: changes to one do not affect the other.
A sandbox can be imported when it is an archived container sandbox with a completed backup. Running and stopped sandboxes must be archived on Daytona v0 first. Linux VM, Windows, and GPU sandboxes cannot be imported. The Daytona v2 dashboard lists Daytona v0 sandboxes and imports them from the Sandboxes page, when the default project is selected.
from daytona import Daytona
daytona = Daytona()
sandbox = daytona.v0.get("{sandboxId}")sandbox.stop()sandbox.archive()import { Daytona } from '@daytona/sdk'
const daytona = new Daytona()
const sandbox = await daytona.v0.get('{sandboxId}')await sandbox.stop()await sandbox.archive()daytona-v0 stop {sandboxId}daytona-v0 archive {sandboxId}The CLI commands are part of the Daytona v0 CLI.
The import requests require an API key of the default project with the following permissions:
| Request | Permission |
|---|---|
| List Daytona v0 sandboxes | read:sandboxes |
| Import a sandbox | write:sandboxes |
List Daytona v0 sandboxes
Section titled “List Daytona v0 sandboxes”List the sandboxes of the organization on Daytona v0 to see which ones can be imported. Each sandbox shows whether it can be imported now and, when it cannot, the reason. The list is paginated: pass the cursor from the response to get the next page, until the response has no cursor.
curl 'https://api.daytona.com/migration/v0/sandboxes' \ --header 'Authorization: Bearer YOUR_API_KEY'| Field | Description |
|---|---|
cursor | Query parameter. The next_cursor of the previous page. |
next_cursor | Response field. The cursor of the next page, or null on the last page. |
not_container | Reason. The sandbox is a Linux VM or Windows sandbox. |
not_archived | Reason. The sandbox is not archived. |
backup_not_completed | Reason. The backup of the sandbox has not completed. |
backup_registry_unavailable | Reason. Daytona v2 cannot read the registry of the backup. |
gpu_not_supported | Reason. The sandbox is a GPU sandbox. |
Import a sandbox
Section titled “Import a sandbox”Import a sandbox by its Daytona v0 ID. The new sandbox starts in the queued state while its image is imported from the backup. Importing the same sandbox again returns the existing import, unless the request forces a new import.
curl 'https://api.daytona.com/migration/v0/sandboxes/{v0SandboxId}/import' \ --request POST \ --header 'Authorization: Bearer YOUR_API_KEY'The response contains the ID of the Daytona v2 sandbox, the settings that could not be imported, and the names of environment variables that were sandbox secrets on Daytona v0. Set those variables on the imported sandbox.
| Field | Description |
|---|---|
force | Request body field. true creates a new import when one already exists. |
sandbox_id | Response field. The ID of the Daytona v2 sandbox. |
warnings | Response field. The settings that could not be imported. |
secret_env_vars | Response field. The names of environment variables that were sandbox secrets on Daytona v0. |
What an import keeps
Section titled “What an import keeps”| Setting | On the imported sandbox |
|---|---|
| Filesystem | The filesystem of the latest backup. |
| Name | Kept when the name is valid on Daytona v2. |
| Labels | Kept. Invalid labels are dropped and reported in warnings. |
| Environment variables | Kept. Invalid and reserved names are dropped and reported in warnings. |
| CPU, memory, and disk | Kept. Values are rounded up to whole units, and values above the Daytona v2 maximums are capped. |
| OS user | Kept. |
| Network settings | Blocking all traffic and the allow list map to the network policy of Daytona v2. |
| Auto-stop interval | Becomes the idle timeout. An auto-stop interval of 0 sets no idle timeout. |
| Region | The default region of the project, or of the organization, on Daytona v2. |
| Sandbox secrets | Not imported. Their names are listed in secret_env_vars. |
| Auto-archive, auto-delete, and auto-pause intervals | Not imported. |
| Public access | Not imported. |
| Volumes | Not imported. |
| Sandbox ID and preview URLs | Not kept. The imported sandbox has a new ID and new preview URLs. |
| Memory state | Not kept. The sandbox was archived before the import. |
| Daytona v0 sandbox | Kept and labeled daytona.io/migrated-to with the ID of the imported sandbox. |