AuditScenarios

class AuditScenarios(BaseModel)

The supported audit scenarios, grouped by target type.

Attributes:

• targets List[AuditTargetScenario] = Field(description='One entry per target type, sorted by target type.')
• additional_properties Dict[str, Any] = {}

model_config

model_config = ConfigDict(populate_by_name=True, validate_assignment=True, protected_namespaces=())

AuditScenarios.to_str

def to_str() -> str

Returns the string representation of the model using alias

AuditScenarios.to_json

def to_json() -> str

Returns the JSON representation of the model using alias

AuditScenarios.from_json

@classmethod
def from_json(json_str: str) -> Optional[Self]

Create an instance of AuditScenarios from a JSON string

AuditScenarios.to_dict

def to_dict() -> Dict[str, Any]

Return the dictionary representation of the model using alias.

This has the following differences from calling pydantic's self.model_dump(by_alias=True):

• None is only added to the output dict for nullable fields that were set at model initialization. Other fields with value None are ignored.
• Fields in self.additional_properties are added to the output dict.

AuditScenarios.from_dict

@classmethod
def from_dict(obj: Optional[Dict[str, Any]]) -> Optional[Self]

Create an instance of AuditScenarios from a dict

AuditTargetScenario

class AuditTargetScenario(BaseModel)

Actions the audit log can record against one target type.

Attributes:

• actions List[StrictStr] = Field(description='Actions that can appear against this target type, sorted alphabetically.')
• target_type StrictStr = Field(description='Resource type the actions apply to — the target_type of the audit rows the query API returns.')
• additional_properties Dict[str, Any] = {}

model_config

model_config = ConfigDict(populate_by_name=True, validate_assignment=True, protected_namespaces=())

AuditTargetScenario.to_str

def to_str() -> str

Returns the string representation of the model using alias

AuditTargetScenario.to_json

def to_json() -> str

Returns the JSON representation of the model using alias

AuditTargetScenario.from_json

@classmethod
def from_json(json_str: str) -> Optional[Self]

Create an instance of AuditTargetScenario from a JSON string

AuditTargetScenario.to_dict

def to_dict() -> Dict[str, Any]

Return the dictionary representation of the model using alias.

This has the following differences from calling pydantic's self.model_dump(by_alias=True):

• None is only added to the output dict for nullable fields that were set at model initialization. Other fields with value None are ignored.
• Fields in self.additional_properties are added to the output dict.

AuditTargetScenario.from_dict

@classmethod
def from_dict(obj: Optional[Dict[str, Any]]) -> Optional[Self]

Create an instance of AuditTargetScenario from a dict

CurrentApiKey

class CurrentApiKey(BaseModel)

What an API-key caller learns about the credential it presented.

Attributes:

• created_at Optional[datetime] = None
• expires_at Optional[datetime] = Field(default=None, description='RFC 3339 expiry; null = never expires.')
• id StrictStr
• key_prefix Optional[StrictStr] = Field(default=None, description='Leading characters of the plaintext token, for recognizable display.')
• key_suffix Optional[StrictStr] = Field(default=None, description='Trailing characters of the plaintext token; null for keys minted before the suffix was recorded.')
• last_used_at Optional[datetime] = Field(default=None, description='Best-effort, flushed periodically — may lag the request that reads it.')
• name StrictStr
• org_id StrictStr
• org_name StrictStr
• project_id StrictStr
• project_name StrictStr
• project_permissions List[StrictStr] = Field(description="The key's explicit project permissions, canonical order.")
• service_account_id Optional[StrictStr] = Field(default=None, description='The owning service account, when the key was minted for one. Only the id: service_accounts is management-plane state that workload cells do not replicate, so a name would be null there and set on home.')
• additional_properties Dict[str, Any] = {}

model_config

model_config = ConfigDict(populate_by_name=True, validate_assignment=True, protected_namespaces=())

CurrentApiKey.to_str

def to_str() -> str

Returns the string representation of the model using alias

CurrentApiKey.to_json

def to_json() -> str

Returns the JSON representation of the model using alias

CurrentApiKey.from_json

@classmethod
def from_json(json_str: str) -> Optional[Self]

Create an instance of CurrentApiKey from a JSON string

CurrentApiKey.to_dict

def to_dict() -> Dict[str, Any]

Return the dictionary representation of the model using alias.

This has the following differences from calling pydantic's self.model_dump(by_alias=True):

• None is only added to the output dict for nullable fields that were set at model initialization. Other fields with value None are ignored.
• Fields in self.additional_properties are added to the output dict.

CurrentApiKey.from_dict

@classmethod
def from_dict(obj: Optional[Dict[str, Any]]) -> Optional[Self]

Create an instance of CurrentApiKey from a dict

ProjectBudget

class ProjectBudget(BaseModel)

A project's monthly spend budget and its current state.

Attributes:

• evaluated_at Optional[datetime] = Field(default=None, description='When spend was last evaluated in the current period. null until the first evaluation in the period.')
• exceeded_at Optional[datetime] = Field(default=None, description='When the project reached its budget this period. null while the project is under its budget.')
• monthly_limit_cents StrictInt = Field(description='The monthly budget, in US cents.')
• period_start date = Field(description='The first day of the current budget period (the calendar month in UTC), as YYYY-MM-DD.')
• project_id StrictStr = Field(description='The project the budget caps.')
• spent_cents Optional[StrictInt] = Field(default=None, description='Month-to-date spend at list price, in US cents, from the last evaluation in the current period. null until the first evaluation in the period.')
• stop_at Optional[datetime] = Field(default=None, description='When running sandboxes are ended: exceeded_at plus the grace period. On the first sweep after this time, running persistent sandboxes are stopped and running ephemeral sandboxes are deleted; macOS sandboxes, which run on a prepaid Mac lease, keep running. null when exceeded_at is null, and null when this time falls on or after the start of the next UTC month: the hold expires at the month boundary, so no sandbox is ended this period.')
• stop_grace_hours StrictInt = Field(description="The organization's effective grace period, in hours.")
• additional_properties Dict[str, Any] = {}

model_config

model_config = ConfigDict(populate_by_name=True, validate_assignment=True, protected_namespaces=())

ProjectBudget.to_str

def to_str() -> str

Returns the string representation of the model using alias

ProjectBudget.to_json

def to_json() -> str

Returns the JSON representation of the model using alias

ProjectBudget.from_json

@classmethod
def from_json(json_str: str) -> Optional[Self]

Create an instance of ProjectBudget from a JSON string

ProjectBudget.to_dict

def to_dict() -> Dict[str, Any]

Return the dictionary representation of the model using alias.

This has the following differences from calling pydantic's self.model_dump(by_alias=True):

• None is only added to the output dict for nullable fields that were set at model initialization. Other fields with value None are ignored.
• Fields in self.additional_properties are added to the output dict.

ProjectBudget.from_dict

@classmethod
def from_dict(obj: Optional[Dict[str, Any]]) -> Optional[Self]

Create an instance of ProjectBudget from a dict

Daytona

class Daytona()

Top-level synchronous client.

Daytona.__init__

def __init__(config: Optional[DaytonaConfig] = None) -> None

Daytona.create

async def create(image: str,
                 /,
                 *,
                 name: Optional[str] = None,
                 env: Optional[Dict[str, str]] = None,
                 labels: Optional[Dict[str, str]] = None,
                 resources: Optional[Resources] = None,
                 cpu: Optional[float] = None,
                 memory: Optional[int] = None,
                 disk: Optional[int] = None,
                 ports: Optional[Sequence[PortRequest]] = None,
                 volumes: Optional[Sequence[VolumeMount]] = None,
                 secrets: Optional[Sequence[str]] = None,
                 persistent: Optional[bool] = None,
                 spot: Optional[bool] = None,
                 lifecycle: Optional[LifecycleConfig] = None,
                 network_policy: NetworkPolicyInput | None | _UnsetNetworkPolicy = _UNSET_NETWORK_POLICY,
                 cpu_arch: Optional[str] = None,
                 cpu_type: Optional[str] = None,
                 target: Optional[str] = None,
                 toolbox_url: Optional[str] = None,
                 idempotency_key: Optional[str] = None,
                 wait: int = 60,
                 create_ttl: Optional[int] = None) -> Sandbox

Create from a registered image name or img_… id.

Fast path: the server holds this create briefly, so a sandbox that reaches running within that hold returns in one round trip. wait and create_ttl are budgets: the SDK long-polls any remainder of wait client-side, and create_ttl is the server's total budget for reaching running before deletion.

name is non-unique display metadata — and the handle of the one-sandbox-per-end-user pattern (issue #1935): a named create stamps labels["name"] = name (find_by_name reads it back) and, unless idempotency_key is given, derives its idempotency key from the name (idempotency_key_for_name). A repeated or retried create(image, name="mate") within one cell is therefore a get-or-create: the same sandbox comes back, not a second one or a 409 — until the first is deleted, which releases the key. The guarantee is cell-scoped (creates of one end user that land in two cells make two sandboxes; pin them to one target), per class (_experimental_create_gpu(name= "mate") after a Linux create(name="mate") is a 409 — the key belongs to a different request), and exact: a same-name create with different arguments is a 409 too, never a silent replay of the first sandbox's parameters. An explicit idempotency_key always wins over the derived one.

Visible resources. In burstable sandboxes the guest boots with the burst ceiling (resources.cpu_max / memory_max, or the deployment cap when omitted), so nproc and /proc/meminfo report that ceiling, not the guaranteed cpu. Tools that size themselves from the CPU count (pytest -n auto, make -j$(nproc)) start one worker per visible CPU. Pass an explicit worker count when you need the guarantee instead of the ceiling.

Daytona.create_from_snapshot

async def create_from_snapshot(snapshot: str,
                               /,
                               *,
                               name: Optional[str] = None,
                               labels: Optional[Dict[str, str]] = None,
                               lifecycle: Optional[LifecycleConfig] = None,
                               ports: Optional[Sequence[PortRequest]] = None,
                               target: Optional[str] = None,
                               toolbox_url: Optional[str] = None,
                               idempotency_key: Optional[str] = None,
                               wait: int = 60,
                               create_ttl: Optional[int] = None) -> Sandbox

Daytona.create_macos

async def create_macos(image: str,
                       /,
                       *,
                       name: Optional[str] = None,
                       env: Optional[Dict[str, str]] = None,
                       labels: Optional[Dict[str, str]] = None,
                       ports: Optional[Sequence[PortRequest]] = None,
                       persistent: Optional[bool] = None,
                       lifecycle: Optional[LifecycleConfig] = None,
                       reservation: Optional[str] = None,
                       auto_renew: Optional[bool] = None,
                       target: Optional[str] = None,
                       toolbox_url: Optional[str] = None,
                       idempotency_key: Optional[str] = None,
                       wait: int = 60,
                       create_ttl: Optional[int] = None) -> Sandbox

Create a macOS sandbox on a reserved Mac from a macOS image name.

reservation picks the Mac's lease (daytona.reservations): None packs the sandbox onto a reserved Mac with room (or lets the organization's auto-reserve buy one), "new" buys a lease for it, and a reservation id places it on exactly that lease. auto_renew is allowed only with reservation="new". With no lease to use it raises ConflictError (NO_ACTIVE_RESERVATION, NO_FREE_SLOT, AUTO_RESERVE_LIMIT_REACHED, NO_MAC_AVAILABLE). The Mac sets the size (half of it per sandbox), so there are no size parameters; the sandbox reports its size from its first boot on. name, idempotency_key, wait and create_ttl behave as on create.

Creating macOS sandboxes requires the organization's macos_sandboxes feature flag; without it the API answers 403 FEATURE_FLAG_DISABLED (raised as ForbiddenError).

Daytona.create_from_build

async def create_from_build(builder: ImageBuilder,
                            /,
                            *,
                            idle: Optional[int] = None,
                            network_policy: NetworkPolicyInput | None | _UnsetNetworkPolicy = _UNSET_NETWORK_POLICY,
                            **kwargs: object) -> Sandbox

Build an anonymous image first, then create the sandbox from it.

Slow path: POST /images followed by create(image.id, ...). idle describes the anonymous IMAGE (its idle window, PLAN-CREATION-SHAPE §5); every other keyword goes to create(). Docker needs no option: every Linux and GPU sandbox has Docker storage (PLAN-DOCKER-AUTOMATIC-SUPPORT.md). target (the create's region selector) is applied to BOTH legs: a Dockerfile-built image lives in one region and can only boot there (DP-2), so the image is built where the sandbox will run. If the image build fails, this raises ImageBuildFailedError and no sandbox exists.

Daytona.sandbox

def sandbox(sandbox_id: str | SandboxInfo | Mapping[str, JsonValue],
            *,
            toolbox_url: Optional[str] = None,
            access_token: Optional[str] = None,
            access_token_expires_at: Optional[str] = None) -> Sandbox

Create a lazy sandbox handle without fetching it.

A caller-supplied access_token is used verbatim as the data-plane credential and is never silently replaced: its expiry surfaces to the caller as a 401. Without one, the handle mints and refreshes short-lived sandbox access tokens through the project key transparently.

access_token_expires_at and _access_token_from_create are the SDK's own create-flow plumbing (the TS twin's accessTokenFromCreate shape): the expiry is honored only when the from-create knob is set, because only the create response's token is SDK-owned and refreshable — for a caller-supplied token the expiry is ignored and the never-replaced rule above stands.

Daytona.get

async def get(sandbox_id: str, *, toolbox_url: Optional[str] = None) -> Sandbox

Fetch a sandbox by id.

Daytona.find_by_name

async def find_by_name(name: str, /, *, target: Optional[str] = None) -> list[Sandbox]

Sandboxes created with name=name, newest first; [] when none.

Exact match on the labels["name"] every create*(name=…) stamps (issue #1935), read through the region-local GET /sandboxes?labels= filter — synchronous and read-your-writes, so a sandbox created a moment ago is found (unlike the eventually consistent search index behind list filters). Names are not unique, so this is a list: a get-or-create caller takes [0] when it is non-empty and calls create(..., name=name) otherwise — and because that create derives the same key as the first one, a lost race between two such callers still yields one sandbox. Sandboxes that are deleted or deleting are left out (their create key is already released).

target scopes the read the way it scopes a create: it defaults to the client's target, is sent as the same x-daytona-region selector create*() sends, and "local" means this API host's own region — so the lookup reads the cell the named create landed in, which is the create ledger's scope.

Daytona.audit_scenarios

async def audit_scenarios() -> AuditScenarios

Return the actions the audit log can record for each target type.

Daytona.current_api_key

async def current_api_key() -> CurrentApiKey

Describe the API key this client authenticates with.

Returns its name, masked display parts, the project and organization it acts in, its permissions, expiry and last use. The token itself is never returned.

Daytona.get_project_budget

async def get_project_budget() -> Optional[ProjectBudget]

Return the monthly spend budget of the API key's project.

Returns None when the project has no budget. The key needs the read:spending permission. Spend is calculated at list price, before credits, and lags usage by several minutes. While the project is over its budget, creating or starting a sandbox in it raises ProjectBudgetExceededError.

Daytona.list

async def list(*,
               cursor: Optional[str] = None,
               limit: Optional[int] = None,
               id: Optional[str] = None,
               name: Optional[str] = None,
               q: Optional[str] = None,
               status: Optional[Sequence[str]] = None,
               vm_class: Optional[Union[VmClass, Sequence[VmClass]]] = None,
               region: Optional[Sequence[str]] = None,
               image_ref: Optional[str] = None,
               image_ref_prefix: Optional[str] = None,
               labels: Optional[Mapping[str, str]] = None,
               persistent: Optional[bool] = None,
               spot: Optional[bool] = None,
               forked_from: Optional[str] = None,
               min_vcpus: Optional[int] = None,
               max_vcpus: Optional[int] = None,
               min_mem_mib: Optional[int] = None,
               max_mem_mib: Optional[int] = None,
               min_scratch_mib: Optional[int] = None,
               max_scratch_mib: Optional[int] = None,
               created_after: Optional[SearchTimestamp] = None,
               created_before: Optional[SearchTimestamp] = None,
               updated_after: Optional[SearchTimestamp] = None,
               updated_before: Optional[SearchTimestamp] = None,
               last_active_after: Optional[SearchTimestamp] = None,
               last_active_before: Optional[SearchTimestamp] = None,
               sort: Optional[SearchSort] = None,
               order: Optional[SearchOrder] = None) -> ListResult[Sandbox]

List sandboxes as one page {items, next_cursor}.

With only cursor/limit this is the read-your-writes path: one page of the region-local GET /sandboxes. A sandbox you just created is in the result; walk further pages with iter() or the returned cursor.

Any other parameter — including id / name (sent as id_prefix / name_prefix), q, status, vm_class, region, labels, the resource and timestamp bounds, sort, order — switches the call to a single GET /sandboxes/search request, the same surface as search, and fills total, total_relation and partial_regions on the result. That path is eventually consistent: a committed change is searchable after roughly 2-3 s, it spans every region rather than only this API host's, and partial_regions names regions whose index is still backfilling. The cursor it returns is opaque and tied to the exact filter and sort that produced it (reusing it with a different filter or sort is a 400), and paging is best-effort under concurrent mutation. If the API host has search disabled (501, SearchNotConfiguredError with code == "SEARCH_NOT_CONFIGURED") or the index is unreachable (503, SearchUnavailableError with code == "SEARCH_UNAVAILABLE"), drop the search parameters to fall back to the GET /sandboxes path.

Daytona.search

async def search(*,
                 q: Optional[str] = None,
                 name_prefix: Optional[str] = None,
                 id_prefix: Optional[str] = None,
                 status: Optional[Sequence[str]] = None,
                 vm_class: Optional[Union[VmClass, Sequence[VmClass]]] = None,
                 region: Optional[Sequence[str]] = None,
                 image_ref: Optional[str] = None,
                 image_ref_prefix: Optional[str] = None,
                 labels: Optional[Mapping[str, str]] = None,
                 persistent: Optional[bool] = None,
                 spot: Optional[bool] = None,
                 forked_from: Optional[str] = None,
                 min_vcpus: Optional[int] = None,
                 max_vcpus: Optional[int] = None,
                 min_mem_mib: Optional[int] = None,
                 max_mem_mib: Optional[int] = None,
                 min_scratch_mib: Optional[int] = None,
                 max_scratch_mib: Optional[int] = None,
                 created_after: Optional[SearchTimestamp] = None,
                 created_before: Optional[SearchTimestamp] = None,
                 updated_after: Optional[SearchTimestamp] = None,
                 updated_before: Optional[SearchTimestamp] = None,
                 last_active_after: Optional[SearchTimestamp] = None,
                 last_active_before: Optional[SearchTimestamp] = None,
                 sort: Optional[SearchSort] = None,
                 order: Optional[SearchOrder] = None,
                 limit: Optional[int] = None,
                 cursor: Optional[str] = None) -> SearchResult[Sandbox]

Search sandboxes across every region through the search index (GET /sandboxes/search).

Every parameter is optional and they combine as AND. q is free text over name and image (or an exact id); name_prefix/id_prefix are the server-side form of list(name=...)/list(id=...); status, vm_class and region accept a single value or a list (any-of; lifecycle states use the API's wire names such as running); labels is a containment match; the min_*/max_* and *_after/*_before bounds are inclusive, timestamps as RFC 3339 strings or datetime objects (naive values are taken as UTC). sort defaults to created_at and order to desc; limit is clamped to 1..200 by the server. Returns a SearchResult whose items are the same Sandbox handles list returns.

Consistency: the index is eventually consistent. A committed create, update or delete becomes searchable about 2-3 s later, so a sandbox you just created may not be in the result yet — use get or list without search filters for read-your-writes. Results span every region, not only the one this API host serves. partial_regions lists region slugs whose cell has not finished backfilling the index (or has never reported in); results for them may be incomplete. It is empty in steady state.

Cursor: next_cursor is opaque and bound to the exact filter and sort that produced it — presenting it with a different filter or sort is a 400, never a silent reset. Paging is best-effort under concurrent mutation: each page reads the live index, so a sandbox whose sort field (status, name, mem_mib, updated_at, ...) changes between two page fetches can appear on both pages or on neither, and creates or deletes mid-walk shift later pages.

Errors: 400 (BadRequestError) for a malformed or mismatched cursor, an unknown status/vm_class/sort value, a non-object labels or a min above its max; 501 (SearchNotConfiguredError with code == "SEARCH_NOT_CONFIGURED") when this API host has search disabled; 503 (SearchUnavailableError with code == "SEARCH_UNAVAILABLE") when the index did not answer. The server body is the unified {code, message, source, trace_id} envelope. On 501/503 callers may fall back to list without search parameters, which never touches the index.

Daytona.iter

async def iter(*,
               cursor: Optional[str] = None,
               limit: Optional[int] = None) -> AsyncIterator[Sandbox]

Daytona.start

async def start(sandbox: Union[Sandbox, str], *, timeout: float = 60) -> None

Start a sandbox (accepts a Sandbox or its id).

Daytona.stop

async def stop(sandbox: Union[Sandbox, str]) -> None

Warm-stop a sandbox (accepts a Sandbox or its id).

Daytona.pause

async def pause(sandbox: Union[Sandbox, str], *, timeout: float = 60) -> None

Pause a sandbox (accepts a Sandbox or its id); see Sandbox.pause.

Daytona.resume

async def resume(sandbox: Union[Sandbox, str], *, timeout: float = 60) -> None

Resume a sandbox (accepts a Sandbox or its id).

Daytona.delete

async def delete(sandbox: Union[Sandbox, str]) -> None

Delete a sandbox (accepts a Sandbox or its id).

Daytona.get_network_policy

async def get_network_policy(sandbox: Union[Sandbox, str]) -> NetworkPolicyInfo

Daytona.update_network_policy

async def update_network_policy(sandbox: Union[Sandbox, str],
                                *,
                                network_policy: NetworkPolicyInput,
                                if_match: str) -> NetworkPolicyInfo

Daytona.reset_network_policy

async def reset_network_policy(sandbox: Union[Sandbox, str],
                               *,
                               if_match: str) -> NetworkPolicyInfo

Daytona.close

async def close() -> None

Close HTTP resources.

LifecycleConfig

class LifecycleConfig(TypedDict, total=False)

Per-sandbox lifecycle policy: a wall-clock timeout and an idle timeout, each paired with the action it fires.

timeout_secs (>= 1, never disabled) fires on_timeout that many seconds after create, after a daytona.Sandbox.set_lifecycle that supplies it, and again after every accepted transition to running (start, resume, wake) — the full budget re-arms each time. Omitted on_timeout resolves to the class default (pause linux persistent, stop windows persistent, delete ephemeral and gpu).

idle_timeout_secs is opt-in and fires on_idle_timeout after that many seconds without activity; DISABLED clears it. on_idle_timeout has no default — arming idle_timeout_secs from nothing requires it.

At create, each field you omit is inherited: first from the project's lifecycle defaults (set in the dashboard's project settings; a persistent sandbox uses the persistent defaults, every other sandbox the ephemeral ones), then — for timeout_secs only — from the platform default timeout when the platform has it enabled. An action follows its own interval: a timeout_secs you pass without on_timeout gets the class default, not the project's action. Pass DISABLED as idle_timeout_secs to opt out of an inherited idle timeout. Project defaults apply to new sandboxes only; daytona.Sandbox.set_lifecycle never consults them.

Rejected before posting when inapplicable to the sandbox class: see LifecycleAction for the action matrix; wake_on_request needs linux persistent.

Attributes:

• timeout_secs int
• on_timeout LifecycleAction
• idle_timeout_secs int
• on_idle_timeout LifecycleAction
• wake_on_request bool

ListResult

@dataclass(frozen=True)
class ListResult(Generic[T])

Cursor-paginated list result.

total, total_relation and partial_regions are only populated when the result came from the search index (Daytona.list() with any search filter); they are None on every other list surface.

Attributes:

• items List[T]
• next_cursor Optional[str] = None
• total Optional[int] = None
• total_relation Optional[str] = None
• partial_regions Optional[List[str]] = None

DaytonaConfig

@dataclass(frozen=True)
class DaytonaConfig()

Configuration for the V2 Daytona client.

request_timeout is the per-request HTTP timeout in seconds; 0 keeps the transport unbounded. shared_hub controls whether this instance shares the shared daytona._events.WaitHub for its event loop and hub identity (default) or gets its own private one. events customises that identity and the hub's behaviour; None uses defaults.

Attributes:

• api_url Optional[str] = None
• api_key Optional[str] = None
• jwt_token Optional[str] = field(default=None, kw_only=True)
• project_id Optional[str] = field(default=None, kw_only=True)
• otel_enabled Optional[bool] = field(default=None, kw_only=True)
• connection_pool_maxsize Optional[int] = field(default=None, kw_only=True)
• target Optional[str] = None
• request_timeout Optional[float] = None
• shared_hub bool = True
• events Optional[SandboxEventsConfig] = None

Resources

@dataclass(frozen=True)
class Resources()

Sandbox resource request; memory and disk are GiB.

cpu/memory/disk are the request: what is reserved and billed as a floor. cpu_max/memory_max/disk_max are the limits: the boot shape and the ceiling, the system cap when omitted. Set each limit equal to its request for a fixed shape. Requests below the platform minimums are raised to them, so a fixed shape below a minimum is refused.

_experimental_gpu is experimental and may change or be removed without notice: the abstract GPU count for Daytona._experimental_create_gpu (sent as gpu_host when neither gpu_host nor a gpu address list is given). GPU creates need the organization's gpu_sandboxes feature flag.

Attributes:

• cpu Optional[float] = None
• cpu_max Optional[int] = None
• memory Optional[int] = None
• memory_max Optional[float] = None
• disk Optional[int] = None
• disk_max Optional[float] = None

NetworkPolicyInput

class NetworkPolicyInput(TypedDict, total=False)

Attributes:

• block_all bool | None
• allow_cidrs Sequence[str]
• allow_domains Optional[Sequence[str]]

NetworkPolicy

@dataclass(frozen=True)
class NetworkPolicy()

Attributes:

• version int
• block_all bool = False
• allow_cidrs List[str] = field(default_factory=list)
• allow_domains Optional[List[str]] = None

NetworkPolicyInfo

@dataclass(frozen=True)
class NetworkPolicyInfo()

Attributes:

• desired Optional[NetworkPolicy]
• desired_revision int
• etag str
• http_status int
• applied Optional[NetworkPolicy] = None
• applied_revision Optional[int] = None
• applied_incarnation Optional[str] = None
• state Optional[str] = None
• failure_reason Optional[str] = None

SnapshotRef

@dataclass(frozen=True, slots=True)
class SnapshotRef()

Attributes:

• id str
• name Optional[str] = None

ListSandboxesQuery

@dataclass(frozen=True)
class ListSandboxesQuery(SandboxSearchFilters)

Every Daytona.list() parameter.

cursor/limit/id/name keep the region-local GET /sandboxes semantics and remain the only positional parameters, in that order; any inherited (keyword-only) search filter routes the call to /sandboxes/search.

Attributes:

• cursor Optional[str] = None
• limit Optional[int] = None
• id Optional[str] = None
• name Optional[str] = None

SyncDaytona

class SyncDaytona()

Top-level synchronous client.

SyncDaytona.__init__

def __init__(config: Optional[DaytonaConfig] = None) -> None

SyncDaytona.images

@property
def images() -> SyncImageService

SyncDaytona.snapshots

@property
def snapshots() -> SyncSnapshotService

SyncDaytona.volume

@property
def volume() -> SyncVolumeService

SyncDaytona.secret

@property
def secret() -> SyncSecretService

SyncDaytona.secrets

@property
def secrets() -> SyncSecretService

SyncDaytona.reservations

@property
def reservations() -> SyncReservationService

SyncDaytona.audit_scenarios

def audit_scenarios() -> AuditScenarios

Return the actions the audit log can record for each target type.

SyncDaytona.close

def close() -> None

Close HTTP resources, then stop the bridge loop. Idempotent; safe from any thread.

SyncDaytona.create

def create(image: str,
           /,
           *,
           name: Optional[str] = None,
           env: Optional[Dict[str, str]] = None,
           labels: Optional[Dict[str, str]] = None,
           resources: Optional[Resources] = None,
           cpu: Optional[float] = None,
           memory: Optional[int] = None,
           disk: Optional[int] = None,
           ports: Optional[Sequence[PortRequest]] = None,
           volumes: Optional[Sequence[VolumeMount]] = None,
           secrets: Optional[Sequence[str]] = None,
           persistent: Optional[bool] = None,
           spot: Optional[bool] = None,
           lifecycle: Optional[LifecycleConfig] = None,
           network_policy: NetworkPolicyInput | None | _UnsetNetworkPolicy = _UNSET_NETWORK_POLICY,
           cpu_arch: Optional[str] = None,
           cpu_type: Optional[str] = None,
           target: Optional[str] = None,
           toolbox_url: Optional[str] = None,
           idempotency_key: Optional[str] = None,
           wait: int = 60,
           create_ttl: Optional[int] = None) -> SyncSandbox

Create from a registered image name or img_… id.

SyncDaytona.create_from_build

def create_from_build(builder: ImageBuilder,
                      /,
                      *,
                      idle: Optional[int] = None,
                      network_policy: NetworkPolicyInput | None | _UnsetNetworkPolicy = _UNSET_NETWORK_POLICY,
                      **kwargs) -> SyncSandbox

Build an anonymous image first, then create the sandbox from it.

SyncDaytona.create_from_snapshot

def create_from_snapshot(snapshot: str,
                         /,
                         *,
                         name: Optional[str] = None,
                         labels: Optional[Dict[str, str]] = None,
                         lifecycle: Optional[LifecycleConfig] = None,
                         ports: Optional[Sequence[PortRequest]] = None,
                         target: Optional[str] = None,
                         toolbox_url: Optional[str] = None,
                         idempotency_key: Optional[str] = None,
                         wait: int = 60,
                         create_ttl: Optional[int] = None) -> SyncSandbox

SyncDaytona.create_macos

def create_macos(image: str,
                 /,
                 *,
                 name: Optional[str] = None,
                 env: Optional[Dict[str, str]] = None,
                 labels: Optional[Dict[str, str]] = None,
                 ports: Optional[Sequence[PortRequest]] = None,
                 persistent: Optional[bool] = None,
                 lifecycle: Optional[LifecycleConfig] = None,
                 reservation: Optional[str] = None,
                 auto_renew: Optional[bool] = None,
                 target: Optional[str] = None,
                 toolbox_url: Optional[str] = None,
                 idempotency_key: Optional[str] = None,
                 wait: int = 60,
                 create_ttl: Optional[int] = None) -> SyncSandbox

Create a macOS sandbox on a reserved Mac from a macOS image name.

SyncDaytona.current_api_key

def current_api_key() -> CurrentApiKey

Describe the API key this client authenticates with.

SyncDaytona.delete

def delete(sandbox: Union[SyncSandbox, str]) -> None

Delete a sandbox (accepts a Sandbox or its id).

SyncDaytona.find_by_name

def find_by_name(name: str, /, *, target: Optional[str] = None) -> list[SyncSandbox]

Sandboxes created with name=name, newest first; [] when none.

SyncDaytona.get

def get(sandbox_id: str, *, toolbox_url: Optional[str] = None) -> SyncSandbox

Fetch a sandbox by id.

SyncDaytona.get_network_policy

def get_network_policy(sandbox: Union[SyncSandbox, str]) -> NetworkPolicyInfo

SyncDaytona.get_project_budget

def get_project_budget() -> Optional[ProjectBudget]

Return the monthly spend budget of the API key's project.

SyncDaytona.iter

def iter(*,
         cursor: Optional[str] = None,
         limit: Optional[int] = None) -> Iterator[SyncSandbox]

SyncDaytona.list

def list(*,
         cursor: Optional[str] = None,
         limit: Optional[int] = None,
         id: Optional[str] = None,
         name: Optional[str] = None,
         q: Optional[str] = None,
         status: Optional[Sequence[str]] = None,
         vm_class: Optional[Union[VmClass, Sequence[VmClass]]] = None,
         region: Optional[Sequence[str]] = None,
         image_ref: Optional[str] = None,
         image_ref_prefix: Optional[str] = None,
         labels: Optional[Mapping[str, str]] = None,
         persistent: Optional[bool] = None,
         spot: Optional[bool] = None,
         forked_from: Optional[str] = None,
         min_vcpus: Optional[int] = None,
         max_vcpus: Optional[int] = None,
         min_mem_mib: Optional[int] = None,
         max_mem_mib: Optional[int] = None,
         min_scratch_mib: Optional[int] = None,
         max_scratch_mib: Optional[int] = None,
         created_after: Optional[SearchTimestamp] = None,
         created_before: Optional[SearchTimestamp] = None,
         updated_after: Optional[SearchTimestamp] = None,
         updated_before: Optional[SearchTimestamp] = None,
         last_active_after: Optional[SearchTimestamp] = None,
         last_active_before: Optional[SearchTimestamp] = None,
         sort: Optional[SearchSort] = None,
         order: Optional[SearchOrder] = None) -> ListResult[SyncSandbox]

List sandboxes as one page {items, next_cursor}.

SyncDaytona.pause

def pause(sandbox: Union[SyncSandbox, str], *, timeout: float = 60) -> None

Pause a sandbox (accepts a Sandbox or its id); see Sandbox.pause.

SyncDaytona.reset_network_policy

def reset_network_policy(sandbox: Union[SyncSandbox, str],
                         *,
                         if_match: str) -> NetworkPolicyInfo

SyncDaytona.resume

def resume(sandbox: Union[SyncSandbox, str], *, timeout: float = 60) -> None

Resume a sandbox (accepts a Sandbox or its id).

SyncDaytona.sandbox

def sandbox(sandbox_id: str | SandboxInfo | Mapping[str, JsonValue],
            *,
            toolbox_url: Optional[str] = None,
            access_token: Optional[str] = None,
            access_token_expires_at: Optional[str] = None) -> SyncSandbox

Create a lazy sandbox handle without fetching it.

SyncDaytona.search

def search(*,
           q: Optional[str] = None,
           name_prefix: Optional[str] = None,
           id_prefix: Optional[str] = None,
           status: Optional[Sequence[str]] = None,
           vm_class: Optional[Union[VmClass, Sequence[VmClass]]] = None,
           region: Optional[Sequence[str]] = None,
           image_ref: Optional[str] = None,
           image_ref_prefix: Optional[str] = None,
           labels: Optional[Mapping[str, str]] = None,
           persistent: Optional[bool] = None,
           spot: Optional[bool] = None,
           forked_from: Optional[str] = None,
           min_vcpus: Optional[int] = None,
           max_vcpus: Optional[int] = None,
           min_mem_mib: Optional[int] = None,
           max_mem_mib: Optional[int] = None,
           min_scratch_mib: Optional[int] = None,
           max_scratch_mib: Optional[int] = None,
           created_after: Optional[SearchTimestamp] = None,
           created_before: Optional[SearchTimestamp] = None,
           updated_after: Optional[SearchTimestamp] = None,
           updated_before: Optional[SearchTimestamp] = None,
           last_active_after: Optional[SearchTimestamp] = None,
           last_active_before: Optional[SearchTimestamp] = None,
           sort: Optional[SearchSort] = None,
           order: Optional[SearchOrder] = None,
           limit: Optional[int] = None,
           cursor: Optional[str] = None) -> SearchResult[SyncSandbox]

Search sandboxes across every region through the search index (GET /sandboxes/search).

SyncDaytona.start

def start(sandbox: Union[SyncSandbox, str], *, timeout: float = 60) -> None

Start a sandbox (accepts a Sandbox or its id).

SyncDaytona.stop

def stop(sandbox: Union[SyncSandbox, str]) -> None

Warm-stop a sandbox (accepts a Sandbox or its id).

SyncDaytona.update_network_policy

def update_network_policy(sandbox: Union[SyncSandbox, str],
                          *,
                          network_policy: NetworkPolicyInput,
                          if_match: str) -> NetworkPolicyInfo

idempotency_key_for_name

def idempotency_key_for_name(name: str) -> str

The idempotency key create*(name=name) derives when none is given.

"name:" + name when that is a key the API accepts verbatim — printable ASCII (0x20–0x7E), no surrounding whitespace (the API trims keys and HTTP strips header padding, so a padded name would not round-trip), at most 256 characters in total — else "name:sha256:" + hex(sha256(name)) over the UTF-8 bytes. The name: namespace keeps a derived key from ever colliding with a caller's explicit key of the same spelling. Deterministic and identical in the TypeScript SDK, so the two SDKs are one client to the API's cell-scoped create ledger: use it to recover or inspect the key behind a named create.

NAME_LABEL: Final

NAME_LABEL = 'name'

VmStateSnapshot

VmStateSnapshot = _gen.api.SnapshotPageRow

SnapshotDetail

SnapshotDetail = _gen.api.SnapshotRow

VmClass

VmClass = Literal['linux', 'windows', 'gpu', 'macos']

LifecycleAction

LifecycleAction = Literal['stop', 'pause', 'delete']

The action a lifecycle trigger fires: on_timeout / on_idle_timeout.

Legal per class: delete everywhere; stop needs a persistent sandbox (linux or windows — never gpu, which is always ephemeral); pause needs linux persistent.

DISABLED: int

DISABLED = -1

Clears LifecycleConfig.idle_timeout_secs — and ONLY that field.

idle_timeout_secs value space, identical at create and on daytona.Sandbox.set_lifecycle: omitted = unchanged (set_lifecycle) / disabled (create); DISABLED (-1) = clear the idle pair (on_idle_timeout with it); n > 0 = seconds, a value below 60 raised to 60 server-side and read back raised; 0 and anything below -1 are rejected.

timeout_secs does NOT accept it: the timeout cannot be disabled, so timeout_secs must be >= 1 (-1 and 0 are rejected).