feat(sdk): add v1 client namespace and per-create target by MDzaja · Pull Request #349 · daytona/clients

MDzaja · 2026-10-09T15:51:00Z

Description

Adds a versioned v1 alias of the current client API to every SDK, for code that wants to pin the API version explicitly. v1 returns the same client (or re-exports the same module), so existing code behaves exactly as before.

SDK	Versioned alias
Python	`Daytona().v1` / `AsyncDaytona().v1` (typed `Self`); `from daytona.v1 import ...` re-exports the full public API, resolved lazily like the root package
TypeScript	`daytona.v1` getter (returns `this`); `@daytona/sdk/v1` subpath export for ESM and CJS, plus a `v1/package.json` fallback for `moduleResolution: node`
Go	`client.V1()` method returning the same `*Client` (a method, not a field, so it always refers to the receiver and cannot be reassigned)
Ruby	`daytona.v1` returns `self`; `Daytona::V1` is the `Daytona` module itself (`Daytona::V1::Daytona`, `Daytona::V1::Config`, ...)
Java	`daytona.v1()` returns `this`

Also adds an optional target to the sandbox create params in every SDK (CreateSandboxFromSnapshotParams / CreateSandboxFromImageParams, Go SandboxBaseParams.Target, Java CreateSandboxParams#setTarget). It overrides the client-level target for that call; when omitted, behavior is unchanged.

The client-level target config and the DAYTONA_TARGET environment variable are deprecated, using each language's native mechanism. Both keep working:

Python: DeprecationWarning when either is set, plus a docstring note
TypeScript: @deprecated on DaytonaConfig.target, plus a console.warn when either is set (matching the existing DAYTONA_SERVER_URL deprecation)
Go: // Deprecated: on DaytonaConfig.Target; DAYTONA_TARGET documented as deprecated
Ruby: warn (with uplevel) when either is set, plus YARD @deprecated
Java: @Deprecated on DaytonaConfig#getTarget and DaytonaConfig.Builder#target

The client-level target still seeds the default snapshot region where an SDK already did that. The deprecation messages point to region_id / regionId on snapshot create for that case.

Verification (run locally in the Nix dev shells):

Python: pylint clean, basedpyright 0 errors / 0 warnings, pytest 825 passed
TypeScript: ESLint 0 errors, Prettier clean, jest 455 passed (21 suites), nx build + attw --pack green for @daytona/sdk/v1 in node10, node16 (CJS and ESM) and bundler. The packed tarball was also installed into a scratch project, where require('@daytona/sdk/v1'), import '@daytona/sdk/v1' and tsc (node10/node16/bundler) all resolve to the same classes.
Go: golangci-lint 0 issues, go test -race ./... 315 top-level tests passed (485 including subtests), examples/go builds
Ruby: rspec 578 examples, 0 failures. RuboCop reports 204 offenses both on main and on this branch, so this change adds none.
Java: ./gradlew build green, 381 tests passed

Documentation

This change requires a documentation update
I have made corresponding changes to the documentation

SDK READMEs gain "Create a sandbox in a specific region" and "Pin the API version" sections, config examples drop the deprecated target, and the region examples (Python sync and async, TypeScript, Java) now pass target per create. SDK reference docs under artifacts/sdk-docs/ are regenerated; the Go docs keep only the hunks this change produces, not unrelated generator churn.

Related Issue(s)

None.

Notes

No version bumps, release workflow changes or CLI changes.
daytona.v1 / @daytona/sdk/v1 are excluded from the generated reference docs so the API is not documented twice.

Summary by cubic

Adds a versioned v1 alias of the current client API to every SDK, so code can explicitly pin the API version without changing behavior. v1 returns the same client (Go client.V1(), Java daytona.v1(), daytona.v1 elsewhere) or re-exports the same module (daytona.v1, @daytona/sdk/v1, Daytona::V1).

Adds an optional target to sandbox create params that overrides the client-level target for that call, falling back through the per-create target, the client-level target, then DAYTONA_TARGET, before the organization's default region. The client-level config and DAYTONA_TARGET are deprecated but still work, emitting a deprecation warning via each language's native mechanism. Go Create now also accepts pointer snapshot/image params.

Migration

Set target on each sandbox create call instead of the client-level config.
Snapshot creates should pass region_id / regionId instead of relying on the deprecated client target for the default region.

^{Written for commit 3116d95. Summary will update on new commits.}

Add a versioned `v1` alias of the current client API to every SDK, for code that wants to pin the API version explicitly. The alias returns the same client and changes no behavior: - Python: `daytona.v1` module re-exporting the public API, plus a `v1` property on `Daytona` and `AsyncDaytona` - TypeScript: `@daytona/sdk/v1` subpath export (ESM, CJS and a node10 fallback) plus a `daytona.v1` getter - Go: `Client.V1()` - Ruby: `Daytona::Daytona#v1` and the `Daytona::V1` module alias - Java: `Daytona.v1()` Add an optional `target` to the sandbox create params in every SDK. It overrides the client-level target for that call. Deprecate the client-level `target` config and the `DAYTONA_TARGET` environment variable with each language's native mechanism; both keep working. Signed-off-by: MDzaja <mirkodzaja0@gmail.com>

vidoc-agent · 2026-10-09T15:51:05Z

Vidoc security review

Tip

Good to merge — no security issues found. Reviewed 50 changed files.

💬 Have questions? Tag @vidoc in a comment and I'll answer.

Signed-off-by: MDzaja <mirkodzaja0@gmail.com>

MDzaja · 2026-10-09T16:23:27Z

@cubic-dev-ai review this PR

cubic-dev-ai · 2026-10-09T16:23:32Z

@cubic-dev-ai review this PR

@MDzaja I have started the AI code review. It will take a few minutes to complete.

cubic-dev-ai

1 issue found across 50 files

Prompt for AI agents (unresolved issues)


Check if these issues are valid — if so, understand the root cause of each and fix them. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="artifacts/sdk-docs/typescript-sdk/daytona.mdx">

<violation number="1" location="artifacts/sdk-docs/typescript-sdk/daytona.mdx:542">
P2: This setting also seeds the default region for snapshot creation, but the migration advice only covers Sandbox creation. Mention `regionId` on Snapshot create params so callers preserve snapshot placement when replacing the deprecated setting.</violation>
</file>

_{Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic}

Accept pointer params in Go Create, warn on the Ruby target writer, treat a blank Ruby per-create target as unset, list v1 in dir(daytona), and document the target fallback order and snapshot region replacement. Signed-off-by: MDzaja <mirkodzaja0@gmail.com>

MDzaja · 2026-10-09T16:37:33Z

@cubic-dev-ai review this PR

cubic-dev-ai · 2026-10-09T16:37:39Z

@cubic-dev-ai review this PR

@MDzaja I have started the AI code review. It will take a few minutes to complete.

cubic-dev-ai

All reported issues were addressed across 50 files

_{Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic}

Signed-off-by: MDzaja <mirkodzaja0@gmail.com>

MDzaja · 2026-10-09T16:46:23Z

@cubic-dev-ai review this PR

cubic-dev-ai · 2026-10-09T16:46:28Z

@cubic-dev-ai review this PR

@MDzaja I have started the AI code review. It will take a few minutes to complete.

cubic-dev-ai

No issues found across 50 files

_{View guided diff | Turn on auto-fix | Re-trigger cubic}

MDzaja self-assigned this Oct 9, 2026

docs(sdk-go): match generated reference docs

c91f2f5

Signed-off-by: MDzaja <mirkodzaja0@gmail.com>

cubic-dev-ai Bot reviewed Oct 9, 2026

View reviewed changes

Comment thread artifacts/sdk-docs/typescript-sdk/daytona.mdx Outdated

Comment thread sdk-python/tests/test_v1.py Outdated

Comment thread sdk-ruby/lib/daytona/config.rb Outdated

Comment thread sdk-ruby/spec/daytona/daytona_spec.rb

Comment thread sdk-ruby/spec/daytona/config_spec.rb

fix(sdk): clarify DAYTONA_TARGET deprecation source and docs rendering

3116d95

Signed-off-by: MDzaja <mirkodzaja0@gmail.com>

cubic-dev-ai Bot reviewed Oct 9, 2026

View reviewed changes

Conversation

MDzaja commented Oct 9, 2026 • edited by cubic-dev-ai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Documentation

Related Issue(s)

Notes

Summary by cubic

Uh oh!

vidoc-agent Bot commented Oct 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Vidoc security review

Uh oh!

MDzaja commented Oct 9, 2026

Uh oh!

cubic-dev-ai Bot commented Oct 9, 2026

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

MDzaja commented Oct 9, 2026

Uh oh!

cubic-dev-ai Bot commented Oct 9, 2026

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

MDzaja commented Oct 9, 2026

Uh oh!

cubic-dev-ai Bot commented Oct 9, 2026

Uh oh!

cubic-dev-ai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

MDzaja commented Oct 9, 2026 •

edited by cubic-dev-ai Bot

Loading

vidoc-agent Bot commented Oct 9, 2026 •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading