# Daytona Documentation (/docs/quickstart) Daytona is secure and elastic cloud infrastructure built for autonomous agents. Daytona provides **composable computers for agents** — [sandboxes](/docs/sandboxes) — virtual machines with hardware isolation, a dedicated kernel, filesystem, network, and allocated vCPU, RAM, and disk. Sandboxes are the core component of the Daytona platform, spinning up in under 90ms from code to execution and running any code in Python, TypeScript, and JavaScript. Built on OCI/Docker compatibility and massive parallelization, sandboxes deliver consistent, predictable environments for AI, autonomous agents, and reinforcement learning. ## Get started [#get-started] 1. Create an account → [app.daytona.com](https://app.daytona.com) 2. Get an API key → [app.daytona.com/dashboard/keys](https://app.daytona.com/dashboard/keys) 3. Save the API key → `DAYTONA_API_KEY` environment variable or in a `.env` file. ```bash DAYTONA_API_KEY=YOUR_API_KEY ``` ```bash export DAYTONA_API_KEY=YOUR_API_KEY ``` ```powershell $env:DAYTONA_API_KEY="YOUR_API_KEY" ``` 4. Install the Python SDK ```bash pip install daytona==2.0.0a11 ``` 5. Create a sandbox and run code ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() response = sandbox.run_code('print("Hello World")') print(response.logs.stdout) ``` 4. Install the TypeScript SDK ```bash npm install @daytona/sdk@2.0.0-alpha.11 ``` 5. Create a sandbox and run code ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() const response = await sandbox.runCode('print("Hello World")') console.log(response.logs.stdout) ``` 4. Install the CLI ```bash brew install daytonaio/cli/daytona-alpha ``` ```bash # Installs the newest 2.x release for this host after verifying its checksum curl -fsSL https://github.com/daytona/clients/releases/download/v2.0.0-alpha.11/install.sh | sh ``` ```powershell irm https://github.com/daytona/clients/releases/download/v2.0.0-alpha.11/install.ps1 | iex ``` 5. Log in ```bash daytona login --token "$DAYTONA_API_KEY" --api-url https://api.daytona.com ``` ```powershell daytona login --token "$env:DAYTONA_API_KEY" --api-url https://api.daytona.com ``` 6. Create a sandbox and run code ```bash daytona sandbox create daytona sandbox exec {sandboxId} -- python -c 'print("Hello World")' ``` 4. Create a sandbox and run code ```bash # Create sandbox curl 'https://api.daytona.com/sandboxes' \ --request POST \ --header 'Content-Type: application/json' \ --header "Authorization: Bearer $DAYTONA_API_KEY" \ --data '{}' # Wait until running curl 'https://api.daytona.com/sandboxes/{sandboxId}?wait=running&timeout_ms=60000' \ --header "Authorization: Bearer $DAYTONA_API_KEY" # Run code; {toolboxProxyUrl} is toolbox_proxy_url from the sandbox response curl '{toolboxProxyUrl}/{sandboxId}/processes?waitMs=30000&logs=text' \ --request POST \ --header 'Content-Type: application/json' \ --header "Authorization: Bearer $DAYTONA_API_KEY" \ --data '{"kind": "code", "language": "python", "code": "print(\"Hello World\")"}' ``` ## Reference [#reference] Daytona provides a comprehensive set of resources for developers and agents to get started and build on the platform. You can find the following resources in the documentation: - **Daytona Sandboxes**: [Linux](/docs/sandboxes#linux-sandboxes), [Windows](/docs/sandboxes#windows-sandboxes), [GPU](/docs/sandboxes#gpu-sandboxes), [macOS](/docs/sandboxes#macos-sandboxes) - **Daytona SDKs**: [TypeScript](/docs/typescript-sdk), [Python](/docs/python-sdk) - **Daytona APIs**: [Platform](/docs/api/daytona) ([OpenAPI](/docs/openapi.json)), [Toolbox](/docs/api/toolbox) ([OpenAPI](/docs/toolbox-openapi.json)) - **Daytona CLI**: [Mac/Linux/Windows](/docs/cli) - **Daytona LLMs**: [llms.txt](https://www.daytona.com/llms.txt), [llms-full.txt](https://www.daytona.com/llms-full.txt) - **Daytona Markdown**: suffix pages with `.md` (e.g [sandboxes.md](/docs/sandboxes.md)) # Authentication (/docs/authentication) Daytona authenticates SDK, CLI, and API requests with a project [API key](/docs/api-keys). The key identifies the [project](/docs/projects) that owns the sandboxes you create and carries the [permissions](/docs/api-keys#scopes) a request may use. ## Get an API key [#get-an-api-key] 1. Go to [Daytona Dashboard ↗](https://app.daytona.com/dashboard/keys) 2. Select the project in the header switcher 3. Click 4. Enter 5. Select permission 6. Click 7. Copy and save the API key as an environment variable ## Environment variables [#environment-variables] Daytona resolves configuration in order of precedence: 1. Configuration in code 2. Environment variables | **Variable** | **Description** | | ------------------------- | ---------------------------------------------------------------------------------------------- | | **`DAYTONA_API_KEY`** | Your Daytona API key.
Required unless `DAYTONA_JWT_TOKEN` is set | | **`DAYTONA_JWT_TOKEN`** | A JWT instead of an API key.
Optional; needs `DAYTONA_PROJECT_ID` | | **`DAYTONA_PROJECT_ID`** | The project a JWT is scoped to.
Required with `DAYTONA_JWT_TOKEN` | ### .env file [#env-file] ```bash DAYTONA_API_KEY=YOUR_API_KEY ``` ### Shell [#shell] ```bash export DAYTONA_API_KEY=YOUR_API_KEY ``` ```powershell $env:DAYTONA_API_KEY="YOUR_API_KEY" ``` ## Authenticate the SDK [#authenticate-the-sdk] Construct the client without arguments to read the environment variables, or pass the configuration in code. Every call made through the client sends the API key or, with a JWT, a short-lived project token the client exchanges the JWT for. ```python from daytona import Daytona, DaytonaConfig # Using environment variables daytona = Daytona() # Using explicit configuration config = DaytonaConfig(api_key="YOUR_API_KEY") daytona = Daytona(config) # Pick the region per create sandbox = daytona.v2.create(region="earth") ``` | **Parameter** | **Type** | **Description** | | ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `api_key` | str | Falls back to `DAYTONA_API_KEY`. When neither this nor `jwt_token` is set, the first access to `daytona.v2` raises `UnauthorizedError`. | | `jwt_token` | str | A JWT instead of an API key. Falls back to `DAYTONA_JWT_TOKEN`. Needs `project_id`; setting both `api_key` and `jwt_token` raises `BadRequestError`. | | `project_id` | str | The project a JWT is scoped to. Falls back to `DAYTONA_PROJECT_ID`. | | `request_timeout` | float | Per-request HTTP timeout in seconds. `0` disables the timeout. | ```typescript import { Daytona } from '@daytona/sdk' // Using environment variables const daytona = new Daytona() // Using explicit configuration const daytonaWithConfig = new Daytona({ apiKey: 'YOUR_API_KEY' }) // Pick the region per create const sandbox = await daytonaWithConfig.v2.create({ region: 'earth' }) ``` | **Parameter** | **Type** | **Description** | | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `apiKey` | string | Falls back to `DAYTONA_API_KEY`. When neither this nor `jwtToken` is set, the first access to `daytona.v2` throws `DaytonaAuthenticationError`. | | `jwtToken` | string | A JWT instead of an API key. Falls back to `DAYTONA_JWT_TOKEN`. Needs `projectId`; setting both `apiKey` and `jwtToken` throws `DaytonaValidationError`. | | `projectId` | string | The project a JWT is scoped to. Falls back to `DAYTONA_PROJECT_ID`. | | `requestTimeout` | number | Per-request HTTP timeout in milliseconds. `0` disables the timeout. | ### Close the client [#close-the-client] Close the client when your program no longer needs it. The client holds network resources between calls, such as the connection that reports sandbox state changes, and closing it releases them. Closing does not stop or delete any sandbox. Closing an already closed client does nothing. ```python from daytona import Daytona # Close the client when the block exits with Daytona() as daytona: sandbox = daytona.v2.create() # Close the client explicitly daytona = Daytona() sandbox = daytona.v2.create() daytona.close() ``` - Use `AsyncDaytona` with `async with` or `await daytona.close()` in asynchronous code. ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() // Close the client explicitly await daytona.close() ``` - Declare the client with `await using` to close it when the scope exits. ## Authenticate the CLI [#authenticate-the-cli] Sign in once and the CLI saves the session in its active profile, so following commands need no key or flags. After a browser or device login, the CLI selects your personal organization and its default project the first time and remembers your last selection afterwards. Sandbox commands use a short-lived platform token where the deployment issues one. Toolbox access, and sandbox commands on other deployments, use a project API key the CLI mints on your behalf with a 24-hour expiry; logging out attempts to revoke these keys. ```bash # Browser login daytona login --api-url https://api.daytona.com # Device-code login on a host without a browser daytona login --device --api-url https://api.daytona.com # Store an API key in the active profile daytona login --token YOUR_API_KEY --api-url https://api.daytona.com # Confirm who you are and what is selected daytona whoami # Create a sandbox with the saved session daytona sandbox create # Remove the saved session from this machine daytona logout ``` ```bash # Using environment variables (DAYTONA_API_KEY, DAYTONA_API_URL) daytona sandbox create # Using explicit flags daytona sandbox create --api-key YOUR_API_KEY --api-url https://api.daytona.com ``` | **Flag** | **Type** | **Description** | | ----------- | -------- | ------------------------------------------------------------------------------------------------ | | `--api-key` | string | Takes precedence over `DAYTONA_API_KEY`. Either one replaces the saved login for that command. | | `--api-url` | string | Takes precedence over `DAYTONA_API_URL`, and either one overrides the URL stored in the profile. | | `--profile` | string | Selects a profile other than the active one. `DAYTONA_PROFILE` does the same. | ### Profiles [#profiles] A profile is a named connection: an API URL, a credential, and the selected organization and project. One machine can keep several profiles, for example one per organization or deployment, and switch between them without signing in again. A command uses the profile it names, then the profile in the environment, then the active profile, then the profile named `default`. Signing in to a new profile creates it, and makes it active only when no profile is active yet. Deleting the active profile makes `default` active when it exists, otherwise no profile is active. ```bash # Sign in to a second profile daytona login --profile work --api-url https://api.daytona.com # List profiles daytona profile list # Run one command with another profile daytona sandbox list --profile work # Make a profile active for following commands daytona profile use work # Delete a profile and its saved credentials daytona profile delete work ``` | **Argument** | **Type** | **Description** | | ------------ | -------- | --------------- | | `name` | string | Sets the profile name: from `1` to `64` ASCII letters, digits, `.`, `_`, or `-`, excluding `.` and `..`. This argument is required. | The output of the list has the following columns: | **Column** | **Description** | | ------------ | ----------------------------------------------------------------------- | | (unnamed) | `*` for the active profile. | | `NAME` | Profile name. | | `API URL` | The API URL the profile connects to. | | `CREDENTIAL` | How the profile authenticates: `oidc` for a browser or device login, `token` for a static credential stored with `--token`, such as a project or organization API key. | | `ORG` | ID of the selected organization. | | `PROJECT` | ID of the selected project. | - A profile named by `--profile` or `DAYTONA_PROFILE` must exist, except in `daytona login`, which creates it. - Deleting a profile attempts to revoke its CLI-minted project keys. The profile is deleted from the machine even when the revocation fails, and the keys expire after 24 hours. ### Confirmation prompts [#confirmation-prompts] At a terminal, the CLI asks for confirmation before destructive and billable commands. The setting applies to every profile on the machine. Turning it off removes the prompt only: when the CLI is not attached to a terminal, prints JSON or YAML, or runs with the `CI` environment variable set, those commands still require an explicit confirmation. ```bash # Turn off confirmation prompts daytona config set confirm false # Print the current value daytona config get confirm # Print the directory that holds profiles, credentials, and settings daytona config path ``` | **Setting** | **Type** | **Description** | | ----------- | -------- | --------------- | | `confirm` | bool | Sets whether destructive and billable commands ask for confirmation at a terminal: `true` or `false`. The default is `true`. | - Pass `--yes` or set `DAYTONA_YES=1` to confirm a command without a prompt, for example in scripts and CI. - The config directory is `DAYTONA_CONFIG_DIR` when set, else `$XDG_CONFIG_HOME/daytona`, else `~/.config/daytona`. ## Authenticate API requests [#authenticate-api-requests] Send the API key as a bearer token in the authorization header of every request. ```bash curl 'https://api.daytona.com/sandboxes' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{}' ``` # Sandboxes (/docs/sandboxes) A sandbox is a hardware-isolated virtual machine with its own kernel, filesystem, network stack, and allocated vCPU, RAM, and disk, with isolation enforced by the hypervisor. Sandboxes run as [Linux](#linux-sandboxes) (default), [Windows](#windows-sandboxes), [macOS](#macos-sandboxes), or [GPU](#gpu-sandboxes)-accelerated virtual machines. Every sandbox moves through a lifecycle and can have several different states. While the sandbox is running, it exposes a toolbox for code, command, and process execution, sessions, filesystem and git operations, computer use, language server protocol support, and log streaming. Use sandboxes to run code written by an agent, build and test software, train or serve a model on a dedicated GPU, drive desktop through screenshots and input events, or spin up thousands of identical environments for autonomous, evaluation, and reinforcement learning workflows. | **Concept** | **Description** | | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Sandbox** | An isolated, dedicated virtual machine. | | **Image** | The OCI image, Dockerfile build, or snapshot the sandbox boots from. | | **Resources** | The vCPU, memory, and disk allocated to the sandbox. | | **Lifecycle** | The states a sandbox can be in and the transitions between them. | | **Persistence** | Deleting a sandbox discards its filesystem. Persistent macOS sandboxes can stop/start, pause/resume, and fork. | | **Toolbox** | A set of features for code, command, and process execution, sessions, filesystem and git operations, computer use, and language server protocol support. | ## Create sandboxes [#create-sandboxes] Daytona provides methods to create sandboxes from the dashboard or programmatically. 1. Go to [Daytona Sandboxes ↗](https://app.daytona.com/dashboard/sandboxes) 2. Click 3. Select , , , or 4. Click ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() ``` ```bash daytona sandbox create ``` ```bash curl 'https://api.daytona.com/sandboxes' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{}' ``` ### Linux sandboxes [#linux-sandboxes] [Linux sandboxes](/docs/linux-sandboxes) are Firecracker microVMs that run their own Linux kernel, and they are the default sandbox type. A Linux sandbox boots from an image that you import from a container registry, build from a Dockerfile, or capture from another sandbox. It can also start from a snapshot of another Linux sandbox. Each sandbox runs on an amd64 or arm64 CPU. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() ``` ```bash daytona sandbox create ``` ```bash curl 'https://api.daytona.com/sandboxes' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{}' ``` ### Windows sandboxes [#windows-sandboxes] [Windows sandboxes](/docs/windows-sandboxes) are virtual machines running Windows Server 2022. A Windows sandbox starts from a prepared Windows base image, or from an image captured from another Windows sandbox. Commands run in PowerShell, and the desktop is reached over the remote desktop protocol. ### macOS sandboxes [#macos-sandboxes] [macOS sandboxes](/docs/macos-sandboxes) are virtual machines running macOS on Apple silicon Mac computers. A macOS sandbox starts from a macOS image. A create can set the sandbox's cores, memory and disk, up to the whole Mac. By default it gets half of the Mac's cores, memory and sandbox disk, so two sandboxes can share one Mac. ### GPU sandboxes [#gpu-sandboxes] [GPU sandboxes](/docs/gpu-sandboxes) have one or more dedicated NVIDIA or AMD GPUs attached for workloads that require GPU acceleration, model inference, training, fine-tuning, and reinforcement learning. A GPU sandbox is ephemeral and can be saved as a checkpoint that includes its processes, memory, and GPU memory, and resumed in a new GPU sandbox. - **NVIDIA H100** - **NVIDIA H200** - **NVIDIA B200** - **NVIDIA B300** - **NVIDIA RTX Pro 6000** - **NVIDIA RTX 4090** - **NVIDIA RTX 5090** - **NVIDIA L40S** - **AMD Instinct MI355X** ## Resources [#resources] Linux sandboxes have **0.5 cores**, **1024MiB memory**, and **512MiB disk** by default. A Linux sandbox may guarantee at most **16 cores**, **32GiB memory**, and **256GiB disk**. A macOS sandbox takes its [size](/docs/macos-sandboxes#sizes) from its Mac reservation. CPU is measured and billed in cores, from fractions of a core up to many cores. One core is **2 vCPUs** where simultaneous multithreading (SMT, also called hyperthreading) is available and enabled, and **1 vCPU** otherwise. Each resource has a guarantee and a limit. A sandbox can always use its guarantee and takes more as its workload needs it, up to the limit, with no manual resize. The **guarantee** is the CPU, memory, and disk that Daytona reserves for the sandbox on its host. It is billed as a minimum, whether the sandbox uses it or not. The CPU guarantee is at least **1 core** for every **8GiB** of guaranteed memory. When a create guarantees more memory than its CPU guarantee covers, Daytona raises the CPU guarantee to that floor, so a sandbox that guarantees **16GiB** memory reserves and is billed for at least **2 cores**. | **Resource** | **Unit** | **Default guarantee** | **Minimum guarantee** | **Maximum guarantee** | | ------------ | -------- | --------------------- | --------------------------------- | --------------------- | | CPU | Cores | `0.5` | **`0.125`** (when set explicitly) | **`16`** | | Memory | MiB | `1024` | **`512`** (when set explicitly) | **`32768`** | | Disk | MiB | `512` | **`10240`** (when set explicitly) | **`262144`** | The **limit** is the most the sandbox can use. You set it when you create the sandbox. When a create sets no limit, the limit is the platform maximum or the cap of the organization's [plan](/docs/limits#sandbox-limits), whichever is lower. A limit equal to its guarantee gives the sandbox a fixed size that does not grow. | **Resource** | **Unit** | **Default limit** | **Minimum limit** | **Maximum limit** | | ------------ | -------- | ---------------------------- | ------------------------------- | ----------------- | | CPU | Cores | Platform maximum or plan cap | **`0.5`** (a multiple of `0.5`) | **`16`** | | Memory | MiB | Platform maximum or plan cap | **`256`** | **`32768`** | | Disk | MiB | Platform maximum | **`512`** | **`262144`** | ```python from daytona import Daytona from daytona.v2 import Resources daytona = Daytona() sandbox = daytona.v2.create( # memory and disk are GiB: 2 maps to memory_mib=2048, 20 to disk_mib=20480 resources=Resources(cpu=1, memory=2, disk=20, cpu_max=2, memory_max=4, disk_max=40), ) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | ------------------------------------------------------------------- | | `cpu` | float | Sets the guaranteed CPU in cores. | | `memory` | int | Sets the guaranteed memory in GiB. | | `disk` | int | Sets the guaranteed disk in GiB. | | `cpu_max` | float | Sets the CPU limit in cores, a multiple of `0.5`. | | `memory_max` | float | Sets the memory limit in GiB. | | `disk_max` | float | Sets the disk limit in GiB. | ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create({ // memory and disk are GiB: 2 maps to memory_mib=2048, 20 to disk_mib=20480 resources: { cpu: 1, memory: 2, disk: 20, cpuMax: 2, memoryMax: 4, diskMax: 40 }, }) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | ------------------------------------------------------------------- | | `cpu` | number | Sets the guaranteed CPU in cores. | | `memory` | number | Sets the guaranteed memory in GiB. | | `disk` | number | Sets the guaranteed disk in GiB. | | `cpuMax` | number | Sets the CPU limit in cores, a multiple of `0.5`. | | `memoryMax` | number | Sets the memory limit in GiB. | | `diskMax` | number | Sets the disk limit in GiB. | ```bash # --memory, --disk, --memory-max, and --disk-max are MiB daytona sandbox create --cpu 1 --memory 2048 --disk 20480 \ --cpu-max 2 --memory-max 4096 --disk-max 40960 ``` | **Flag** | **Type** | **Description** | | -------------- | -------- | ------------------------------------------------------------------- | | `--cpu` | float | Sets the guaranteed CPU in cores. | | `--memory` | int | Sets the guaranteed memory in MiB. | | `--disk` | int | Sets the guaranteed disk in MiB. | | `--cpu-max` | float | Sets the CPU limit in cores, a multiple of `0.5`. | | `--memory-max` | int | Sets the memory limit in MiB. | | `--disk-max` | int | Sets the disk limit in MiB. | ```bash curl 'https://api.daytona.com/sandboxes' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "cpu": 1, "memory_mib": 2048, "disk_mib": 20480, "cores_max": 2, "memory_max_mib": 4096, "disk_max_mib": 40960 }' ``` | **Field** | **Type** | **Description** | | ---------------- | -------- | ---------------------------------------------------------------- | | `cpu` | number | Sets the guaranteed CPU in cores. | | `memory_mib` | integer | Sets the guaranteed memory in MiB. | | `disk_mib` | integer | Sets the guaranteed disk in MiB. | | `cores_max` | number | Sets the CPU limit in cores, a multiple of `0.5`. | | `memory_max_mib` | integer | Sets the memory limit in MiB. | | `disk_max_mib` | integer | Sets the disk limit in MiB. | ## Regions [#regions] Every sandbox runs in a [region](/docs/regions), a geographic or logical group of compute infrastructure. A create request can name a region, and Daytona places the sandbox on available capacity inside it. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create(region="earth") ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create({ region: 'earth' }) ``` ```bash daytona sandbox create --region earth ``` ```bash curl 'https://api.daytona.com/sandboxes' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "region_id": "earth" }' ``` ## Hardware virtualization [#hardware-virtualization] Server processors include instructions for running virtual machines directly on the hardware. A virtual machine monitor uses these instructions to create a guest with its own virtual processors, memory, and devices. The processor rejects any access from a guest to host memory or to another guest's memory. Linux, Windows, and macOS sandboxes run as virtual machines, each on the virtual machine monitor that its operating system needs. | **Sandbox** | **Host** | **Runtime** | | ----------------------------------------- | ---------------------- | ---------------------------------------- | | [**Linux**](/docs/linux-sandboxes) | Linux with KVM | Firecracker virtual machine | | [**Windows**](/docs/windows-sandboxes) | Linux with KVM | Cloud Hypervisor virtual machine | | [**macOS**](/docs/macos-sandboxes) | Mac with Apple silicon | Virtualization framework virtual machine | **Linux** exposes the processor's virtualization through the Kernel-based Virtual Machine (KVM). Linux sandboxes run on Firecracker, a virtual machine monitor built to run many small, short-lived virtual machines on one host. Firecracker provides only the devices a server needs: virtual disks, a network card, and a serial console. Each Linux sandbox runs as one Firecracker process on a host, in its own network namespace, with its own virtual processors and memory. **Windows** sandboxes also use KVM, but Firecracker does not support Windows guests. Windows sandboxes run on **Cloud Hypervisor**, a virtual machine monitor that also keeps its device model small but can start an operating system from firmware. Each Windows sandbox runs as one Cloud Hypervisor process on a host, in its own network namespace, with its own virtual processors and memory. Cloud Hypervisor provides each Windows sandbox with the following: - UEFI firmware, which loads the Windows boot manager from the sandbox's disk - Hyper-V enlightenments: interfaces Windows uses to run efficiently as a guest - Virtual disks and a virtual network card, for which the base image carries Windows drivers - A serial console for management, and no graphics card **macOS sandboxes** run on Macs, because Apple's license allows macOS virtual machines only on Apple hardware. Apple silicon includes hardware support for virtual machines, which macOS exposes through Apple's Virtualization framework. Each macOS sandbox runs as its own virtual machine on its Mac, with its own virtual processors, memory, disk, and network card. ## Sandbox lifecycle [#sandbox-lifecycle] Every sandbox moves through a lifecycle. A sandbox can have several different states. Each state reflects the status of your sandbox. A sandbox transitions between states in response to user actions, or automatically when one of its timeouts elapses. See the lifecycle of [Linux](/docs/linux-sandboxes#lifecycle), [Windows](/docs/windows-sandboxes), [GPU](/docs/gpu-sandboxes), and [macOS](/docs/macos-sandboxes#lifecycle) sandboxes. | **Feature** | **Linux** | **Windows** | **macOS** | **GPU** | | -------------------------- | --------------- | ---------------- | ---------------- | ------------ | | **Stop and start** | ✗ | ✓ persistent | ✓ persistent | ✗ | | **Pause and resume** | ✗ | ✗ | ✓ persistent | ✗ | | **Fork** | ✗ | ✗ | ✓ persistent | ✗ | | **Delete** | ✓ | ✓ | ✓ | ✓ | | **Filesystem persistence** | ✗ | ✓ | ✓ | ✗ | | **Memory persistence** | ✗ | ✗ | ✓ persistent | ✗ | | **Memory snapshot** | ✓ warm template | ✗ | ✗ | ✓ checkpoint | | **Filesystem snapshot** | ✓ | ✓ block snapshot | ✓ persistent | ✗ | | **Spot (Preemption)** | ✓ | ✓ | ✗ | ✗ | | **Network policy** | ✓ | ✗ | ✓ | ✗ | | **Desktop** | ✓ | ✓ RDP | ✓ Screen Sharing | ✗ | The following tables list the states of a Linux sandbox and the transitions between them. The SDKs report the states in the **State** column. The CLI and API report the more detailed status in the **API status** column. | **State** | **API status** | **Description** | | ---------------- | ------------------------------ | ------------------------------------------------------------------------------- | | **`queued`** | **`queued`** | The create request is recorded and waits to be published for placement. | | **`creating`** | **`pending`**, **`assigned`** | The create request is accepted, and the sandbox is queued for and placed on a host. | | **`starting`** | **`booting`** | The microVM is booting and will be ready to use. | | **`started`** | **`running`** | The sandbox is running and ready to accept requests. | | **`destroying`** | **`deleting`** | The sandbox is being deleted. | | **`destroyed`** | **`deleted`** | The sandbox and its storage are removed. | | **`error`** | **`failed`**, **`lost`** | The sandbox could not boot, hit an unrecoverable error, or its host was lost. | | **`unknown`** | | The SDK does not recognize the status the API reports. | A sandbox can transition between states in response to various actions. The following table lists the initial state, target state, and trigger for the transition. | **Initial state** | **Target state** | **Trigger** | | ----------------- | ---------------- | ---------------------------------------------------------------------------------- | | **`queued`** | **`creating`** | The create request is published for placement. | | **`creating`** | **`starting`** | The sandbox is placed on a host, the host prepares its image, and the microVM boots. | | **`starting`** | **`started`** | The sandbox finishes booting and accepts requests. | | any state | **`destroying`** | A delete is requested, a timeout elapses, or the platform reclaims a spot sandbox. | | **`destroying`** | **`destroyed`** | The sandbox is removed and its resources are released. | | any active state | **`error`** | The sandbox fails to boot, hits an unrecoverable error, or its host is lost. | ## Sandbox operations [#sandbox-operations] Daytona provides methods to manage existing sandboxes. Sandbox operations find sandboxes, read their current state and configuration, and update their metadata. They do not change the state of a sandbox or touch anything running inside it. To stop, pause, fork, or delete a sandbox, see [lifecycle](#sandbox-lifecycle). To run commands or work with files inside a sandbox, use the toolbox. ### List sandboxes [#list-sandboxes] List sandboxes in the project, page by page. Unfiltered lists read the region-local database, so new sandboxes appear at once. To filter by name, state, labels, or resources, use [search](#search-sandboxes). ```python from daytona import Daytona daytona = Daytona() page = daytona.v2.list() for sandbox in page.items: print(sandbox.id, sandbox.name, sandbox.state) ``` - The request requires the `read:sandboxes` permission. - `page.next_cursor` is `None` on the last page. - Pass `next_cursor` back as `cursor` for the next page. ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const page = await daytona.v2.list() for (const sandbox of page.items) { console.log(sandbox.id, sandbox.name, sandbox.state) } ``` - The request requires the `read:sandboxes` permission. - `page.nextCursor` is unset on the last page. - Pass `nextCursor` back as `cursor` for the next page. ```bash daytona sandbox list ``` | **Flag** | **Type** | **Description** | | ---------- | -------- | ----------------------------------- | | `--limit` | int | Sets the page size. The default is `100`. | | `--cursor` | string | Continues from a previous page. | ```bash curl 'https://api.daytona.com/sandboxes' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` | **Field** | **Type** | **Description** | | --------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | `limit` | integer | Sets the page size, from `1` to `200`. The default is `100`. | - The request requires the `read:sandboxes` permission. - Pass `next_cursor` from the response as `cursor` to read the next page. ##### Iterate over all sandboxes [#iterate-over-all-sandboxes] Iterate over every sandbox in the project without handling page cursors. The iterator fetches the next page when the current one is exhausted and stops when the server returns no cursor. ```python from daytona import Daytona daytona = Daytona() for sandbox in daytona.v2.iter(): print(sandbox.id, sandbox.name, sandbox.state) ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() for await (const sandbox of daytona.v2.iter()) { console.log(sandbox.id, sandbox.name, sandbox.state) } ``` ```bash # Follow every page until the server returns no cursor daytona sandbox list --all ``` ### Search sandboxes [#search-sandboxes] Search sandboxes across every region. Search reads a central index that is eventually consistent: a create, update, or delete becomes searchable about 2 to 3 seconds after it is committed, so a sandbox created a moment ago may be missing. To read your own writes, use [list](#list-sandboxes) without filters or [get](#get-a-sandbox). Filters combine with AND, and deleted sandboxes are left out of the results. ```python from daytona import Daytona daytona = Daytona() # Free text over name and image, or an exact sandbox id page = daytona.v2.search(q="my-sandbox") for sandbox in page.items: print(sandbox.id, sandbox.name, sandbox.state) ``` | **Parameter** | **Type** | **Description** | | ------------- | --------------- | --------------------------------------------------------------------------------------- | | `status` | Sequence\[str\] | Filters by state. Pass API state names such as `running`, not the SDK names returned in `sandbox.state`. | The response has the following fields: | **Field** | **Description** | | ----------------- | ---------------------------------------------------------------------------------------- | | `next_cursor` | The cursor is tied to the filters and sort of its call. | | `partial_regions` | Lists the regions that are backfilling. Results from these regions can be incomplete. | ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() // Free text over name and image, or an exact sandbox id const page = await daytona.v2.search({ q: 'my-sandbox' }) for (const sandbox of page.items) { console.log(sandbox.id, sandbox.name, sandbox.state) } ``` | **Parameter** | **Type** | **Description** | | ------------- | ------------------------------ | --------------------------------------------------------------------------------- | | `status` | string \| readonly string\[\] | Filters by state. Pass API state names such as `running`, not the SDK names returned in `sandbox.state`. | The response has the following fields: | **Field** | **Description** | | ---------------- | ---------------------------------------------------------------------------------------- | | `nextCursor` | The cursor is tied to the filters and sort of its call. | | `partialRegions` | Lists the regions that are backfilling. Results from these regions can be incomplete. | ```bash # Free text over name and image, or an exact sandbox id daytona sandbox search my-sandbox ``` | **Flag** | **Type** | **Description** | | ---------- | -------- | ---------------------------------------------------------- | | `--status` | string | Repeatable or comma-separated. Matches any listed value. | | `--class` | string | Repeatable or comma-separated. Matches any listed value. | - The request requires the `read:sandboxes` permission. - The query is optional. - Filter flags such as `--status`, `--class`, `--name-prefix`, and `--labels` select sandboxes on their own or narrow the query. ```bash # Free text over name and image, or an exact sandbox id curl 'https://api.daytona.com/sandboxes/search?q=my-sandbox' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` | **Field** | **Type** | **Description** | | --------- | --------- | ------------------------------------- | | `limit` | integer | Sets the page size, from `1` to `200`. The default is `100`. | | `sort` | string | Sets the sort field. The default is `created_at`. | | `order` | string | Sets the sort order. The default is `desc`. | - The request requires the `read:sandboxes` permission. - A `cursor` is tied to the filters and sort of its request. ### Get a sandbox [#get-a-sandbox] Get a sandbox by its ID. The response includes the current state, resources, labels, and lifecycle settings. Get reads the control plane directly, so it reflects changes immediately, unlike [search](#search-sandboxes). ```python from daytona import Daytona daytona = Daytona() # Fetch the sandbox from the control plane sandbox = daytona.v2.get("{sandboxId}") print(sandbox.state, sandbox.cpu, sandbox.memory, sandbox.disk) # Store the sandbox data as JSON; it carries no URL or credential saved = sandbox.to_json() # {"sandboxId": "...", "name": "...", "state": "...", ...} # Later, get the sandbox again by its ID sandbox = daytona.v2.get(saved["sandboxId"]) ``` The response has the following fields: | **Field** | **Description** | | --------- | ------------------------------------------------------------------------------------------- | | `memory` | Gives the memory in GiB, rounded up to a whole GiB. The API reports memory in MiB as `memory_mib`. | | `disk` | Gives the disk in GiB, rounded up to a whole GiB. The API reports disk in MiB as `disk_mib`. | ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() // Fetch the sandbox from the control plane const sandbox = await daytona.v2.get('{sandboxId}') console.log(sandbox.state, sandbox.cpu, sandbox.memory, sandbox.disk) // Store the sandbox data as JSON; it carries no URL or credential const saved = sandbox.toJSON() // { sandboxId: '...', name: '...', state: '...', ... } // Later, get the sandbox again by its ID const again = await daytona.v2.get(saved.sandboxId) ``` The response has the following fields: | **Field** | **Description** | | --------- | ------------------------------------------------------------------------------------------- | | `memory` | Gives the memory in GiB, rounded up to a whole GiB. The API reports memory in MiB as `memory_mib`. | | `disk` | Gives the disk in GiB, rounded up to a whole GiB. The API reports disk in MiB as `disk_mib`. | ```bash daytona sandbox get {sandboxId} ``` ```bash curl 'https://api.daytona.com/sandboxes/{sandboxId}' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ##### Refresh a sandbox [#refresh-a-sandbox] Refresh a sandbox object with its current data. A sandbox object keeps the fields from the request that returned it, so its state, resources, and labels can be out of date after a change made by another client. Refresh reads the sandbox from the control plane and updates the object in place. Lifecycle operations such as start and stop refresh the object when they finish. ```python # Re-read the sandbox from the control plane sandbox.refresh_data() print(sandbox.state, sandbox.labels) ``` | **Parameter** | **Type** | **Description** | | ------------- | --------- | ---------------------------------------------------------------------------------- | | `timeout` | float | Sets the request timeout in seconds. By default, the client request timeout applies. | ```typescript // Re-read the sandbox from the control plane await sandbox.refreshData() console.log(sandbox.state, sandbox.labels) ``` ### Find sandboxes by name [#find-sandboxes-by-name] Find sandboxes by the name they were created with. Names are not unique, so the result is a list, newest first, and it is empty when no sandbox matches. The lookup reads the [search](#search-sandboxes) index, so a sandbox created a moment ago can be missing. The name is stored as the name label. Replacing a sandbox's labels without it removes the sandbox from name lookups. ```python from daytona import Daytona daytona = Daytona() # Reuse a named sandbox, or create it when none exists found = daytona.v2.find_by_name("my-sandbox") sandbox = found[0] if found else daytona.v2.create(name="my-sandbox") ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------------------------------------------------------------------------------------------- | | `name` | str | Matches the sandbox name exactly. This parameter is required. A blank name raises `BadRequestError` before the request is sent. | | `region` | str | Sets the region to search. `"local"` or omitting it means the region of the API host. | ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() // Reuse a named sandbox, or create it when none exists const found = await daytona.v2.findByName('my-sandbox') const sandbox = found[0] ?? (await daytona.v2.create({ name: 'my-sandbox' })) ``` | **Parameter** | **Type** | **Description** | | ---------------- | -------- | --------------------------------------------------------------------------------------------------- | | `name` | string | Required. Exact match. A blank name throws `DaytonaError` before the request is sent. | | `options.region` | string | Sets the region to search. `'local'` or omitting it means the region of the API host. | ```bash # Search by the name label: labels={"name":"my-sandbox"} curl 'https://api.daytona.com/sandboxes/search?labels=%7B%22name%22%3A%22my-sandbox%22%7D' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ### Create an access token [#create-an-access-token] Create a short-lived access token for one sandbox. The token reaches the sandbox toolbox, SSH, desktop, and private preview ports, and can stop, pause, or delete the sandbox, limited to the operations and ports you grant. Give it to a collaborator, a CI job, or a browser instead of a project API key. The token lasts one hour by default and at most 24 hours. It cannot be refreshed, revoked, or used to create other credentials. Create a new token when it expires. ```python # Grant file system and SSH access for 15 minutes token = sandbox.create_access_token(operations=["toolbox:fs", "ssh"], ttl_seconds=900) print(token.access_token, token.expires_at) ``` | **Parameter** | **Type** | **Description** | | ------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `operations` | Sequence\[str\] | Lists the operations the token grants. Each operation is one of `toolbox`, `toolbox:exec`, `toolbox:fs`, `toolbox:git`, `toolbox:lsp`, `desktop`, `ssh`, `sandbox:stop`, `sandbox:pause`, or `sandbox:delete`. `[]` grants preview ports only. The default is every operation the API key can grant. Granting `sandbox:delete` requires the `delete:sandboxes` permission. | | `ports` | Sequence\[int\] | Sets the private preview ports that the token can reach. `[]` grants none. The default is all ports. | | `ttl_seconds` | int | Sets the token lifetime in seconds, at most `86400`. The default is `3600`. | ```typescript // Grant file system and SSH access for 15 minutes const token = await sandbox.createAccessToken({ operations: ['toolbox:fs', 'ssh'], ttlSeconds: 900 }) console.log(token.accessToken, token.expiresAt) ``` | **Parameter** | **Type** | **Description** | | ------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `operations` | string\[\] | Lists the operations the token grants. Each operation is one of `toolbox`, `toolbox:exec`, `toolbox:fs`, `toolbox:git`, `toolbox:lsp`, `desktop`, `ssh`, `sandbox:stop`, `sandbox:pause`, or `sandbox:delete`. `[]` grants preview ports only. The default is every operation the API key can grant. Granting `sandbox:delete` requires the `delete:sandboxes` permission. | | `ports` | number\[\] | Sets the private preview ports that the token can reach. `[]` grants none. The default is all ports. | | `ttlSeconds` | number | Sets the token lifetime in seconds, at most `86400`. The default is `3600`. | ```bash # Grant file system and SSH access for 15 minutes curl 'https://api.daytona.com/sandboxes/{sandboxId}/access-token' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{"operations": ["toolbox:fs", "ssh"], "ttl_seconds": 900}' ``` | **Field** | **Type** | **Description** | | ------------ | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `operations` | string\[\] | Sets the operations that the token grants: any of `toolbox`, `toolbox:exec`, `toolbox:fs`, `toolbox:git`, `toolbox:lsp`, `desktop`, `ssh`, `sandbox:stop`, `sandbox:pause`, and `sandbox:delete`. `[]` grants preview ports only. The default is every operation that the API key can grant. | | `ports` | integer\[\] | Sets the private preview ports that the token can reach, from `1` to `65535`, at most 128. `[]` grants none. The default is all ports. | | `ttl_seconds` | integer | Sets the token lifetime in seconds, at most `86400`. The default is `3600`. | The response has the following fields: | **Field** | **Description** | | -------------- | ------------------------------------------------------------------------------------------------ | | `access_token` | The access token. | | `token_type` | The token type is `Bearer`. | | `expires_at` | The time when the token expires. | | `operations` | The operations that the token grants. | | `ports` | Lists the private preview ports the token can reach. The value is `null` when every port is granted. | ### Label sandboxes [#label-sandboxes] Update a sandbox's labels. Labels are key-value strings for organizing sandboxes, and you can filter by them when you [list](#list-sandboxes) or [search](#search-sandboxes). An update replaces the full label set; omitted labels are removed. A sandbox holds at most 100 labels, each key and value at most 512 bytes. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() # Replace the full label set labels = sandbox.set_labels({"team": "research"}) print(labels) ``` | **Parameter** | **Type** | **Description** | | ------------- | ---------------- | ------------------------------------------------------- | | `labels` | Mapping\[str, str\] | Replaces the full label set. `{}` removes all labels. This parameter is required and positional only. | ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() // Replace the full label set const labels = await sandbox.setLabels({ team: 'research' }) console.log(labels) ``` | **Parameter** | **Type** | **Description** | | ------------- | ------------------------ | ------------------------------------ | | `labels` | Record\ | Replaces the full label set. `{}` removes all labels. This parameter is required. | ```bash # Replace the full label set daytona sandbox update {sandboxId} --label team=research ``` | **Flag** | **Type** | **Description** | | ---------------- | -------- | -------------------------------------------- | | `--label` | string | Repeatable, one `key=value` pair per flag. | | `--clear-labels` | bool | Removes all labels. | ```bash # Replace the full label set curl 'https://api.daytona.com/sandboxes/{sandboxId}/labels' \ --request PUT \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "labels": { "team": "research" } }' ``` | **Field** | **Type** | **Description** | | --------- | -------- | --------------------------- | | `labels` | object | Replaces the full label set. `{}` removes all labels. A sandbox holds at most 100 labels. Each key and value is at most 512 bytes. | ### Metrics [#metrics] Read the current CPU, memory, and disk usage of a running sandbox. The toolbox measures each value inside the sandbox and returns one snapshot per request. Memory in use excludes memory the operating system can reclaim on demand, such as the file cache. Disk usage is measured on the filesystem that holds the sandbox working directory. CPU utilization is the share of total CPU capacity in use across all CPUs since the previous metrics request to the sandbox, from any client. The first request after the toolbox starts measures over about 100 milliseconds. ```python metrics = sandbox.metrics() print(metrics.cpu_utilization, metrics.memory_usage_bytes, metrics.disk_usage_bytes) ``` The response has the following fields: | **Field** | **Description** | | -------------------- | ------------------------------------------------------------------------ | | `timestamp` | The time of the snapshot, as an RFC 3339 UTC timestamp. | | `cpu_count` | The number of logical CPUs visible inside the sandbox. | | `cpu_utilization` | The fraction of total CPU capacity in use, from `0` to `1`. | | `memory_usage_bytes` | The memory in use, in bytes. | | `memory_total_bytes` | The total memory, in bytes. | | `disk_usage_bytes` | The used space on the working directory filesystem, in bytes. | | `disk_total_bytes` | The total space on the working directory filesystem, in bytes. | ```typescript const metrics = await sandbox.metrics() console.log(metrics.cpuUtilization, metrics.memoryUsageBytes, metrics.diskUsageBytes) ``` The response has the following fields: | **Field** | **Description** | | ------------------ | ------------------------------------------------------------------------ | | `timestamp` | The time of the snapshot, as an RFC 3339 UTC timestamp. | | `cpuCount` | The number of logical CPUs visible inside the sandbox. | | `cpuUtilization` | The fraction of total CPU capacity in use, from `0` to `1`. | | `memoryUsageBytes` | The memory in use, in bytes. | | `memoryTotalBytes` | The total memory, in bytes. | | `diskUsageBytes` | The used space on the working directory filesystem, in bytes. | | `diskTotalBytes` | The total space on the working directory filesystem, in bytes. | ```bash curl '{toolboxProxyUrl}/{sandboxId}/system/metrics' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` The response has the following fields: | **Field** | **Description** | | ------------------ | ------------------------------------------------------------------------ | | `timestamp` | The time of the snapshot, as an RFC 3339 UTC timestamp. | | `cpuCount` | The number of logical CPUs visible inside the sandbox. | | `cpuUtilization` | The fraction of total CPU capacity in use, from `0` to `1`. | | `memoryUsageBytes` | The memory in use, in bytes. | | `memoryTotalBytes` | The total memory, in bytes. | | `diskUsageBytes` | The used space on the working directory filesystem, in bytes. | | `diskTotalBytes` | The total space on the working directory filesystem, in bytes. | - The request requires the `write:sandboxes` permission. - `{toolboxProxyUrl}` is the `toolbox_proxy_url` field of the [sandbox](/docs/sandboxes#get-a-sandbox). ### Logs [#logs] Read the serial console log of a sandbox. For a running sandbox the log is read live from its runner; for a sandbox in any other state the persisted log is returned. ```bash # Serial console log of the microVM daytona sandbox logs {sandboxId} ``` | **Flag** | **Type** | **Description** | | -------------- | -------- | ------------------------------------------------------- | | `--follow` | bool | Polls for new log output until interrupted. | | `--entrypoint` | bool | Reads the entrypoint logs instead of the serial console. | ```bash # Serial console log of the microVM curl 'https://api.daytona.com/sandboxes/{sandboxId}/console-logs' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ##### Entrypoint logs [#entrypoint-logs] Read the log of the sandbox entrypoint process as text. For a running sandbox the log is read live; for a sandbox in any other state the persisted log is returned. To page through the log or follow it, read the [entrypoint process](/docs/process-execution#entrypoint-process) through the toolbox. ```python print(sandbox.entrypoint_logs()) ``` ```typescript console.log(await sandbox.entrypointLogs()) ``` ```bash daytona sandbox logs {sandboxId} --entrypoint ``` ```bash curl 'https://api.daytona.com/sandboxes/{sandboxId}/logs' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ##### Build logs [#build-logs] Read the output of the image build behind a sandbox. A sandbox has a build log when its image is built from a Dockerfile, including a build that failed before the sandbox was placed; a sandbox created from a registry image has none. When the sandbox reuses an image built earlier, the log is the output of that original build. Following the log streams output while the build runs and ends when the build finishes. Stopping the reader does not stop the build. To read the log of an image without a sandbox, see [image build logs](/docs/images#build-logs). ```python from daytona import Daytona from daytona.v2 import ImageBuilder daytona = Daytona() sandbox = daytona.v2.create_from_build(ImageBuilder.from_dockerfile("FROM python:3.12-slim")) # Output retained so far, as text print(sandbox.build_logs()) # Stream output until the build finishes result = sandbox.follow_build_logs(on_logs=lambda chunk: print(chunk, end="")) print(result.status, result.reason) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | ------------------------------------------------------------------- | | `on_logs` | Callable\[\[str\], None\] | Receives each chunk of decoded output. This parameter is required. | | `cursor` | str | Resumes after the output a previous follow returned in `cursor`. | | `timeout` | float | Sets the follow limit in seconds. By default, there is no limit. | The response has the following fields: | **Field** | **Description** | | ----------------- | --------------------------------------------------------------------------------------- | | `status` | The status of the build. | | `reason` | The value is `terminal`, `deadline`, `not_applicable`, or `resource_deleted`. | | `output_complete` | Whether the build output is complete. | | `cursor` | Pass this value as `cursor` to resume after this output. | ```typescript import { Daytona } from '@daytona/sdk' import { ImageBuilder } from '@daytona/sdk/v2' const daytona = new Daytona() const sandbox = await daytona.v2.createFromBuild(ImageBuilder.fromDockerfile('FROM python:3.12-slim')) // Output retained so far, as text console.log(await sandbox.buildLogs()) // Stream output until the build finishes const result = await sandbox.followBuildLogs({ onLogs: (chunk) => { process.stdout.write(chunk) } }) console.log(result.status, result.reason) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | ------------------------------------------------------------------------------------------------ | | `onLogs` | (chunk: string) => unknown | Receives each chunk of decoded output. This parameter is required. | | `cursor` | string | Resumes after the output a previous follow returned in `cursor`. | | `timeoutSeconds` | number | Sets the follow limit in seconds. By default, there is no limit. | The response has the following fields: | **Field** | **Description** | | ---------------- | --------------------------------------------------------------------------------------- | | `status` | The status of the build. | | `reason` | The value is `terminal`, `deadline`, `not_applicable`, or `resource_deleted`. | | `outputComplete` | Whether the build output is complete. | | `cursor` | Pass this value as `cursor` to resume after this output. | ```bash BUILD_LOGS_URL=$(curl 'https://api.daytona.com/sandboxes/{sandboxId}/build-logs-url' \ --header 'Authorization: Bearer YOUR_API_KEY' | jq -r '.url') # Output retained so far, as text curl "$BUILD_LOGS_URL?follow=false&format=text" \ --header 'Authorization: Bearer YOUR_API_KEY' # Stream output until the build finishes curl --no-buffer "$BUILD_LOGS_URL?follow=true&format=sse" \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: text/event-stream' ``` ## Permissions [#permissions] Sandboxes are scoped to a project. An API key reaches only the sandboxes of its own project. Access is governed by three permissions, which you can grant to an [organization role](/docs/organizations#roles) or an [API key](/docs/api-keys). Setting, changing, or clearing a delete action in a lifecycle policy also requires the permission to delete sandboxes, and so does creating an access token that can delete the sandbox. Attaching secrets when creating a sandbox requires the permission to read secrets. The [audit logs](/docs/audit-logs) record sandbox creates, lifecycle changes, deletes, and access token creation. | **Permission** | **Grants** | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | **`read:sandboxes`** | List, search, and get sandboxes, and read their logs, usage, and exposed ports | | **`write:sandboxes`** | Create, start, stop, pause, resume, fork, and label sandboxes, change their lifecycle policy, create access tokens, and use the toolbox | | **`delete:sandboxes`** | Delete sandboxes | # Linux Sandboxes (/docs/linux-sandboxes) Linux sandboxes are **Linux virtual machines (VMs)**. Each sandbox is a virtual machine, a microVM, that runs its own Linux kernel on shared physical hardware and has its own operating system, files, network connection, and fixed amount of processor, memory, and disk. The hardware enforces the boundary and isolation between sandboxes. | **Term** | **Description** | | -------------- | -------------------------------------------------------------------------------------------------------------- | | **Sandbox** | An isolated Linux machine created on demand to run code. | | **Host** | The physical server that runs many sandboxes at once. Daytona calls these servers runners. | | **Guest** | The operating system running inside a sandbox, as opposed to the operating system of the host. | | **Kernel** | The core of an operating system. It manages memory, processes, files, and devices. | | **Hypervisor** | Software on the host that creates virtual machines and keeps them separated from each other and from the host. | | **Image** | A packaged filesystem that defines what software a sandbox starts with. | | **Snapshot** | A saved copy of a sandbox's memory and disk that new sandboxes resume from. | | **Spot** | A sandbox that runs on discounted capacity that Daytona can reclaim at any time. | ## Use cases [#use-cases] Sandboxes are used wherever code must run in a real environment, but you cannot trust the code or you cannot afford for it to affect anything else. - **Code execution for AI agents.** An agent writes code, runs it in a sandbox, reads the output, and decides what to do next. The sandbox gives the agent a real shell and filesystem while keeping its actions away from your infrastructure. Once the agent is done, a [delete](#delete) discards the sandbox's filesystem and memory. - **Coding agents.** An agent clones a repository, installs dependencies, edits files, runs the test suite, and opens a pull request, all inside one sandbox. The sandbox keeps its filesystem on its host until it is deleted. A [filesystem snapshot](#filesystem-snapshot) saves that filesystem as an image, and new sandboxes boot from it with the captured files. - **Reinforcement learning (RL).** Training runs create very large numbers of identical environments, run one episode in each, score the result, and discard the environment. Fast creation from a shared snapshot keeps the cost of each environment low. A restored sandbox resumes the captured processes and memory instead of booting. - **Untrusted user code.** Online coding platforms, grading systems, and plugin hosts run code submitted by users without exposing other users or the service. Each sandbox is a microVM with its own Linux kernel. The hardware enforces the boundary between sandboxes. - **Development environments.** A developer gets a preconfigured machine from an image, connects over SSH or from an editor, and previews web applications through a URL. Requests through SSH, VNC, and preview URLs count as activity for the idle timeout. A [reset of the idle timer](#reset-the-idle-timer) keeps the sandbox alive during work that Daytona does not count as activity. ## Create a Linux sandbox [#create-a-linux-sandbox] Create a Linux sandbox from the dashboard or programmatically. 1. Go to [Daytona Sandboxes ↗](https://app.daytona.com/dashboard/sandboxes) 2. Click 3. Select 4. Click ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() ``` The following example sets the remaining parameters: ```python from daytona import Daytona from daytona.v2 import PortMapping, Resources daytona = Daytona() sandbox = daytona.v2.create( name="my-sandbox", labels={"team": "research", "run": "42"}, resources=Resources(cpu=2, memory=4, disk=20), ports=[PortMapping(port=8080), PortMapping(port=5353, proto="udp")], network_policy={"block_all": True, "allow_domains": ["pypi.org", "*.github.com"]}, env={"LOG_LEVEL": "debug"}, secrets=["GITHUB_TOKEN"], spot=False, cpu_arch="amd64", cpu_type="zen5", lifecycle_policy={ "idle_expiry_seconds": 3600, "on_idle_timeout": "delete", "timeout_seconds": 604800, "on_timeout": "delete", }, idempotency_key="run-42-create", wait_seconds=120, ) ``` | **Parameter** | **Type** | **Description** | | ----------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `image` | str | Sets the registered image that the sandbox starts from, by name or `img_` ID. This is the first positional argument. If omitted, the sandbox boots the platform default image, the platform image whose `default` field is `true` in the [image list](/docs/images#list-images). When no default image is set, the request returns a 400 error. | | `name` | str | Sets the display name. If omitted, a name is generated. Within one [workload cell](/docs/regions), a create with the same name and different arguments is refused until the first sandbox is deleted. The name is also stored as the `name` label. | | `labels` | Dict\[str, str\] | Attaches key-value metadata to the sandbox. | | `user` | str | Sets the default OS user inside the sandbox. The default is the image's `USER`, or `root` if the image sets none, sets root, or sets a numeric user ID. | | `resources` | Resources | Sets the sandbox size. `cpu` sets the guaranteed CPU cores as a float, raised to at least 0.125; the value is raised to at least one core per 8 GiB of guaranteed memory, and if omitted it is one core per 8 GiB of guaranteed memory, and at least 0.5: 0.5 with the default 1 GiB. `memory` sets the guaranteed memory in GiB, raised to at least 0.5 GiB, default 1 GiB. `disk` sets the guaranteed writable disk in GiB, default 512 MiB. When `cpu`, `memory`, or `disk` is set, the disk is raised to at least 10 GiB. `cpu_max` sets the CPU limit in cores as a multiple of 0.5, which defaults to the system or plan cap. `memory_max` sets the memory limit in GiB, from 0.25 to 32, which defaults to 32. If `memory` is omitted, the guaranteed memory is lowered to the limit. If `memory` is set, a guaranteed memory above the limit, after the raise to 0.5 GiB, is refused. `disk_max` sets the writable disk limit in GiB. Memory and disk must convert to a whole number of MiB. | | `ports` | Sequence\[PortMapping\] | Forwards inbound ports to the sandbox. Each mapping has a `port` and a `proto`, which defaults to `tcp`. | | `volumes` | Sequence\[VolumeMount\] | Attaches volumes to the sandbox. See [attach volumes](/docs/volumes#attach-volumes). | | `env` | Dict\[str, str\] | Sets environment variables inside the sandbox. | | `secrets` | Sequence\[str\] | Attaches project secrets by name. The sandbox sees each secret as an opaque placeholder. A name that is not a secret of the project is refused. | | `network_policy` | NetworkPolicyInput | Sets the outbound network policy with `block_all`, `allow_domains`, and `allow_cidrs`. `allow_domains` implies `block_all`. `allow_cidrs` restricts egress only together with `block_all` or `allow_domains`. A `*.` wildcard domain matches subdomains only, so list the parent domain separately. A create with a policy is refused when no runner in the region can enforce it for the sandbox's CPU architecture and type. You can [change it](/docs/network-limits#update-network-policy) after create. | | `spot` | bool | Runs the sandbox on discounted capacity that can be reclaimed. The default is `False`. | | `region` | str | Sets the region, any listed region including `earth`. The default is the project's default region, then the organization's, then `earth`. A create in a region with no online Linux runner is refused. | | `cpu_arch` | str | Sets the CPU architecture, `amd64` or `arm64`. The default is the region's default architecture, or `amd64` if the region sets none. A create with an architecture that no runner in the region provides is refused, or waits until its create deadline. | | `cpu_type` | str | Sets the CPU hardware tier slug: `zen3`, `zen4`, `zen5`, `zen5c`, `arrowlake1`, `arrowlake2`, `graviton`, `graviton3`, and `graviton4`. The slug also sets the architecture. A create with a type that no runner in the region serves, itself or as a fallback, is refused, or waits until its create deadline. See [CPU types](#cpu-types). | | `lifecycle_policy` | LifecyclePolicyOptions | Sets the lifecycle policy with `timeout_seconds` and `on_timeout`, and `idle_expiry_seconds` and `on_idle_timeout`. The action is `delete`. By default, there is no idle timeout unless the project sets one, and the wall-clock timeout uses the project or platform default, if one is enabled. | | `idempotency_key` | str | Makes a retried create in the same workload cell return the same sandbox. A create in another cell makes a separate sandbox. To keep creates in one region, set `region`. If `name` is set, the key is derived from it. Otherwise, each call generates a new key. | | `create_timeout_seconds` | int | Sets how many seconds the sandbox has to reach running before it is deleted. `-1` sets the maximum, 86400. The default is the server default, 3600. | | `wait_seconds` | int | Sets how many seconds create waits for the sandbox to start. The server holds the request for up to 3 seconds, and the SDK waits for the rest. `0` returns immediately. The default is 60. If the sandbox has not started in time, or fails, `create()` returns it without raising. Check `sandbox.state` before using it. | ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() ``` The following example sets the remaining parameters: ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create({ name: 'my-sandbox', labels: { team: 'research', run: '42' }, resources: { cpu: 2, memory: 4, disk: 20 }, ports: [{ port: 8080 }, { port: 5353, proto: 'udp' }], networkPolicy: { blockAll: true, allowDomains: ['pypi.org', '*.github.com'] }, env: { LOG_LEVEL: 'debug' }, secrets: ['GITHUB_TOKEN'], spot: false, cpuArch: 'amd64', cpuType: 'zen5', lifecyclePolicy: { idleExpirySeconds: 3600, onIdleTimeout: 'delete', timeoutSeconds: 604800, onTimeout: 'delete', }, idempotencyKey: 'run-42-create', waitSeconds: 120, }) ``` | **Parameter** | **Type** | **Description** | | ---------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `image` | string | Sets the registered image that the sandbox starts from, by name or `img_` ID. This is the first positional argument. If omitted, the sandbox boots the platform default image, the platform image whose `default` field is `true` in the [image list](/docs/images#list-images). When no default image is set, the request returns a 400 error. | | `name` | string | Sets the display name. If omitted, a name is generated. Within one [workload cell](/docs/regions), a create with the same name and different arguments is refused until the first sandbox is deleted. The name is also stored as the `name` label. | | `labels` | Record\ | Attaches key-value metadata to the sandbox. | | `user` | string | Sets the default OS user inside the sandbox. The default is the image's `USER`, or `root` if the image sets none, sets root, or sets a numeric user ID. | | `resources` | Resources | Sets the sandbox size. `cpu` sets the guaranteed CPU cores as a float, raised to at least 0.125; the value is raised to at least one core per 8 GiB of guaranteed memory, and if omitted it is one core per 8 GiB of guaranteed memory, and at least 0.5: 0.5 with the default 1 GiB. `memory` sets the guaranteed memory in GiB, raised to at least 0.5 GiB, default 1 GiB. `disk` sets the guaranteed writable disk in GiB, default 512 MiB. When `cpu`, `memory`, or `disk` is set, the disk is raised to at least 10 GiB. `cpuMax` sets the CPU limit in cores as a multiple of 0.5, which defaults to the system or plan cap. `memoryMax` sets the memory limit in GiB, from 0.25 to 32, which defaults to 32. If `memory` is omitted, the guaranteed memory is lowered to the limit. If `memory` is set, a guaranteed memory above the limit, after the raise to 0.5 GiB, is refused. `diskMax` sets the writable disk limit in GiB. Memory and disk must convert to a whole number of MiB. | | `ports` | PortMapping\[\] | Forwards inbound ports to the sandbox. Each mapping has a `port` and a `proto`, which defaults to `tcp`. | | `volumes` | VolumeMount\[\] | Attaches volumes to the sandbox. See [attach volumes](/docs/volumes#attach-volumes). | | `env` | Record\ | Sets environment variables inside the sandbox. | | `secrets` | string\[\] | Attaches project secrets by name. The sandbox sees each secret as an opaque placeholder. A name that is not a secret of the project is refused. | | `networkPolicy` | NetworkPolicyInput | Sets the outbound network policy with `blockAll`, `allowDomains`, and `allowCidrs`. `allowDomains` implies `blockAll`. `allowCidrs` restricts egress only together with `blockAll` or `allowDomains`. A `*.` wildcard domain matches subdomains only, so list the parent domain separately. A create with a policy is refused when no runner in the region can enforce it for the sandbox's CPU architecture and type. You can [change it](/docs/network-limits#update-network-policy) after create. | | `spot` | boolean | Runs the sandbox on discounted capacity that can be reclaimed. The default is `false`. | | `region` | string | Sets the region, any listed region including `earth`. The default is the project's default region, then the organization's, then `earth`. A create in a region with no online Linux runner is refused. | | `cpuArch` | CpuArch | Sets the CPU architecture, `amd64` or `arm64`. The default is the region's default architecture, or `amd64` if the region sets none. A create with an architecture that no runner in the region provides is refused, or waits until its create deadline. | | `cpuType` | string | Sets the CPU hardware tier slug: `zen3`, `zen4`, `zen5`, `zen5c`, `arrowlake1`, `arrowlake2`, `graviton`, `graviton3`, and `graviton4`. The slug also sets the architecture. A create with a type that no runner in the region serves, itself or as a fallback, is refused, or waits until its create deadline. See [CPU types](#cpu-types). | | `lifecyclePolicy` | LifecyclePolicyOptions | Sets the lifecycle policy with `timeoutSeconds` and `onTimeout`, and `idleExpirySeconds` and `onIdleTimeout`. The action is `delete`. By default, there is no idle timeout unless the project sets one, and the wall-clock timeout uses the project or platform default, if one is enabled. | | `idempotencyKey` | string | Makes a retried create in the same workload cell return the same sandbox. A create in another cell makes a separate sandbox. To keep creates in one region, set `region`. If `name` is set, the key is derived from it. Otherwise, each call generates a new key. | | `createTimeoutSeconds` | number | Sets how many seconds the sandbox has to reach running before it is deleted. `-1` sets the maximum, 86400. The default is the server default, 3600. | | `waitSeconds` | number | Sets how many seconds create waits for the sandbox to start. The server holds the request for up to 3 seconds, and the SDK waits for the rest. `0` returns immediately. The default is 60. If the sandbox has not started in time, or fails, `create()` resolves with it without throwing. Check `sandbox.state` before using it. | ```bash daytona sandbox create ``` The following example sets the remaining flags: ```bash daytona sandbox create \ --name my-sandbox \ --label team=research --label run=42 \ --user root \ --cpu 2 --memory 4096 --disk 20480 \ --cpu-max 4 --memory-max 16384 \ --port 8080 --port 5353/udp \ --block-all --allow-domain pypi.org --allow-domain '*.github.com' \ --env LOG_LEVEL=debug \ --secret GITHUB_TOKEN \ --cpu-arch amd64 --cpu-type zen5 \ --idle-timeout 1h --on-idle-timeout delete \ --lifecycle-timeout 168h --on-lifecycle-timeout delete \ --idempotency-key run-42-create ``` | **Flag** | **Type** | **Description** | | ------------------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `--image` | string | Sets the registered image that the sandbox starts from, by name or `img_` ID. If omitted, the sandbox boots the platform default image, the platform image whose `default` field is `true` in the [image list](/docs/images#list-images). When no default image is set, the request returns a 400 error. | | `--name` | string | Sets the display name. If omitted, a name is generated. | | `--label` | KEY=VALUE | Attaches a `KEY=VALUE` metadata label. Repeat the flag for more labels. | | `--user` | string | Sets the default OS user inside the sandbox. The default is the image's `USER`, or `root` if the image sets none, sets root, or sets a numeric user ID. | | `--cpu` | float | Sets the guaranteed CPU cores as a float, raised to at least 0.125. The value is raised to at least one core per 8 GiB of guaranteed memory. If omitted, the value is one core per 8 GiB of guaranteed memory, and at least 0.5: 0.5 with the default 1024 MiB. | | `--memory` | int32 | Sets the guaranteed memory in MiB, raised to at least 512. The default is 1024. | | `--disk` | int32 | Sets the guaranteed writable disk in MiB. The default is 512. When `--cpu`, `--memory`, or `--disk` is set, the disk is raised to at least 10240. | | `--cpu-max` | float | Sets the CPU limit of the sandbox in cores, a multiple of 0.5. One core is 2 vCPUs. The sandbox boots at this size. The default is the system or plan cap. | | `--memory-max` | int32 | Sets the memory limit of the sandbox in MiB, from 256 to 32768. If `--memory` is omitted, the guaranteed memory is lowered to the limit. If `--memory` is set, a guaranteed memory above the limit, after the raise to 512, is refused. The default is 32768. | | `--disk-max` | int32 | Sets the writable disk limit of the sandbox in MiB, from 512 to 262144. | | `--port` | PORT\[/PROTO\] | Forwards an inbound port, with an optional protocol. Repeat the flag for more ports. | | `--volume` | VOLUME:MOUNT_PATH\[:SUBPATH\]\[:ro\] | Attaches a volume. Repeat the flag for more volumes. See [attach volumes](/docs/volumes#attach-volumes). | | `--env` | KEY=VALUE | Sets an environment variable inside the sandbox. Repeat the flag for more variables. | | `--secret` | string | Attaches a project secret by name. The sandbox sees it as an opaque placeholder. A name that is not a secret of the project is refused. Repeat the flag for more secrets. | | `--block-all` | bool | Denies all egress that is not explicitly allowed. A create with a network policy is refused when no runner in the region can enforce it for the sandbox's CPU architecture and type. You can [change the policy](/docs/network-limits#update-network-policy) after create through the SDKs or the API. The default is `false`. | | `--allow-domain` | string | Allows egress to a hostname or a `*.` wildcard domain. A wildcard matches subdomains only, so list the parent domain separately. It implies `--block-all`. Repeat the flag for more domains. | | `--allow-cidr` | string | Allows egress to an IPv4 address or CIDR block, on any port. It needs `--block-all` or `--allow-domain`. Repeat the flag for more addresses. | | `--spot` | bool | Runs the sandbox on discounted capacity that can be reclaimed. The default is `false`. | | `--region` | string | Sets the region, any listed region including `earth`. The default is the project's default region, then the organization's, then `earth`. A create in a region with no online Linux runner is refused. | | `--cpu-arch` | string | Sets the CPU architecture, `amd64` or `arm64`. The default is the region's default architecture, or `amd64` if the region sets none. A create with an architecture that no runner in the region provides is refused, or waits until its create deadline. | | `--cpu-type` | string | Sets the CPU hardware tier slug: `zen3`, `zen4`, `zen5`, `zen5c`, `arrowlake1`, `arrowlake2`, `graviton`, `graviton3`, and `graviton4`. The slug also sets the architecture. A create with a type that no runner in the region serves, itself or as a fallback, is refused, or waits until its create deadline. See [CPU types](#cpu-types). | | `--lifecycle-timeout` | duration | Sets the wall-clock lifetime as a Go duration such as `2h`, until `--on-lifecycle-timeout` fires. The default is the project or platform default, if one is enabled. | | `--on-lifecycle-timeout` | string | Sets the action when `--lifecycle-timeout` elapses, `delete`. The default is `delete`. | | `--idle-timeout` | duration | Sets the idle time as a Go duration, at least `1m`, until `--on-idle-timeout` fires. By default, there is no idle timeout unless the project sets one. | | `--on-idle-timeout` | string | Sets the action when `--idle-timeout` elapses, `delete`. It is required with `--idle-timeout`. | | `--idempotency-key` | string | Makes a retried create return the same sandbox. | | `--server-wait` | duration | Sets how long the server holds the create response for the sandbox to start, as a Go duration. `0s` answers at once. The server default is `3s`. The command then waits until the sandbox is running and prints it, unless `--no-wait` is set. | | `--timeout` | duration | Sets how long the command waits for the sandbox to start, as a Go duration. The default is `10m`. The sandbox keeps starting after the command stops waiting. | | `--no-wait` | bool | Prints the create response immediately instead of waiting for the sandbox to start. | | `--create-ttl` | duration | Sets how long the sandbox has to reach running before the server deletes it, as a Go duration. `max` sets the server maximum, 24 hours. The default is `1h`. | | `-f`, `--file` | string | Reads the JSON request body from a file, or from standard input with `-`. Flags set on the command line override its fields. | ```bash curl 'https://api.daytona.com/sandboxes' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{}' ``` The following example sets the remaining fields: ```bash curl 'https://api.daytona.com/sandboxes' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "name": "my-sandbox", "labels": { "team": "research", "run": "42" }, "user": "root", "cpu": 2, "memory_mib": 4096, "disk_mib": 20480, "cores_max": 4, "memory_max_mib": 16384, "ports": [{ "port": 8080 }, { "port": 5353, "proto": "udp" }], "network_policy": { "block_all": true, "allow_domains": ["pypi.org", "*.github.com"] }, "env": { "LOG_LEVEL": "debug" }, "secrets": ["GITHUB_TOKEN"], "spot": false, "cpu_arch": "amd64", "cpu_type": "zen5", "lifecycle_policy": { "idle_expiry_seconds": 3600, "on_idle_timeout": "delete", "timeout_seconds": 604800, "on_timeout": "delete" }, "idempotency_key": "run-42-create" }' ``` | **Field** | **Type** | **Description** | | ----------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `image` | string | Sets the registered image that the sandbox starts from, by name or `img_` ID. If omitted, the sandbox boots the platform default image, the platform image whose `default` field is `true` in the [image list](/docs/images#list-images). When no default image is set, the request returns a 400 error. | | `name` | string | Sets the display name. If omitted, a name is generated. Names need not be unique. To make a retried create return the same sandbox, send `idempotency_key`. | | `labels` | object | Attaches key-value metadata to the sandbox. | | `user` | string | Sets the default OS user inside the sandbox. The default is the image's `USER`, or `root` if the image sets none, sets root, or sets a numeric user ID. | | `cpu` | number | Sets the guaranteed CPU cores as a float, raised to at least 0.125. The value is raised to at least one core per 8 GiB of guaranteed memory. If omitted, the value is one core per 8 GiB of guaranteed memory, and at least 0.5: 0.5 with the default 1024 MiB. | | `memory_mib` | integer | Sets the guaranteed memory in MiB, raised to at least 512. The default is 1024. | | `disk_mib` | integer | Sets the guaranteed writable disk in MiB. The default is 512. When `cpu`, `memory_mib`, or `disk_mib` is set, the disk is raised to at least 10240. | | `cores_max` | number | Sets the CPU limit of the sandbox in cores, a positive multiple of 0.5. One core is 2 vCPUs. The sandbox boots at this size. The default is the system or plan cap. | | `memory_max_mib` | integer | Sets the memory limit of the sandbox in MiB, from 256 to 32768. If `memory_mib` is omitted, the guaranteed memory is lowered to the limit. If `memory_mib` is set, a guaranteed memory above the limit, after the raise to 512, is refused. The default is 32768. | | `disk_max_mib` | integer | Sets the writable disk limit of the sandbox in MiB, from 512 to 262144. | | `ports` | array | Forwards inbound ports to the sandbox. Each entry has a `port` and a `proto`, which defaults to `tcp`. | | `volumes` | array | Attaches volumes to the sandbox. See [attach volumes](/docs/volumes#attach-volumes). | | `env` | object | Sets environment variables inside the sandbox. | | `secrets` | array | Attaches project secrets by name. The sandbox sees each secret as an opaque placeholder. A name that is not a secret of the project is refused. | | `network_policy` | object | Sets the outbound network policy with `block_all`, `allow_domains`, and `allow_cidrs`. `allow_domains` implies `block_all`. `allow_cidrs` restricts egress only together with `block_all` or `allow_domains`. A `*.` wildcard domain matches subdomains only, so list the parent domain separately. A create with a policy is refused when no runner in the region can enforce it for the sandbox's CPU architecture and type. You can [change it](/docs/network-limits#update-network-policy) after create. | | `spot` | boolean | Runs the sandbox on discounted capacity that can be reclaimed. The default is `false`. | | `region_id` | string | Sets the region, any listed region including `earth`. The default is the project's default region, then the organization's, then `earth`. A create in a region with no online Linux runner is refused. | | `cpu_arch` | string | Sets the CPU architecture, `amd64` or `arm64`. The default is the region's default architecture, or `amd64` if the region sets none. A create with an architecture that no runner in the region provides is refused, or waits until its create deadline. | | `cpu_type` | string | Sets the CPU hardware tier slug: `zen3`, `zen4`, `zen5`, `zen5c`, `arrowlake1`, `arrowlake2`, `graviton`, `graviton3`, and `graviton4`. The slug also sets the architecture. A create with a type that no runner in the region serves, itself or as a fallback, is refused, or waits until its create deadline. See [CPU types](#cpu-types). | | `lifecycle_policy` | object | Sets the lifecycle policy with `timeout_seconds` and `on_timeout`, and `idle_expiry_seconds` and `on_idle_timeout`. The action is `delete`. By default, there is no idle timeout unless the project sets one, and the wall-clock timeout uses the project or platform default, if one is enabled. | | `idempotency_key` | string | Makes a retried create return the same sandbox. You can also send it as the `Idempotency-Key` header. It is required when `region_id` is `earth` or another region that covers other regions. | | `create_timeout_seconds` | integer | Sets how many seconds the sandbox has to reach running before it is deleted. `-1` sets the maximum, 86400. The default is 3600. | | `wait_seconds` | integer | Sets how many seconds the server holds the request for the sandbox to start. `0` returns immediately. The default and the maximum are 3, and a larger value is lowered to 3. | The response has the following fields: | **Field** | **Description** | | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `status` | The status of the sandbox when the response is sent. The server holds the request for up to `wait_seconds`, so the status is `running`, `failed` when the sandbox failed to start, or an earlier status such as `pending` or `booting` when the sandbox has not started in time. Poll `GET /sandboxes/{sandboxId}?wait=running` while the status is not `running` or `failed`. A `failed` sandbox does not start; the `error` field of the sandbox names the cause. | | `access_token` | The access token is returned only once. An idempotent replay returns `null`. | ### Spot [#spot] Linux sandboxes run on reserved capacity by default. A spot Linux sandbox runs on discounted capacity that Daytona can reclaim at any time to free resources for full-price sandboxes. Spot multiplies the CPU, memory, and disk price by 0.7. Apart from price and reclaim, a spot Linux sandbox supports the same images, resources, volumes, and lifecycle operations as any other Linux sandbox. A reclaim is immediate, with no advance notice and no grace period. An ephemeral sandbox is deleted, and only data on a [volume](/docs/volumes) or in other storage outside the sandbox remains. [Preemption](/docs/preemption) describes the reclaim policy. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create(spot=True) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------- | | `spot` | bool | Places the sandbox on discounted, reclaimable capacity. The default is `False`. Set it when you create the sandbox. It cannot be changed on an existing sandbox. | ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create({ spot: true }) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------- | | `spot` | boolean | Places the sandbox on discounted, reclaimable capacity. The default is `false`. Set it when you create the sandbox. It cannot be changed on an existing sandbox. | ```bash daytona sandbox create --spot ``` | **Flag** | **Type** | **Description** | | -------- | -------- | --------------- | | `--spot` | bool | Places the sandbox on discounted, reclaimable capacity. The default is `false`. Set it when you create the sandbox. It cannot be changed on an existing sandbox. | ```bash curl 'https://api.daytona.com/sandboxes' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{"spot": true}' ``` | **Field** | **Type** | **Description** | | --------- | -------- | --------------- | | `spot` | boolean | Places the sandbox on discounted, reclaimable capacity. The default is `false`. Set it when you create the sandbox. It cannot be changed on an existing sandbox. | ### CPU types [#cpu-types] A CPU type is a processor model that a Linux sandbox can request when it is created. Each type belongs to one architecture, amd64 or arm64, and has a tier: its rank within that architecture, starting at 1 for the lowest. Requesting a CPU type also sets the sandbox's architecture. The CPU type list contains every type that a create request accepts, whether or not a runner provides it. A create with a type that no runner in the region serves, itself or as a fallback, is refused, or waits until its create deadline. To see which types a region can serve, add the region. A type is available in a region when a running runner there provides it. When no runner provides the type itself, a runner with a higher tier of the same architecture can serve it as a fallback. Availability reflects the runners that are live at request time. [List regions](/docs/regions#list-regions) gives the region IDs. ```bash # List CPU types daytona cpu-type list # Check CPU type availability in a region daytona cpu-type list --region us-east-ash-1 ``` | **Flag** | **Type** | **Description** | | ---------- | -------- | ------------------------------------------------------------------------------------- | | `--region` | string | Sets one region ID. Without it, the command lists CPU types without availability. With it, the output adds the `AVAILABLE` column. | In a terminal, the output is a table with the following columns. Otherwise, the output is JSON unless `-o table` is set. | **Column** | **Description** | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `ID` | The CPU type slug that a create request accepts. | | `NAME` | The display name of the CPU type. | | `ARCH` | The CPU architecture, `amd64` or `arm64`. | | `TIER` | The rank within the architecture, starting at 1 for the lowest. | | `AVAILABLE` | Shown with `--region`. `exact` if a runner in the region provides the type, `fallback` if a higher tier of the same architecture serves it, and `-` otherwise. | ```bash # List CPU types curl 'https://api.daytona.com/cpu-catalog' \ --header 'Authorization: Bearer YOUR_API_KEY' # Check CPU type availability in a region curl 'https://api.daytona.com/cpu-catalog?region_ids=us-east-ash-1' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` | **Field** | **Type** | **Description** | | ---------- | -------- | ---------------------------------------------------------------------------------------------------- | | `region_ids` | string | Sets a comma-separated list of region IDs, at most 64. The default is every region that the answering workload cell hosts. | The response has the following fields: | **Field** | **Description** | | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `cpu_types` | Lists every CPU type with `id`, `name`, `cpu_arch`, and `tier`, and whether the requested regions can serve it: `available`, `exact_region_ids`, and `fallback_region_ids`. | | `arches` | Lists each CPU architecture and the requested regions where it is available. | | `regions` | Lists the covered regions. In each region, `default_arch` and `default_type` are the values that a create request that sets neither uses. `default_type` is `null` when the region sets none. | ## Filesystem snapshot [#filesystem-snapshot] A filesystem snapshot saves the filesystem of a running Linux sandbox as an [image](/docs/images). The sandbox keeps running, and new sandboxes boot from the image with the captured files. Unlike a [memory snapshot](#memory-snapshot), a filesystem snapshot holds no processes or memory. The capture runs in the background: the image starts as pending, moves to building, and becomes ready when the capture finishes. A named image is permanent until you delete it. An unnamed image is anonymous. Daytona deletes an anonymous image after its idle window passes without a sandbox create from it. The idle window is the server maximum of 7 days by default. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.process.run("pip install requests") # Capture the filesystem; the sandbox keeps running image = sandbox.capture_image(name="my-env") # Wait until the capture is ready, then boot new sandboxes from it while image.status not in ("ready", "failed"): image = daytona.v2.images.get(image.id, wait="ready") if image.status == "failed": raise RuntimeError(image.error) clone = daytona.v2.create("my-env") ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------- | | `name` | str | Sets the image name. The default is `None`, which makes the image anonymous. The name must be unique in the project. | | `idle_expiry_seconds` | int | Sets how many seconds an anonymous image can go without a sandbox create before deletion, from `1` to the server maximum. `-1` sets the maximum. The default is the server maximum. It applies only to anonymous images. A capture that also sets `name` is refused. | - The requests require the `write:images` and `write:sandboxes` permissions. - The sandbox must be a running Linux sandbox. ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() await sandbox.process.run('pip install requests') // Capture the filesystem; the sandbox keeps running let image = await sandbox.captureImage({ name: 'my-env' }) // Wait until the capture is ready, then boot new sandboxes from it while (image.status !== 'ready' && image.status !== 'failed') { image = await daytona.v2.images.get(image.id, { wait: 'ready' }) } if (image.status === 'failed') throw new Error(image.error ?? 'image capture failed') const clone = await daytona.v2.create('my-env') ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------- | | `name` | string | Sets the image name. The default is `undefined`, which makes the image anonymous. The name must be unique in the project. | | `idleExpirySeconds` | number | Sets how many seconds an anonymous image can go without a sandbox create before deletion, from `1` to the server maximum. `-1` sets the maximum. The default is the server maximum. It applies only to anonymous images. A capture that also sets `name` is refused. | - The requests require the `write:images` and `write:sandboxes` permissions. - The sandbox must be a running Linux sandbox. ```bash # Capture the filesystem and wait until the image is ready daytona image capture {sandboxId} --name my-env # Boot a new sandbox from the captured filesystem daytona sandbox create --image my-env ``` | **Flag** | **Type** | **Description** | | -------- | -------- | --------------- | | `--name` | string | Sets the image name. Without a name, the image is anonymous. The name must be unique in the project. | | `--timeout` | string | Sets how long the command waits for the image to be ready. The default is `10m`. | | `--no-wait` | boolean | Returns once the capture is queued, without waiting for the image to be ready. | - The requests require the `write:images` and `write:sandboxes` permissions. - The sandbox must be a running Linux sandbox. ```bash # Capture the filesystem; the sandbox keeps running curl 'https://api.daytona.com/sandboxes/{sandboxId}/images' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{"name": "my-env"}' # Wait for the capture to be ready curl 'https://api.daytona.com/images/{imageId}?wait=ready' \ --header 'Authorization: Bearer YOUR_API_KEY' # Boot a new sandbox from the captured filesystem curl 'https://api.daytona.com/sandboxes' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{"image": "my-env"}' ``` | **Field** | **Type** | **Description** | | --------- | -------- | --------------- | | `name` | string | Sets the image name. Without a name, the image is anonymous. The name must be unique in the project. | | `idle_expiry_seconds` | integer | Sets how many seconds an anonymous image can go without a sandbox create before deletion, from `1` to the server maximum. `-1` sets the maximum. The default is the server maximum. It applies only to anonymous images. A capture that also sets `name` is refused. | - The requests require the `write:images` and `write:sandboxes` permissions. - The sandbox must be a running Linux sandbox. - The wait request returns at `ready` or `failed`, or after 30 seconds. Repeat it while the image status is `pending` or `building`. A `failed` image does not become `ready`. ## Memory snapshot [#memory-snapshot] A memory snapshot saves the memory and disk of a running Linux sandbox under a name. A sandbox restored from the snapshot resumes the captured processes and memory instead of booting. The restored sandbox gets the CPU, memory, and disk of the source sandbox. Deleting the source sandbox does not delete its snapshots. The capture runs in the background: the snapshot starts as pending, is building while the runner captures the sandbox, and becomes ready when the capture finishes. A snapshot restores on the runner that captured it, or on another runner of the region with the same CPU model and hypervisor version. It restores in another region only where Daytona has enabled cross-region restore and the source sandbox was not persistent. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() # Capture the memory and disk of the running sandbox snapshot = sandbox.create_snapshot("my-snapshot") # Wait until the capture is ready while snapshot.status not in ("ready", "failed"): snapshot = daytona.v2.snapshots.get(snapshot.id, wait="ready") if snapshot.status == "failed": raise RuntimeError(snapshot.error) # Resume the captured processes and memory in a new sandbox restored = daytona.v2.create_from_snapshot("my-snapshot", labels={"team": "research"}) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------- | | `name` | str | Sets the snapshot name, 1 to 128 characters of letters, digits, `.`, `_`, and `-`. The name cannot start with `.` or with a reserved prefix: `sbx_`, `vol_`, `fn_`, `img_`, `snap_`, `snap-`, `build-`, `refs`, `by-digest`, `prj-`, or `glb-`. This parameter is required. Snapshots and images in the project share one name space. A name in use fails with `409`. | | `snapshot` | str | Sets the snapshot that `create_from_snapshot()` restores from, by name or by ID, `snap_...`. This parameter is required. | | `labels` | Dict\[str, str\] | Attaches key-value metadata to the restored sandbox. The restored sandbox does not inherit the labels of the source sandbox. | - The requests require the `write:snapshots` and `write:sandboxes` permissions. - The source sandbox must be running. - The source sandbox must be persistent or served from a warm template. A snapshot of any other sandbox, such as one created from a filesystem snapshot or with volumes attached, fails with `409`. ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() // Capture the memory and disk of the running sandbox let snapshot = await sandbox.createSnapshot('my-snapshot') // Wait until the capture is ready while (snapshot.status !== 'ready' && snapshot.status !== 'failed') { snapshot = await daytona.v2.snapshots.get(snapshot.id, { wait: 'ready' }) } if (snapshot.status === 'failed') throw new Error(snapshot.error ?? 'snapshot capture failed') // Resume the captured processes and memory in a new sandbox const restored = await daytona.v2.createFromSnapshot('my-snapshot', { labels: { team: 'research' } }) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------- | | `name` | string | Sets the snapshot name, 1 to 128 characters of letters, digits, `.`, `_`, and `-`. The name cannot start with `.` or with a reserved prefix: `sbx_`, `vol_`, `fn_`, `img_`, `snap_`, `snap-`, `build-`, `refs`, `by-digest`, `prj-`, or `glb-`. This parameter is required. Snapshots and images in the project share one name space. A name in use fails with `409`. | | `snapshot` | string | Sets the snapshot that `createFromSnapshot()` restores from, by name or by ID, `snap_...`. This parameter is required. | | `labels` | Record\ | Attaches key-value metadata to the restored sandbox. The restored sandbox does not inherit the labels of the source sandbox. | - The requests require the `write:snapshots` and `write:sandboxes` permissions. - The source sandbox must be running. - The source sandbox must be persistent or served from a warm template. A snapshot of any other sandbox, such as one created from a filesystem snapshot or with volumes attached, fails with `409`. ```bash # Capture the memory and disk of the running sandbox and wait until it is ready daytona snapshot create {sandboxId} --name my-snapshot # Resume the captured processes and memory in a new sandbox daytona sandbox create-from-snapshot my-snapshot --label team=research ``` | **Flag** | **Type** | **Description** | | -------- | -------- | --------------- | | `--name` | string | Sets the snapshot name. This flag is required. | | `--label` | KEY=VALUE | Attaches a `KEY=VALUE` metadata label to the restored sandbox. The restored sandbox does not inherit the labels of the source sandbox. Repeat the flag for more labels. | | `--timeout` | string | Sets how long the command waits for the snapshot to be `ready`. The default is `10m`. | | `--no-wait` | boolean | Returns once the capture is queued, without waiting for `ready`. | - The requests require the `write:snapshots` and `write:sandboxes` permissions. - The source sandbox must be running. - The source sandbox must be persistent or served from a warm template. A snapshot of any other sandbox, such as one created from a filesystem snapshot or with volumes attached, fails with `409`. ```bash # Capture the memory and disk of the running sandbox curl 'https://api.daytona.com/sandboxes/{sandboxId}/snapshots' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{"name": "my-snapshot"}' # Wait for the capture to be ready curl 'https://api.daytona.com/snapshots/{snapshotId}?wait=ready&timeout_ms=60000' \ --header 'Authorization: Bearer YOUR_API_KEY' # Resume the captured processes and memory in a new sandbox curl 'https://api.daytona.com/sandboxes/from-snapshot' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{"snapshot": "my-snapshot", "labels": {"team": "research"}}' ``` | **Field** | **Type** | **Description** | | --------- | -------- | --------------- | | `name` | string | Sets the snapshot name, 1 to 128 characters of letters, digits, `.`, `_`, and `-`. The name cannot start with `.` or with a reserved prefix: `sbx_`, `vol_`, `fn_`, `img_`, `snap_`, `snap-`, `build-`, `refs`, `by-digest`, `prj-`, or `glb-`. This field is required. Snapshots and images in the project share one name space. A name in use fails with `409`. | | `snapshot` | string | Sets the snapshot that `POST /sandboxes/from-snapshot` restores from, by name or by ID, `snap_...`. This field is required. | | `labels` | object | Attaches key-value metadata to the restored sandbox. The restored sandbox does not inherit the labels of the source sandbox. | - The requests require the `write:snapshots` and `write:sandboxes` permissions. - The source sandbox must be running. - The source sandbox must be persistent or served from a warm template. A snapshot of any other sandbox, such as one created from a filesystem snapshot or with volumes attached, fails with `409`. - The wait request returns at `ready` or `failed`, or after 60 seconds. Repeat it while the snapshot status is `pending` or `building`. A `failed` snapshot does not become `ready`. - A restore from a snapshot that is not ready is refused. ## Filesystem persistence [#filesystem-persistence] Filesystem persistence keeps the contents of a sandbox's disk: files, installed packages, cloned repositories, and build artifacts. A sandbox with a preserved filesystem starts with its environment intact, with nothing to reinstall or rebuild. A Linux sandbox keeps its filesystem on its host until it is deleted. Deleting the sandbox or losing its host discards the filesystem. [Filesystem snapshots](#filesystem-snapshot) keep the filesystem beyond the sandbox, and new sandboxes boot from them. ## Memory persistence [#memory-persistence] Memory persistence keeps the runtime state of a sandbox: running processes, open connections, and everything loaded in RAM. A sandbox with preserved memory continues from the point it was frozen, with processes still running, instead of starting from a clean boot. A Linux sandbox keeps its memory only while it runs. [Memory snapshots](#memory-snapshot) keep memory and processes beyond the sandbox. ## Lifecycle [#lifecycle] Every Linux sandbox moves through a lifecycle. A Linux sandbox can have several different states. Each state reflects the status of your sandbox. A Linux sandbox transitions between states in response to user actions, or automatically when one of its [timeouts](#timeouts) elapses. Every Linux sandbox supports wait for state, delete, timeouts, and lifecycle policy updates. A Linux sandbox keeps its filesystem and memory until it is deleted, or until its host fails: the sandbox then moves to error (lost in the CLI and API), and its local filesystem and memory are gone. The following tables list the states of a Linux sandbox and the transitions between them. The SDKs report the states in the **State** column. The CLI and API report the more detailed status in the **API status** column. | **State** | **API status** | **Description** | | ---------------- | ------------------------------ | ------------------------------------------------------------------------------- | | **`queued`** | **`queued`** | The create request is recorded and waits to be published for placement. | | **`creating`** | **`pending`**, **`assigned`** | The create request is accepted, and the sandbox is queued for and placed on a host. | | **`starting`** | **`booting`** | The microVM is booting and will be ready to use. | | **`started`** | **`running`** | The sandbox is running and ready to accept requests. | | **`destroying`** | **`deleting`** | The sandbox is being deleted. | | **`destroyed`** | **`deleted`** | The sandbox and its storage are removed. | | **`error`** | **`failed`**, **`lost`** | The sandbox could not boot, hit an unrecoverable error, or its host was lost. | | **`unknown`** | | The SDK does not recognize the status the API reports. | A sandbox can transition between states in response to various actions. The following table lists the initial state, target state, and trigger for the transition. | **Initial state** | **Target state** | **Trigger** | | ----------------- | ---------------- | ---------------------------------------------------------------------------------- | | **`queued`** | **`creating`** | The create request is published for placement. | | **`creating`** | **`starting`** | The sandbox is placed on a host, the host prepares its image, and the microVM boots. | | **`starting`** | **`started`** | The sandbox finishes booting and accepts requests. | | any state | **`destroying`** | A delete is requested, a timeout elapses, or the platform reclaims a spot sandbox. | | **`destroying`** | **`destroyed`** | The sandbox is removed and its resources are released. | | any active state | **`error`** | The sandbox fails to boot, hits an unrecoverable error, or its host is lost. | ### Wait for state [#wait-for-state] Wait until a Linux sandbox reaches a target state. The wait stops early when the sandbox reaches a state from which the target is no longer reachable, such as error or destroyed. The SDKs use the states in the [sandbox states](#lifecycle) table, so the SDK started state corresponds to the running status in the CLI and API. ```python # Block until the sandbox is started; returns the sandbox sandbox.wait(until="started", timeout=60) # Block until the sandbox is in one of the listed states sandbox.wait(until=["starting", "started"], timeout=60) ``` | **Parameter** | **Type** | **Description** | | ------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------- | | `until` | str \| Sequence\[str\] | Sets one state or a list of states. `wait()` returns on any of them. The default is `"started"`. | | `timeout` | float | Sets the wait limit in seconds. When the timeout elapses, `wait()` raises `RequestTimeoutError`. When the sandbox reaches `destroying`, `destroyed`, or `error` first, it raises `SandboxTerminalStateError`. `0` waits without a limit. The default is `60`. | ```typescript // Block until the sandbox is started; returns the sandbox await sandbox.wait({ until: 'started', timeoutSeconds: 60 }) // Block until the sandbox is in one of the listed states await sandbox.wait({ until: ['starting', 'started'], timeoutSeconds: 60 }) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | -------------------------------------------------------------------------------------------------------------------------- | | `until` | SandboxWaitState \| SandboxWaitState\[\] | Sets one state or a list of states. `wait()` returns on any of them. The default is `'started'`. | | `timeoutSeconds` | number | Sets the wait limit in seconds. When the timeout elapses, `wait()` throws `RequestTimeoutError`. When the sandbox reaches `destroying`, `destroyed`, or `error` first, it throws `SandboxTerminalStateError`. `0` waits without a limit. The default is `60`. | ```bash # Block until the sandbox is running, or the timeout elapses daytona sandbox wait {sandboxId} --for running --timeout 60s ``` | **Flag** | **Type** | **Description** | | -------- | -------- | --------------- | | `--for` | string | Sets the state to wait for: `running`, `stopped`, `paused`, or `deleted`. The SDK names `started` and `destroyed` are also accepted. The default is `running`. | | `--timeout` | string | Sets how long the command waits. The default is `10m`. | ```bash # Long-poll until the sandbox is running, a terminal state, or the timeout elapses curl 'https://api.daytona.com/sandboxes/{sandboxId}?wait=running&timeout_ms=60000' \ --header 'Authorization: Bearer YOUR_API_KEY' # Long-poll until the sandbox is exactly deleted; wait_exact skips the transient deleting state curl 'https://api.daytona.com/sandboxes/{sandboxId}?wait_exact=deleted&timeout_ms=60000' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` | **Field** | **Type** | **Description** | | ------------ | --------- | ----------------------------------------------------------------------------------------------------------- | | `wait` | string | Blocks the response until the sandbox reaches this state or a terminal state. The wait also ends on `stopping`, `stopped`, `deleting`, `deleted`, `failed`, or `lost`. There is no default. | | `wait_exact` | string | Blocks the response until the sandbox reaches exactly this state. Only `failed` and `lost` also end the wait. There is no default. | | `timeout_ms` | integer | Sets the wait limit in milliseconds, at most `60000`. A larger value is lowered to `60000`. When the limit elapses, the response is `200` with the current sandbox. Check `status` in the response. The default is `30000`. | ### Delete [#delete] Delete a Linux sandbox to tear down its virtual machine. Deletion works in any state. The API returns once teardown starts, and the SDKs and the CLI wait until the sandbox is deleted. The sandbox moves from deleting to deleted when the teardown finishes. Deleting a sandbox discards its filesystem and memory. Images and snapshots captured from the sandbox remain. To keep files from a sandbox, take a [filesystem snapshot](#filesystem-snapshot) or write the files to a [volume](/docs/volumes) or other storage outside the sandbox. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.delete() # Delete by sandbox ID, without fetching the sandbox first daytona.v2.delete("{sandboxId}") ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() await sandbox.delete() // Delete by sandbox ID, without fetching the sandbox first await daytona.v2.delete('{sandboxId}') ``` ```bash daytona sandbox delete {sandboxId} ``` ```bash curl 'https://api.daytona.com/sandboxes/{sandboxId}' \ --request DELETE \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ### Timeouts [#timeouts] Daytona deletes a Linux sandbox automatically when one of its two timers elapses. Each timer pairs an interval in seconds with the action it fires. Set both timers at create in the lifecycle policy, and change them later through [update lifecycle policy](#update-lifecycle-policy). | **Timer** | **Purpose** | **Fires after** | **Default** | | --------------------------------- | --------------------------------------------------- | ------------------------------------------------------------ | --------------------------- | | [**Timeout**](#timeout) | Cap how long a sandbox lives | The interval has passed since the sandbox last started running, active or not | Project or platform default | | [**Idle timeout**](#idle-timeout) | Delete a sandbox that is not in use | The sandbox has had no activity for the interval | Project default, or off | The action for both timers is delete. Auto-delete is not a separate setting. It is the idle timeout with the delete action. #### Timeout [#timeout] The timeout is a wall-clock budget. It starts when the sandbox starts running. Activity does not extend it. A delete timeout fires in any state, except while the sandbox is still being created: a sandbox that does not reach running is deleted at its create deadline. Once set, the timeout cannot be cleared. When the timeout is omitted at create, Daytona applies the project's [lifecycle defaults](/docs/projects#lifecycle-defaults). Without a project default, Daytona applies the platform default timeout of 300 seconds, if the platform default is enabled. An explicit timeout must not exceed the organization maximum, 86,400 seconds (24 hours) unless the organization sets a different maximum. When the action is omitted, it defaults to delete. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create( # Delete the sandbox 2 hours after it is created lifecycle_policy={"timeout_seconds": 7200, "on_timeout": "delete"}, ) ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create({ // Delete the sandbox 2 hours after it is created lifecyclePolicy: { timeoutSeconds: 7200, onTimeout: 'delete' }, }) ``` ```bash # Delete the sandbox 2 hours after it is created daytona sandbox create --lifecycle-timeout 2h --on-lifecycle-timeout delete ``` ```bash # Delete the sandbox 2 hours after it is created curl 'https://api.daytona.com/sandboxes' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "lifecycle_policy": { "timeout_seconds": 7200, "on_timeout": "delete" } }' ``` #### Idle timeout [#idle-timeout] The idle timeout fires after the sandbox has had no activity for the interval. Activity is any request through the toolbox API, preview URLs, VNC, and SSH, a toolbox command that is still running, the sandbox being created or starting to run, and a reset of the idle timer. A change to the lifecycle policy does not count as activity. The idle timeout is off by default unless the project sets one, has a minimum of 60 seconds, and requires an action. The API raises a smaller value to 60 seconds, and the CLI refuses it. The action fires within about 2 minutes after the interval elapses. ##### Auto-delete [#auto-delete] Delete a Linux sandbox after a period of inactivity. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create( lifecycle_policy={"idle_expiry_seconds": 3600, "on_idle_timeout": "delete"}, ) ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create({ lifecyclePolicy: { idleExpirySeconds: 3600, onIdleTimeout: 'delete' }, }) ``` ```bash daytona sandbox create --idle-timeout 1h --on-idle-timeout delete ``` ```bash curl 'https://api.daytona.com/sandboxes' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "lifecycle_policy": { "idle_expiry_seconds": 3600, "on_idle_timeout": "delete" } }' ``` ##### Reset the idle timer [#reset-the-idle-timer] Reset the idle timer of a Linux sandbox to keep it alive while it does work that Daytona does not count as activity. The reset counts as activity, so the idle countdown restarts from now. The timeout is not affected. The reset succeeds whether or not an idle timeout is set, in any state except deleting and deleted. It never moves the timer backwards: when newer activity arrives at the same time, the newer activity wins. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create( lifecycle_policy={"idle_expiry_seconds": 3600, "on_idle_timeout": "delete"}, ) lifecycle = sandbox.reset_idle_timer() print(lifecycle.idle_timeout_at) ``` - The request requires the `write:sandboxes` permission. - When the idle action is delete, the request also requires the `delete:sandboxes` permission. ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create({ lifecyclePolicy: { idleExpirySeconds: 3600, onIdleTimeout: 'delete' }, }) const lifecycle = await sandbox.resetIdleTimer() console.log(lifecycle.idleTimeoutAt) ``` - The request requires the `write:sandboxes` permission. - When the idle action is delete, the request also requires the `delete:sandboxes` permission. ```bash curl 'https://api.daytona.com/sandboxes/{sandboxId}/reset-idle-timer' \ --request POST \ --header 'Authorization: Bearer YOUR_API_KEY' ``` The response has the sandbox ID and its lifecycle policy with the following fields: | **Field** | **Description** | | ----------------- | ---------------------------------------- | | `idle_timeout_at` | The reset moves this value forward. | | `timeout_at` | The reset leaves this value unchanged. | - The request requires the `write:sandboxes` permission. - When the idle action is delete, the request also requires the `delete:sandboxes` permission. ### Update lifecycle policy [#update-lifecycle-policy] Update the timeouts of an existing Linux sandbox. Omitted fields keep their current values. The new actions must be valid for the sandbox, as listed in [timeouts](#timeouts). A deleting or deleted sandbox cannot be updated. ```python from daytona import Daytona from daytona.v2 import DISABLED daytona = Daytona() sandbox = daytona.v2.create() # Delete the sandbox after 30 minutes without activity; omitted fields keep their current value lifecycle = sandbox.update_lifecycle_policy(idle_expiry_seconds=1800, on_idle_timeout="delete") print(lifecycle.idle_expiry_seconds, lifecycle.on_idle_timeout) # Re-anchor the timeout to 1 hour from now lifecycle = sandbox.update_lifecycle_policy(timeout_seconds=3600) print(lifecycle.timeout_at) # Clear the idle timeout lifecycle = sandbox.update_lifecycle_policy(idle_expiry_seconds=DISABLED) ``` - The request requires the `write:sandboxes` permission. - Setting, changing, or clearing a delete action also requires the `delete:sandboxes` permission. ```typescript import { Daytona } from '@daytona/sdk' import { DISABLED } from '@daytona/sdk/v2' const daytona = new Daytona() const sandbox = await daytona.v2.create() // Delete the sandbox after 30 minutes without activity; omitted fields keep their current value let lifecycle = await sandbox.updateLifecyclePolicy({ idleExpirySeconds: 1800, onIdleTimeout: 'delete' }) console.log(lifecycle.idleExpirySeconds, lifecycle.onIdleTimeout) // Re-anchor the timeout to 1 hour from now lifecycle = await sandbox.updateLifecyclePolicy({ timeoutSeconds: 3600 }) console.log(lifecycle.timeoutAt) // Clear the idle timeout lifecycle = await sandbox.updateLifecyclePolicy({ idleExpirySeconds: DISABLED }) ``` - The request requires the `write:sandboxes` permission. - Setting, changing, or clearing a delete action also requires the `delete:sandboxes` permission. ```bash # Delete the sandbox after 30 minutes without activity daytona sandbox update {sandboxId} --idle-timeout 30m --on-idle-timeout delete # Re-anchor the timeout to 1 hour from now daytona sandbox update {sandboxId} --lifecycle-timeout 1h # Clear the idle timeout daytona sandbox update {sandboxId} --idle-timeout off ``` - The request requires the `write:sandboxes` permission. - Setting, changing, or clearing a delete action also requires the `delete:sandboxes` permission. ```bash # Delete the sandbox after 30 minutes without activity curl 'https://api.daytona.com/sandboxes/{sandboxId}/lifecycle-policy' \ --request PATCH \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "idle_expiry_seconds": 1800, "on_idle_timeout": "delete" }' # Re-anchor the timeout to 1 hour from now curl 'https://api.daytona.com/sandboxes/{sandboxId}/lifecycle-policy' \ --request PATCH \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "timeout_seconds": 3600 }' # Clear the idle timeout curl 'https://api.daytona.com/sandboxes/{sandboxId}/lifecycle-policy' \ --request PATCH \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "idle_expiry_seconds": -1 }' ``` | **Field** | **Type** | **Description** | | ------------------- | --------- | ----------------------------------------------------------------------------------------------------------------- | | `timeout_seconds` | integer | Sets the seconds until the timeout, counted from now. If omitted, the value is unchanged. | | `idle_expiry_seconds` | integer | Sets the seconds without activity before the idle action. `-1` clears the idle timeout and its action. If omitted, the value is unchanged. | | `on_timeout` | string | Sets the timeout action, `delete`. If omitted, the value is unchanged. | | `on_idle_timeout` | string | Sets the idle action, `delete`. It is required when you set an idle timeout on a sandbox that has none. If omitted, the value is unchanged. | - The request requires the `write:sandboxes` permission. - Setting, changing, or clearing a delete action also requires the `delete:sandboxes` permission. ## Permissions [#permissions] Linux sandboxes use the sandbox permissions of their project, and snapshots use the image and snapshot permissions. You can grant each to an [organization role](/docs/organizations#roles) or an [API key](/docs/api-keys). Setting, changing, or clearing a delete action in a lifecycle policy, and resetting the idle timer of a sandbox whose idle action is delete, also require the permission to delete sandboxes. The [audit logs](/docs/audit-logs) record sandbox creates, lifecycle changes, deletes, and snapshots. | **Permission** | **Grants** | | ---------------------- | --------------------------------------------------------------------------- | | **`read:sandboxes`** | Get sandboxes and wait for their state | | **`write:sandboxes`** | Create sandboxes, change their lifecycle policy, and reset the idle timer | | **`delete:sandboxes`** | Delete sandboxes | | **`write:images`** | Capture filesystem snapshots as images | | **`write:snapshots`** | Create memory snapshots | # Windows Sandboxes (/docs/windows-sandboxes) Windows sandboxes are **Windows virtual machines (VMs)**. Each sandbox runs its own Windows operating system on shared physical hardware and has its own files, network connection, and fixed amount of processor, memory, and disk. The hypervisor enforces the boundary and isolation between sandboxes and the host. A Windows sandbox starts from a prepared Windows base image or from an image captured from another Windows sandbox. The base image stays read-only, and each sandbox writes its changes to its own disk. A persistent Windows sandbox keeps its disk across stop and start. While the sandbox is running, it exposes a toolbox for command and process execution, sessions, filesystem and git operations, and computer use. Commands run in PowerShell, and the desktop is reached over the remote desktop protocol. The features and limits of Windows sandboxes can differ from those of Linux sandboxes and may change over time. | **Term** | **Description** | | ------------------ | -------------------------------------------------------------------------------------------------------------- | | **Sandbox** | An isolated Windows machine created on demand to run code. | | **Host** | The physical server that runs many sandboxes at once. Daytona calls these servers runners. | | **Guest** | The Windows operating system running inside a sandbox, as opposed to the operating system of the host. | | **Hypervisor** | Software on the host that creates virtual machines and keeps them separated from each other and from the host. | | **Base image** | A prepared Windows disk that a sandbox starts from. Sandboxes do not write to it. | | **Captured image** | A saved copy of a Windows sandbox's disk that new sandboxes start from. | | **Persistent** | A sandbox that keeps its disk across stop and start. | | **PowerShell** | The Windows shell that runs commands and sessions inside the sandbox. | | **Remote desktop** | Access to the Windows desktop of the sandbox over the remote desktop protocol (RDP). | Windows sandboxes for Daytona v2 are coming soon. # macOS Sandboxes (/docs/macos-sandboxes) macOS sandboxes are **macOS virtual machines (VMs)** on dedicated Apple silicon hardware. Each sandbox runs on a Mac Mini that your organization reserves. You can run commands in a macOS sandbox, connect with SSH, see and control its desktop, and keep disk between sessions. A Mac is reserved for a 24-hour period. You choose the cores, memory and disk of each sandbox when you create it: one sandbox can use the whole Mac, or two sandboxes share it. macOS sandboxes run only on reservations. When your organization holds no reservation, Daytona can buy one for you when you create a sandbox. | **Term** | **Description** | | ---------------- | ------------------------------------------------------------------------------------------------------------ | | **Reservation** | One dedicated Mac for your organization for a 24-hour period. Nobody else uses that Mac while you hold it. | | **Size** | The cores, memory and disk of one sandbox. You choose it when you create the sandbox. | | **Model** | The type of Mac. | | **Auto-reserve** | An organization setting that buys a Mac for you when you create a macOS sandbox and hold no reservation. | | **Image** | A macOS disk that a sandbox starts from: a base image or a snapshot of your sandbox. | | **Persistent** | A sandbox that keeps its disk across stop and start. Stop, start, pause, resume and snapshots need it. | ## Use cases [#use-cases] macOS sandboxes are used when the software, the build, or the task requires macOS or Apple tooling. - **Build and test Apple apps.** An agent or a CI job builds and tests iOS and macOS apps with Xcode and the iPhone simulator on a clean Mac. The base image ships with Xcode, its iPhone simulator, Homebrew, and Python. The image runs macOS 26.6.2, and its Homebrew includes CocoaPods, fastlane, and Node.js 24. - **Computer-use agents on macOS.** An agent operates macOS applications through screenshots and mouse and keyboard input. Computer use also reads the accessibility tree, acts on controls, and records the screen. The desktop is 1280 by 800, and your own [VNC client](#vnc-client) can connect to it over a WebSocket. - **Long-lived build machines.** A persistent sandbox keeps its disk across stop and start, so installed tools and build caches stay between sessions. To keep the disk after the reservation ends, take a [filesystem snapshot](#filesystem-snapshot). Automatic renewal stops when every sandbox on the Mac is stopped or paused, and the reservation then ends with its period. - **Remote access over SSH.** A developer or a script connects to the Mac over SSH to run commands and inspect builds. The CLI opens the connection itself, and other SSH clients sign in with a short-lived sandbox token in the user name. The token is limited to one sandbox and to SSH, so no project API key goes into the SSH command. - **Fleets of Macs.** One request reserves up to 100 Macs for parallel builds and tests. Each Mac is a separate reservation with its own ID, period, charge, and renewal. A minimum count accepts fewer Macs when not enough are available. ## Requirements [#requirements] Your organization must have macOS sandboxes turned on. Without it, reserving a Mac or creating a macOS sandbox fails with a [feature error](#errors). Sign in to the dashboard at [app.daytona.com ↗](https://app.daytona.com) and create a project API key. The examples read the key from an environment variable. ### Endpoints [#endpoints] macOS sandboxes have their own API address. Send all macOS requests to the macOS API. | **What** | **Address** | | ----------------------------------------- | ----------------------------------------------- | | Dashboard | **`https://app.daytona.com`** | | Daytona API (organizations, API keys) | **`https://api.daytona.com`** | | macOS API (reservations, macOS sandboxes) | **`https://api.us-macos.daytona.com`** | | Sandbox SSH | **`ssh.us-macos.daytona.com`**, port **`2222`** | | Region of the Macs | **`macos-1`** | The SDKs and the CLI read the API address and your key from environment variables. Give the region of the Macs, listed in the table above, on each reservation and each macOS create. ```bash export DAYTONA_API_KEY=dtn_... export DAYTONA_API_URL=https://api.us-macos.daytona.com export DAYTONA_REGION=macos-1 # the CLI's default region ``` ### Install [#install] Pin these exact versions. Pre-release and latest installs pull other versions that do not have the macOS features. Python 3.10 or later: ```bash pip install daytona==2.0.0a11 ``` Do not use `pip install --pre daytona`. It installs another version that does not have the macOS features. Node.js 22.4 or later: ```bash npm install @daytona/sdk@2.0.0-alpha.11 ``` Do not use `npm install @daytona/sdk@latest`. It installs another version that does not have the macOS features. On macOS or Linux: ```bash curl -fsSL https://github.com/daytona/clients/releases/download/v2.0.0-alpha.11/install.sh | sh -s -- --version 2.0.0-alpha.11 ``` With the API key set in the environment, the CLI needs no login. ### Connect [#connect] The SDK clients read your key and the macOS API address from the environment. ```python from daytona import Daytona daytona = Daytona() # reads DAYTONA_API_KEY and DAYTONA_API_URL # AsyncDaytona has the same methods with await ``` - `memory` and `disk` are in GiB. - Timeouts are in seconds. ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() // reads DAYTONA_API_KEY and DAYTONA_API_URL ``` - `resources.memory` and `resources.disk` are in GiB. - Every timeout is in seconds: `timeoutSeconds`, `waitSeconds` and `createTimeoutSeconds`. ## Create a macOS sandbox [#create-a-macos-sandbox] Create a macOS sandbox from a macOS image. Each sandbox runs on one of your [Mac reservations](#mac-reservations). When your organization holds no reservation in the region and [auto-reserve](#auto-reserve) is on, which it is by default, the create buys one for you, so you do not need to reserve a Mac first. With auto-reserve off, reserve a Mac before you create a sandbox. The base image has macOS, Xcode and common build tools. The following table lists its contents. | **Property** | **Value** | | ---------------- | ----------------------------------------------------------------------------------------------------------- | | Image | `base-macos` | | Operating system | macOS 26.6.2 | | Tools | Xcode 26.6 and its iPhone simulator, Homebrew (with git, Node.js 24, Ruby, CocoaPods, fastlane, gh and jq) and Python 3.14 | | User | `lume`, with home `/Users/lume` | | Password | `lume`. See [user and password](#user-and-password) | You choose the [size](#sizes) of each sandbox when you create it. Two sandboxes share one Mac when their sizes fit in the Mac together. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create_macos("base-macos", region="macos-1") ``` The following example creates two sandboxes of different sizes on one reservation: ```python from daytona.v2 import MacosResources r = daytona.v2.reservations.create(region="macos-1", model="m4pro-12c-24g", idempotency_key="shared-mac-1") a = daytona.v2.create_macos("base-macos", region="macos-1", reservation=r.id, resources=MacosResources(cpu=4, memory=8, disk=100)) b = daytona.v2.create_macos("base-macos", region="macos-1", reservation=r.id, resources=MacosResources(cpu=8, memory=16, disk=120)) ``` The following example creates a persistent sandbox that uses the whole Mac: ```python from daytona.v2 import MacosResources r = daytona.v2.reservations.create(region="macos-1", model="m4pro-12c-24g", idempotency_key="ios-builder-mac-1") sandbox = daytona.v2.create_macos( "base-macos", region="macos-1", reservation=r.id, resources=MacosResources(cpu=12, memory=24, disk=220), persistent=True, name="ios-builder", wait_seconds=120, ) print(sandbox.id, sandbox.reservation_id, sandbox.cpu, sandbox.memory, sandbox.disk) ``` | **Parameter** | **Type** | **Description** | | ---------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `image` | str | Sets the macOS image that the sandbox starts from, for example `base-macos` or a snapshot. This is the first positional argument. | | `region` | str | Sets the region, `macos-1`. | | `reservation` | str | Sets the reservation that the sandbox runs on: a reservation ID, or `"new"`. See [which reservation](#which-reservation). | | `auto_renew` | bool | Sets [automatic renewal](#automatic-renewal) of the reservation that the create buys. Only with `reservation="new"`. | | `resources` | MacosResources | Sets the size: `cpu`, the number of CPU cores; `memory`, the memory in GiB; and `disk`, the whole guest disk in GiB, macOS included. See [sizes](#sizes). | | `persistent` | bool | Keeps the disk across stop and start. See [filesystem persistence](#filesystem-persistence). | | `name` | str | Sets the display name. | | `wait_seconds` | int | Sets how many seconds the call waits for the sandbox to start. | | `create_timeout_seconds` | int | Sets how many seconds the server tries before it deletes the waiting sandbox. | - The request requires the `write:sandboxes` permission. - The other create options, `env`, `labels`, `secrets`, `ports`, and `network_policy`, work as on [Linux sandboxes](/docs/linux-sandboxes#create-a-linux-sandbox). ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.createMacos('base-macos', { region: 'macos-1' }) ``` The following example creates two sandboxes of different sizes on one reservation: ```typescript const r = await daytona.v2.reservations.create({ region: 'macos-1', model: 'm4pro-12c-24g', idempotencyKey: 'shared-mac-1', }) const a = await daytona.v2.createMacos('base-macos', { region: 'macos-1', reservation: r.id, resources: { cpu: 4, memory: 8, disk: 100 }, }) const b = await daytona.v2.createMacos('base-macos', { region: 'macos-1', reservation: r.id, resources: { cpu: 8, memory: 16, disk: 120 }, }) ``` The following example creates a persistent sandbox that uses the whole Mac: ```typescript const r = await daytona.v2.reservations.create({ region: 'macos-1', model: 'm4pro-12c-24g', idempotencyKey: 'ios-builder-mac-1', }) const sandbox = await daytona.v2.createMacos('base-macos', { region: 'macos-1', reservation: r.id, resources: { cpu: 12, memory: 24, disk: 220 }, persistent: true, name: 'ios-builder', waitSeconds: 120, }) console.log(sandbox.id, sandbox.reservationId) ``` | **Parameter** | **Type** | **Description** | | -------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `image` | string | Sets the macOS image that the sandbox starts from, for example `base-macos` or a snapshot. This is the first positional argument. | | `region` | string | Sets the region, `macos-1`. | | `reservation` | string | Sets the reservation that the sandbox runs on: a reservation ID, or `'new'`. See [which reservation](#which-reservation). | | `autoRenew` | boolean | Sets [automatic renewal](#automatic-renewal) of the reservation that the create buys. Only with `reservation: 'new'`. | | `resources` | MacosResources | Sets the size: `cpu`, the number of CPU cores; `memory`, the memory in GiB; and `disk`, the whole guest disk in GiB, macOS included. See [sizes](#sizes). | | `persistent` | boolean | Keeps the disk across stop and start. See [filesystem persistence](#filesystem-persistence). | | `name` | string | Sets the display name. | | `waitSeconds` | number | Sets how many seconds the call waits for the sandbox to start. | | `createTimeoutSeconds` | number | Sets how many seconds the server tries before it deletes the waiting sandbox. | - The request requires the `write:sandboxes` permission. - The other create options, `env`, `labels`, `secrets`, `ports`, and `networkPolicy`, work as on [Linux sandboxes](/docs/linux-sandboxes#create-a-linux-sandbox). ```bash daytona sandbox create-macos --region macos-1 --image base-macos ``` The following example creates two sandboxes of different sizes on one reservation: ```bash daytona sandbox create-macos --region macos-1 --image base-macos --reservation RESERVATION_ID \ --cores 4 --memory 8192 --disk 102400 daytona sandbox create-macos --region macos-1 --image base-macos --reservation RESERVATION_ID \ --cores 8 --memory 16384 --disk 122880 ``` The following example creates a persistent sandbox that uses the whole Mac: ```bash daytona sandbox create-macos --region macos-1 --image base-macos --reservation RESERVATION_ID \ --cores 12 --memory 24576 --disk 225280 --persistent --name ios-builder ``` | **Flag** | **Type** | **Description** | | ------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- | | `--image` | string | Sets the macOS image that the sandbox starts from, for example `base-macos` or a snapshot. | | `--region` | string | Sets the region, `macos-1`. | | `--reservation` | string | Sets the reservation that the sandbox runs on: a reservation ID, or `new`. See [which reservation](#which-reservation). | | `--auto-renew` | bool | Sets [automatic renewal](#automatic-renewal) of the reservation that the create buys. Only with `--reservation new`. | | `--cores` | int32 | Sets the number of CPU cores. See [sizes](#sizes). | | `--memory` | int32 | Sets the memory in MiB. See [sizes](#sizes). | | `--disk` | int32 | Sets the whole guest disk in MiB, macOS included. See [sizes](#sizes). | | `--persistent` | bool | Keeps the disk across stop and start. See [filesystem persistence](#filesystem-persistence). | | `--name` | string | Sets the display name. | | `--server-wait` | duration | Sets how long the server holds the create response for the sandbox to start, as a Go duration. `0s` answers at once. | | `--create-ttl` | duration | Sets how long the server tries before it deletes the waiting sandbox, as a Go duration. | - The request requires the `write:sandboxes` permission. - Other create options work as on [Linux sandboxes](/docs/linux-sandboxes#create-a-linux-sandbox), including the network flags `--block-all`, `--allow-domain`, and `--allow-cidr`. ```bash curl 'https://api.us-macos.daytona.com/sandboxes/macos' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "image": "base-macos", "region_id": "macos-1" }' ``` The following example creates two sandboxes of different sizes on one reservation: ```bash curl 'https://api.us-macos.daytona.com/sandboxes/macos' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "image": "base-macos", "region_id": "macos-1", "reservation": "RESERVATION_ID", "cores": 4, "memory_mib": 8192, "disk_mib": 102400 }' curl 'https://api.us-macos.daytona.com/sandboxes/macos' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "image": "base-macos", "region_id": "macos-1", "reservation": "RESERVATION_ID", "cores": 8, "memory_mib": 16384, "disk_mib": 122880 }' ``` The following example creates a persistent sandbox that uses the whole Mac: ```bash curl 'https://api.us-macos.daytona.com/sandboxes/macos' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Idempotency-Key: ios-builder-create-1' \ --data '{ "image": "base-macos", "region_id": "macos-1", "reservation": "RESERVATION_ID", "cores": 12, "memory_mib": 24576, "disk_mib": 225280, "persistent": true, "name": "ios-builder", "wait_seconds": 120 }' ``` | **Field** | **Type** | **Description** | | ------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------- | | `image` | string | Sets the macOS image that the sandbox starts from, by name or `img_` ID, for example `base-macos` or a snapshot. This field is required. | | `region_id` | string | Sets the region, `macos-1`. | | `reservation` | string | Sets the reservation that the sandbox runs on: a reservation ID, or `new`. See [which reservation](#which-reservation). | | `auto_renew` | boolean | Sets [automatic renewal](#automatic-renewal) of the reservation that the create buys. Only with `"reservation": "new"`. | | `cores` | integer | Sets the number of CPU cores. See [sizes](#sizes). | | `memory_mib` | integer | Sets the memory in MiB. See [sizes](#sizes). | | `disk_mib` | integer | Sets the whole guest disk in MiB, macOS included. See [sizes](#sizes). | | `persistent` | boolean | Keeps the disk across stop and start. See [filesystem persistence](#filesystem-persistence). | | `name` | string | Sets the display name. | | `wait_seconds` | integer | Sets how many seconds the server holds the request for the sandbox to start. `0` returns immediately. The default is 3. | | `create_timeout_seconds` | integer | Sets how many seconds the server tries before it deletes the waiting sandbox. | | `idempotency_key` | string | Makes a retried create return the same sandbox and never buy a second reservation. You can also send it as the `Idempotency-Key` header. | - The request requires the `write:sandboxes` permission. - The other create fields, `env`, `labels`, `secrets`, `ports`, and `network_policy`, work as on [Linux sandboxes](/docs/linux-sandboxes#create-a-linux-sandbox). ### Sizes [#sizes] A macOS sandbox takes its cores, memory and disk from the Mac of its reservation. The disk is the whole guest disk, macOS included. On the M4 Pro [model](#models-and-prices), the sandboxes of one Mac share 12 cores, 24 GiB memory and 220 GiB disk. Up to two sandboxes run on one Mac at the same time, and their sizes must fit in the Mac together. For example, one sandbox of 12 cores, 24 GiB memory and 220 GiB disk uses the whole Mac, and a sandbox of 4 cores, 8 GiB and 100 GiB fits beside a sandbox of 8 cores, 16 GiB and 120 GiB. A Mac fixes the size when it accepts the sandbox, and the sandbox reports that size from then on. | **Setting** | **SDK (GiB)** | **CLI (MiB)** | **API (MiB)** | **Minimum** | **Maximum on `m4pro-12c-24g`** | **If you omit it, on `m4pro-12c-24g`** | | ----------- | ----------------- | -------------- | ------------------ | ------------------ | ------------------------------ | -------------------------------------- | | Cores | **`resources.cpu`** (cores) | **`--cores`** | **`cores`** | 4 | 12 | 6 | | Memory | **`resources.memory`** | **`--memory`** | **`memory_mib`** | 4 GiB (4096 MiB) | 24 GiB (24576 MiB) | 12 GiB (12288 MiB) | | Disk | **`resources.disk`** | **`--disk`** | **`disk_mib`** | 80 GiB (81920 MiB) | 220 GiB (225280 MiB) | 110 GiB (112640 MiB) | ### Which reservation [#which-reservation] A create places the sandbox on a reservation. The reservation option decides which one, and whether the create buys a new one. | **Reservation option** | **Where the sandbox goes** | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | | Omitted | Any of your reservations in the region that has room. If you have none, [auto-reserve](#auto-reserve) buys one (if it is on). | | `reservation=""` | That reservation. | | `reservation="new"` | A new reservation that the create always buys for this sandbox. Only here can you also set `auto_renew`. | The create can wait for room on a reservation. Two options set how long: in seconds in the SDKs, and as a Go duration in the CLI. If the time runs out, a reservation that the create bought stays bought. | **Option** | **Description** | | -------------------------------------------------------------- | -------------------------------------------------------------------- | | `wait_seconds` (`waitSeconds`, `--server-wait`) | How long the call waits for the sandbox to start. | | `create_timeout_seconds` (`createTimeoutSeconds`, `--create-ttl`) | How long the server tries before it deletes the waiting sandbox. | ### Get a sandbox [#get-a-sandbox] Get a macOS sandbox by its ID, or list the sandboxes in the macOS region. ```python sandbox = daytona.v2.get("SANDBOX_ID") ``` ```typescript const sandbox = await daytona.v2.get('SANDBOX_ID') ``` ```bash daytona sandbox get SANDBOX_ID daytona sandbox list --region macos-1 ``` ## Mac reservations [#mac-reservations] A reservation gives your organization one dedicated Mac for a 24-hour period. Nobody else uses that Mac while you hold it. You pay for each period when it starts. The first period starts when a Mac accepts the reservation, not when you send the request, and time spent waiting for a Mac is not charged. You cannot end a reservation early. It ends at the end of its period unless it renews. macOS sandboxes run only on your reservations: a create picks a reservation with room left, or you name one. Up to two sandboxes run on the Mac at the same time, and you choose the [size](#sizes) of each sandbox when you create it. | **Status** | **Description** | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | `pending_charge` | We are charging the period. | | `pending_mac` | The period is paid. The reservation waits for an available Mac. If no Mac accepts it within 5 minutes, it becomes `failed` and we refund the charge. | | `active` | A Mac holds the reservation. `period_end` tells you when the period ends. | | `ending` | The period ended. We stop the sandboxes, save persistent disks and erase the Mac. See [when a reservation ends](#when-a-reservation-ends). | | `released` | The reservation ended. `end_reason` tells you why, for example `expired`. | | `failed` | The charge failed, or no Mac accepted the reservation (refunded). | ### Models and prices [#models-and-prices] The production Macs are **Apple M4 Pro, 12 cores, 24 GB memory**. Always give this model when you reserve. Its model ID is in the table below. The price of one reservation of this model is **$2.5032 per Mac-hour, $60.08 per 24-hour period**. | **Model** | **Cores** | **Memory** | **Sandbox disk** | **Sandboxes at a time** | | --------------------- | --------- | ---------- | ---------------- | ----------------------- | | **`m4pro-12c-24g`** | 12 | 24 GiB | 220 GiB | Up to 2 | The sizes of the sandboxes on one Mac must fit in its cores, memory and sandbox disk together. See [sizes](#sizes). Read the current price and the number of available Macs from the Mac catalog. An available Mac is one that nobody has reserved. The number is a guide only: another purchase can reserve an available Mac before yours. ```python catalog = daytona.v2.mac_models.catalog(region="macos-1") for region in catalog.regions: for entry in region.models: price = entry.price print( entry.model.id, "available:", entry.available, "per period: $%.2f" % (price.period_cents / 100) if price else "no price", ) # Model specs only; the catalog adds prices and available Macs per region for model in daytona.v2.mac_models.list(): print(model.id, model.cores, model.memory_mib, model.max_sandboxes) ``` ```typescript const catalog = await daytona.v2.macModels.catalog({ region: 'macos-1' }) for (const region of catalog.regions) { for (const entry of region.models) { const perPeriod = entry.price ? `$${(entry.price.periodCents / 100).toFixed(2)}` : 'no price' console.log(entry.model.id, 'available:', entry.available, 'per period:', perPeriod) } } // Model specs only; the catalog adds prices and available Macs per region for (const model of await daytona.v2.macModels.list()) { console.log(model.id, model.cores, model.memoryMib, model.maxSandboxes) } ``` ```bash daytona mac-model list --region macos-1 ``` ```bash # Catalog: available Macs and prices per model; region_ids is a comma-separated list, all regions by default curl 'https://api.us-macos.daytona.com/mac-catalog?region_ids=macos-1' \ --header 'Authorization: Bearer YOUR_API_KEY' # Model specs only; the catalog adds prices and available Macs per region curl 'https://api.us-macos.daytona.com/mac-models' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` | **Field** | **Description** | | ---------------------- | --------------------------------------------------------------------------------------------------- | | `default_model` | The model a reservation in the region gets when it names none. | | `available` | The number of Macs of the model that nobody has reserved. A guide only; another purchase can reserve one first. | | `price` | `period_cents`, `cents_per_hour`, `period_seconds` and `currency`. `null` where billing is not enabled. | | `max_sandboxes` | The most sandboxes a Mac of the model runs at once. | | `sandbox_disk_mib` | The disk room for all sandboxes on one Mac, stopped sandboxes included. | ### Reserve a Mac [#reserve-a-mac] Reserve one Mac of a model in a region. Each purchase has an idempotency key. If you retry with the same key, you get the same reservation and you do not pay again. If you do not give a key, the SDK and the CLI make a new key for each call, so a retry buys a second Mac. Give your own key when your code can retry. ```python reservation = daytona.v2.reservations.create( region="macos-1", model="m4pro-12c-24g", idempotency_key="build-mac-2026-10-24", ) print(reservation.id, reservation.status) ``` | **Parameter** | **Type** | **Description** | | ----------------- | -------- | ---------------------------------------------------------------------------------------------------------------- | | `region` | str | Sets the region, `macos-1`. This parameter is required. | | `model` | str | Sets the Mac [model](#models-and-prices), `m4pro-12c-24g`. | | `idempotency_key` | str | Sets the idempotency key. Defaults to a new key for each call. | | `auto_renew` | bool | Sets [automatic renewal](#automatic-renewal). If you omit it, it follows your organization's auto-reserve setting, which is on by default. | ```typescript const reservation = await daytona.v2.reservations.create({ region: 'macos-1', model: 'm4pro-12c-24g', idempotencyKey: 'build-mac-2026-10-24', }) console.log(reservation.id, reservation.status) ``` | **Parameter** | **Type** | **Description** | | ---------------- | -------- | ---------------------------------------------------------------------------------------------------------------- | | `region` | string | Sets the region, `macos-1`. This parameter is required. | | `model` | string | Sets the Mac [model](#models-and-prices), `m4pro-12c-24g`. | | `idempotencyKey` | string | Sets the idempotency key. Defaults to a new key for each call. | | `autoRenew` | boolean | Sets [automatic renewal](#automatic-renewal). If you omit it, it follows your organization's auto-reserve setting, which is on by default. | ```bash daytona reservation create --region macos-1 --model m4pro-12c-24g \ --idempotency-key build-mac-2026-10-24 ``` | **Flag** | **Type** | **Description** | | ------------------- | -------- | ---------------------------------------------------------------------------------------------------------------- | | `--region` | string | Sets the region, `macos-1`. | | `--model` | string | Sets the Mac [model](#models-and-prices), `m4pro-12c-24g`. | | `--idempotency-key` | string | Sets the idempotency key. Defaults to a new key for each invocation. | | `--auto-renew` | bool | Sets [automatic renewal](#automatic-renewal). If you omit it, it follows your organization's auto-reserve setting, which is on by default. | ```bash curl 'https://api.us-macos.daytona.com/reservations' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Idempotency-Key: build-mac-2026-10-24' \ --data '{ "region_id": "macos-1", "model": "m4pro-12c-24g" }' ``` | **Field** | **Type** | **Description** | | ----------------- | --------- | ---------------------------------------------------------------------------------------------------------------- | | `Idempotency-Key` | header | Sets the idempotency key. This header is required; the API does not generate a key. | | `region_id` | string | Sets the region, `macos-1`. This field is required. | | `model` | string | Sets the Mac [model](#models-and-prices), `m4pro-12c-24g`. | | `auto_renew` | boolean | Sets [automatic renewal](#automatic-renewal). If you omit it, it follows your organization's auto-reserve setting, which is on by default. | ### Reserve many Macs [#reserve-many-macs] Reserve 1 to 100 Macs of one model in one request. Each Mac is a separate reservation with its own ID, period, charge and renewal. By default, the request is all or nothing: if fewer Macs are available than you ask for, it reserves none and fails because no Mac is available. Set a minimum count to accept fewer: the request then reserves as many as are available, if that is at least the minimum. ```python batch = daytona.v2.reservations.create_bulk( region="macos-1", model="m4pro-12c-24g", count=20, min_count=10, idempotency_key="ci-fleet-2026-10-24", ) print(f"reserved {batch.reserved} of {batch.requested} Macs") ids = [r.id for r in batch.reservations] ``` | **Parameter** | **Type** | **Description** | | ----------------- | -------- | ----------------------------------------------------------------------- | | `count` | int | Sets how many Macs to reserve, 1 to 100. | | `min_count` | int | Sets the fewest Macs to accept when fewer than the count are available. Defaults to the count, all or nothing. | | `idempotency_key` | str | Sets the idempotency key. Defaults to a new key for each call. | ```typescript const batch = await daytona.v2.reservations.createBulk({ region: 'macos-1', model: 'm4pro-12c-24g', count: 20, minCount: 10, idempotencyKey: 'ci-fleet-2026-10-24', }) console.log(`reserved ${batch.reserved} of ${batch.requested} Macs`) ``` | **Parameter** | **Type** | **Description** | | ---------------- | -------- | ----------------------------------------------------------------------- | | `count` | number | Sets how many Macs to reserve, 1 to 100. | | `minCount` | number | Sets the fewest Macs to accept when fewer than the count are available. Defaults to the count, all or nothing. | | `idempotencyKey` | string | Sets the idempotency key. Defaults to a new key for each call. | A dry run shows the price and the available Macs and reserves nothing. ```bash daytona reservation create --region macos-1 --model m4pro-12c-24g --count 20 --dry-run daytona reservation create --region macos-1 --model m4pro-12c-24g --count 20 --min-count 10 \ --idempotency-key ci-fleet-2026-10-24 ``` | **Flag** | **Type** | **Description** | | ------------------- | -------- | ----------------------------------------------------------------------- | | `--count` | int | Sets how many Macs to reserve, 1 to 100. | | `--min-count` | int | Sets the fewest Macs to accept when fewer than the count are available. Defaults to the count, all or nothing. | | `--idempotency-key` | string | Sets the idempotency key. Defaults to a new key for each invocation. | | `--dry-run` | bool | Prints the price and the available Macs and reserves nothing. | ```bash curl 'https://api.us-macos.daytona.com/reservations/bulk' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Idempotency-Key: ci-fleet-2026-10-24' \ --data '{ "region_id": "macos-1", "model": "m4pro-12c-24g", "count": 20, "min_count": 10 }' ``` | **Field** | **Type** | **Description** | | ----------------- | --------- | ----------------------------------------------------------------------- | | `Idempotency-Key` | header | Sets the idempotency key. This header is required; the API does not generate a key. | | `count` | integer | Sets how many Macs to reserve, 1 to 100. | | `min_count` | integer | Sets the fewest Macs to accept when fewer than the count are available. Defaults to the count, all or nothing. | ### List reservations [#list-reservations] List the reservations of your organization, one page at a time. The list returns the open reservations and the reservations that ended in the last 30 days. ```python cursor = None while True: page = daytona.v2.reservations.list(limit=100, cursor=cursor) for r in page.items: print(r.id, r.status, r.model, r.period_end, r.auto_renew) cursor = page.next_cursor # None on the last page if cursor is None: break ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | ---------------------------------------------------------------------------------- | | `limit` | int | Sets the page size, from `1` to `200`. The default is `100`. | | `cursor` | str | Resumes the list after the previous page. Pass the `next_cursor` of that page. | ```typescript let cursor: string | undefined do { const page = await daytona.v2.reservations.list({ limit: 100, cursor }) for (const r of page.items) { console.log(r.id, r.status, r.model, r.periodEnd, r.autoRenew) } cursor = page.nextCursor // undefined on the last page } while (cursor) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | ---------------------------------------------------------------------------------- | | `limit` | number | Sets the page size, from `1` to `200`. The default is `100`. | | `cursor` | string | Resumes the list after the previous page. Pass the `nextCursor` of that page. | ```bash daytona reservation list ``` ```bash # Paginated; follow next_cursor for more rows curl 'https://api.us-macos.daytona.com/reservations?limit=100' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` | **Field** | **Type** | **Description** | | ------------ | ------------- | -------------------------------------------------------------------------------------- | | `limit` | integer | Sets the maximum number of items, from `1` to `200`. The default is `100`. | | `cursor` | string | Pass the `next_cursor` value of the previous response to read the next page. | #### Iterate over all reservations [#iterate-over-all-reservations] Iterate over every reservation of your organization without handling page cursors. The iterator fetches the next page when the current one is exhausted and stops when the server returns no cursor. ```python for r in daytona.v2.reservations.iter(): print(r.id, r.status, r.model, r.period_end, r.auto_renew) ``` ```typescript for await (const r of daytona.v2.reservations.iter()) { console.log(r.id, r.status, r.model, r.periodEnd, r.autoRenew) } ``` ### Get a reservation [#get-a-reservation] Get one reservation of your organization by its ID. The response has the same fields as an item of the list, including its current status and the end of its period. ```python r = daytona.v2.reservations.get("RESERVATION_ID") print(r.id, r.status, r.period_end, r.auto_renew) ``` ```typescript const r = await daytona.v2.reservations.get('RESERVATION_ID') console.log(r.id, r.status, r.periodEnd, r.autoRenew) ``` ```bash daytona reservation get RESERVATION_ID ``` ```bash curl 'https://api.us-macos.daytona.com/reservations/RESERVATION_ID' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ### Renew a reservation [#renew-a-reservation] Renew a reservation to pay for the next 24-hour period on the same Mac. You keep the Mac, its sandboxes and their disks. Use a new key for each period you want to buy, and the same key when you retry. ```python daytona.v2.reservations.renew(reservation.id, idempotency_key=f"renew-{reservation.id}-2") ``` ```typescript await daytona.v2.reservations.renew(reservation.id, { idempotencyKey: `renew-${reservation.id}-2` }) ``` ```bash daytona reservation renew RESERVATION_ID --idempotency-key renew-RESERVATION_ID-2 ``` ```bash curl 'https://api.us-macos.daytona.com/reservations/RESERVATION_ID/renew' \ --request POST \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Idempotency-Key: renew-RESERVATION_ID-2' ``` - The request requires the `write:sandboxes` permission. - The `Idempotency-Key` header is required. - The API does not generate an idempotency key. ### Automatic renewal [#automatic-renewal] When automatic renewal is on, we renew the reservation in the last hour of its period, **but only while a sandbox on that Mac is active** (being created, starting or running). If all its sandboxes are stopped or paused, or it has none, the reservation does not renew and ends at the end of its period. If a renewal fails, the reservation records the reason and ends at the end of its period. Turn automatic renewal on or off for one reservation. ```python daytona.v2.reservations.update(reservation.id, auto_renew=False) ``` ```typescript await daytona.v2.reservations.update(reservation.id, { autoRenew: false }) ``` ```bash daytona reservation update RESERVATION_ID --auto-renew=false ``` ```bash curl 'https://api.us-macos.daytona.com/reservations/RESERVATION_ID' \ --request PATCH \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "auto_renew": false }' ``` ### Auto-reserve [#auto-reserve] Auto-reserve buys a Mac for you when you create a macOS sandbox and your organization holds no live reservation in the region. It buys the cheapest model that fits the sandbox, with automatic renewal on. If you want to control every purchase, turn auto-reserve off and reserve Macs yourself. - It is **on by default**. It holds at most **2** reservations at a time. Above that, a create fails because the auto-reserve limit is reached. - It does not buy a Mac when you have a reservation that is only full: no free slot, or too little disk left. - An organization admin can turn it off, or change the limit, in the dashboard: Settings, **Auto-reserve Macs**, or through the [macOS settings](#macos-settings). ### macOS settings [#macos-settings] The macOS settings control [auto-reserve](#auto-reserve) for macOS sandboxes. With auto-reserve on, a macOS create in a region where the organization holds no live Mac reservation buys a 24-hour reservation that renews while a sandbox runs on it. Auto-reserve is on by default, and the organization caps how many auto-reserved reservations it holds at once. #### Get the settings [#get-the-settings] Get the organization's macOS settings. ```bash curl 'https://api.daytona.com/orgs/ORGANIZATION_ID/macos-settings' \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' ``` ```json { "macos_auto_reserve": true, "macos_auto_reserve_max_reservations": 2, "macos_auto_reserve_disabled_at": null, "macos_auto_reserve_disabled_by": null } ``` The response has the following fields: | **Field** | **Description** | | -------------------------------------- | --------------------------------------------------------------------------------------------------- | | `macos_auto_reserve` | Shows whether auto-reserve is on. | | `macos_auto_reserve_max_reservations` | The most auto-reserved reservations the organization holds at once. | | `macos_auto_reserve_disabled_at` | Records when auto-reserve was last turned off. The value is `null` while auto-reserve is on. | | `macos_auto_reserve_disabled_by` | Records who last turned auto-reserve off. The value is `null` while auto-reserve is on. | #### Set the settings [#set-the-settings] Turn auto-reserve on or off, or change the cap on auto-reserved reservations. Fields left out of the request keep their stored values. ```bash curl 'https://api.daytona.com/orgs/ORGANIZATION_ID/macos-settings' \ --request PATCH \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "macos_auto_reserve": true, "macos_auto_reserve_max_reservations": 4 }' ``` | **Field** | **Type** | **Description** | | -------------------------------------- | -------- | ------------------------------------------------------------------------------------- | | `macos_auto_reserve` | boolean | Turns auto-reserve on or off. If omitted, the stored value stays unchanged. Turning auto-reserve off while it is already off keeps the original `macos_auto_reserve_disabled_at` and `macos_auto_reserve_disabled_by`. Turning auto-reserve on clears both fields. | | `macos_auto_reserve_max_reservations` | integer | Sets the most auto-reserved reservations the organization holds at once. If omitted, the stored value stays unchanged. The value must be at least `1`. A cap below `1` returns `400`. | - The request requires the `write:organization` permission. - Set at least one field in the request. ### When a reservation ends [#when-a-reservation-ends] A reservation ends at the end of its period when it does not renew. There is no grace period, and we do not send a notice. Watch the end of the period, the automatic renewal setting and any renewal error on your reservations, or [renew by hand](#renew-a-reservation). At the end, in this order: 1. The reservation enters the ending status. You cannot start, resume or create sandboxes on it. 2. **Persistent sandboxes** are shut down (paused ones are resumed first, then shut down). Each one that ran is **exported as an image**: an image without a name that records the sandbox's ID. 3. **Sandboxes that are not persistent** are deleted. Their data is lost. 4. When every export is saved or has failed, the Mac is **erased**: the sandbox disks, the console logs, the macOS user and its files. A failed export holds the erase for up to 24 hours. The disk of that sandbox is lost. 5. The Mac is checked and goes back to the pool for the next customer. 6. The reservation enters the released status. Every sandbox on it is deleted. #### What you keep [#what-you-keep] | **Data** | **After the end** | | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | Disk of a persistent sandbox | Kept as an image without a name, unless its export fails. It is deleted when no sandbox is created from it for 30 days. Give it a name to keep it. | | Snapshots you made | Kept. Named ones until you delete them. Unnamed ones while a sandbox is created from them at least once every 7 days. | | Usage records and bills | Kept. | | Sandboxes that are not persistent | Lost. | | Memory of paused sandboxes | Lost. The disk is exported. | | Console logs | Lost. | | The Mac | Erased. | #### Continue after the end [#continue-after-the-end] Find the exported image, then create a sandbox from it on a reservation. You can also give the image a name to keep it. The new sandbox needs a reservation with room for the disk: an existing one, a new one you buy, or one that auto-reserve buys. It gets a new machine identity. ```python exports = daytona.v2.images.list(anonymous=True, sandbox_id="OLD_SANDBOX_ID") image = exports.items[0] daytona.v2.images.promote(image.id, "ios-builder-day-2") # optional: keep it sandbox = daytona.v2.create_macos(image.id, region="macos-1", persistent=True, wait_seconds=120) ``` ```typescript const exports = await daytona.v2.images.list({ anonymous: true, sandboxId: 'OLD_SANDBOX_ID' }) const image = exports.items[0] await daytona.v2.images.promote(image.id, 'ios-builder-day-2') // optional: keep it const sandbox = await daytona.v2.createMacos(image.id, { region: 'macos-1', persistent: true, waitSeconds: 120 }) ``` ```bash daytona image list --anonymous true --sandbox OLD_SANDBOX_ID daytona image promote IMAGE_ID ios-builder-day-2 daytona sandbox create-macos --region macos-1 --image IMAGE_ID --persistent ``` ## Filesystem snapshot [#filesystem-snapshot] A filesystem snapshot saves the disk of a stopped persistent macOS sandbox as an image. You can create new sandboxes from it on any Mac of the region. Snapshots save the disk only, not the memory. A new sandbox from an image gets a new machine identity. Apps that are bound to one machine (for example an iCloud sign-in or some licences) need you to sign in again. ```python sandbox.stop() image = sandbox.capture_image(name="ios-builder-ready") image = daytona.v2.images.get(image.id, wait="ready", timeout=3600) print(image.id, image.status) copy = daytona.v2.create_macos("ios-builder-ready", region="macos-1", persistent=True) ``` - The requests require the `write:images` and `write:sandboxes` permissions. - The sandbox must be persistent and stopped. - The sandbox must have an active reservation. - The sandbox cannot start until the snapshot is `ready`. ```typescript await sandbox.stop() const image = await sandbox.captureImage({ name: 'ios-builder-ready' }) const ready = await daytona.v2.images.get(image.id, { wait: 'ready', timeoutSeconds: 3600 }) const copy = await daytona.v2.createMacos('ios-builder-ready', { region: 'macos-1', persistent: true }) ``` - The requests require the `write:images` and `write:sandboxes` permissions. - The sandbox must be persistent and stopped. - The sandbox must have an active reservation. - The sandbox cannot start until the snapshot is `ready`. ```bash daytona sandbox stop SANDBOX_ID daytona image capture SANDBOX_ID --name ios-builder-ready daytona image list --name ios-builder-ready daytona sandbox create-macos --region macos-1 --image ios-builder-ready --persistent ``` - The requests require the `write:images` and `write:sandboxes` permissions. - The sandbox must be persistent and stopped. - The sandbox must have an active reservation. - The sandbox cannot start until the snapshot is `ready`. ## Filesystem persistence [#filesystem-persistence] A persistent macOS sandbox keeps its disk on its Mac across stop and start for as long as the reservation lives. To keep the disk after the reservation, make a [filesystem snapshot](#filesystem-snapshot), or let the end of the reservation save it (see [when a reservation ends](#when-a-reservation-ends)). ## Lifecycle [#lifecycle] Every macOS sandbox moves through a lifecycle. Stop, start, pause and resume need a **persistent** sandbox. A sandbox that is not persistent can only run or be deleted. If a Mac restarts, a running persistent sandbox comes back stopped with its disk. A running sandbox that is not persistent is lost. | **Action** | **What happens** | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Stop | macOS shuts down. The disk stays on the same Mac and keeps its disk room on the reservation. The cores, memory and slot become available to other sandboxes. | | Start | macOS boots from the same disk on the same Mac. The reservation needs an open slot and enough cores and memory for the sandbox, or start fails with `NO_FREE_SLOT`. Start never buys a reservation. | | Pause | The Mac saves the memory of the sandbox. It keeps its place on the reservation. | | Resume | The sandbox continues from the saved memory. If the memory cannot be restored, macOS boots from the disk and `mac_boot_mode` is `cold_after_restore_failure`. | | Delete | The sandbox and its disk are erased. You cannot undo this. | A stopped or paused sandbox **does not keep automatic renewal going**. If all sandboxes on a reservation are stopped or paused at the end of the period, the reservation ends. See [when a reservation ends](#when-a-reservation-ends). ### Stop / start [#stop--start] Stop a persistent macOS sandbox to shut down macOS and keep its disk on the same Mac. Start boots macOS from the same disk on the same Mac. ```python sandbox.stop() sandbox.wait(until="stopped") sandbox.start(timeout=120) # Stop a sandbox by ID, without fetching it first daytona.v2.stop("SANDBOX_ID") # Start a stopped sandbox by ID daytona.v2.start("SANDBOX_ID", timeout=120) ``` ```typescript await sandbox.stop() await sandbox.wait({ until: 'stopped' }) await sandbox.start({ timeoutSeconds: 120 }) // Stop a sandbox by ID, without fetching it first await daytona.v2.stop('SANDBOX_ID') // Start a stopped sandbox by ID await daytona.v2.start('SANDBOX_ID', { timeoutSeconds: 120 }) ``` ```bash daytona sandbox stop SANDBOX_ID daytona sandbox start SANDBOX_ID ``` ```bash curl 'https://api.us-macos.daytona.com/sandboxes/{sandboxId}/stop' \ --request POST \ --header 'Authorization: Bearer YOUR_API_KEY' # Long-poll until the sandbox is stopped curl 'https://api.us-macos.daytona.com/sandboxes/{sandboxId}?wait=stopped&timeout_ms=60000' \ --header 'Authorization: Bearer YOUR_API_KEY' curl 'https://api.us-macos.daytona.com/sandboxes/{sandboxId}/start' \ --request POST \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ### Pause / resume [#pause--resume] Pause a persistent macOS sandbox to save its memory on the Mac. Resume continues the sandbox from the saved memory. ```python sandbox.pause() sandbox.resume() # Pause a sandbox by ID, without fetching it first daytona.v2.pause("SANDBOX_ID") # Resume a paused sandbox by ID daytona.v2.resume("SANDBOX_ID") ``` ```typescript await sandbox.pause() await sandbox.resume() // Pause a sandbox by ID, without fetching it first await daytona.v2.pause('SANDBOX_ID') // Resume a paused sandbox by ID await daytona.v2.resume('SANDBOX_ID') ``` ```bash daytona sandbox pause SANDBOX_ID daytona sandbox resume SANDBOX_ID ``` ```bash curl 'https://api.us-macos.daytona.com/sandboxes/{sandboxId}/pause' \ --request POST \ --header 'Authorization: Bearer YOUR_API_KEY' curl 'https://api.us-macos.daytona.com/sandboxes/{sandboxId}/resume' \ --request POST \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ### Fork [#fork] Fork a persistent macOS sandbox to copy its disk into a new sandbox. A fork does not copy memory, and a fork that asks for memory fails. ```python twin = sandbox.fork(name="ios-builder-2") ``` ```typescript const twin = await sandbox.fork({ name: 'ios-builder-2' }) ``` ```bash daytona sandbox fork SANDBOX_ID --name ios-builder-2 ``` ```bash curl 'https://api.us-macos.daytona.com/sandboxes/{sandboxId}/fork' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "name": "ios-builder-2" }' ``` | **Field** | **Type** | **Description** | | --------- | -------- | ---------------------------------------------------------------- | | `name` | string | Sets the display name of the fork. The default is `-fork`. | ### Delete [#delete] Delete a macOS sandbox to erase the sandbox and its disk. You cannot undo this. ```python sandbox.delete() ``` ```typescript await sandbox.delete() ``` ```bash daytona sandbox delete SANDBOX_ID ``` ```bash curl 'https://api.us-macos.daytona.com/sandboxes/{sandboxId}' \ --request DELETE \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ## Run commands [#run-commands] Run commands in a macOS sandbox, in the foreground or in the background. Files, git and PTYs work as on Linux sandboxes. ```python result = sandbox.exec("sw_vers -productVersion && xcodebuild -version") print(result.exit_code, result.output) handle = sandbox.process.start("xcodebuild -scheme App build") # runs in the background print(handle.wait().exit_code) ``` ```typescript const result = await sandbox.exec('sw_vers -productVersion && xcodebuild -version') console.log(result.exitCode, result.output) ``` ```bash daytona sandbox exec SANDBOX_ID -- sw_vers -productVersion daytona sandbox exec SANDBOX_ID --tty -- zsh # an interactive shell daytona sandbox cp ./App.zip SANDBOX_ID:/Users/lume/App.zip ``` ## SSH [#ssh] Connect to a macOS sandbox over SSH. The CLI opens SSH for you. With your own SSH client, make a short-lived sandbox token that allows SSH, and put the sandbox ID and the token in the user name, joined by a hash sign (#). The gateway checks the token, not a password or an SSH key. A token works until it expires. Make a new one when you need it. ```python token = sandbox.create_access_token(operations=["ssh"], ttl_seconds=3600) print(f'ssh -p 2222 "{sandbox.id}#{token.access_token}@ssh.us-macos.daytona.com"') ``` Do not put a project API key in an SSH command. Use a sandbox token: it is limited to this sandbox and to SSH. ```typescript const token = await sandbox.createAccessToken({ operations: ['ssh'], ttlSeconds: 3600 }) console.log(`ssh -p 2222 "${sandbox.id}#${token.accessToken}@ssh.us-macos.daytona.com"`) ``` Do not put a project API key in an SSH command. Use a sandbox token: it is limited to this sandbox and to SSH. ```bash daytona sandbox ssh SANDBOX_ID daytona sandbox ssh SANDBOX_ID -- ls /Users/lume ``` ## Desktop [#desktop] macOS sandboxes have a desktop of 1280 × 800. Open the sandbox in the dashboard and choose the desktop view. The desktop takes mouse and keyboard input as soon as it connects. ### User and password [#user-and-password] A macOS sandbox signs in to its macOS user when it starts, so the desktop opens without a login screen. macOS asks for the password of this user when you change a protected setting, for example when you allow an app under **Privacy & Security**, and when you unlock the screen. SSH and the desktop view do not use this password. Daytona checks your sandbox token instead. The following table lists the user settings of the base image. A sandbox from a [filesystem snapshot](#filesystem-snapshot) keeps the user settings of the sandbox that the snapshot was taken from, including a changed password. | **Property** | **Value** | | ---------------- | ----------------------------------------------------------------------------------------------- | | User | `lume` | | Password | `lume` | | Administrator | Yes | | `sudo` | Does not ask for a password | | Sign-in at start | Automatic | | Screen lock | Only when you lock the screen or the display sleeps. The sandbox does not sleep on its own. | ### Computer use [#computer-use] Take screenshots and send mouse and keyboard input inside the sandbox. Computer use can also read the accessibility tree, act on controls, and record the screen. ```python import base64 cu = sandbox.computer_use cu.start() print(cu.status()) shot = cu.screen.screenshot() with open("screen.png", "wb") as f: f.write(base64.b64decode(shot.screenshot)) cu.mouse.click(x=640, y=400) cu.keyboard.type(text="hello from Daytona") cu.keyboard.hotkey(keys="cmd+space") # modifiers: cmd, ctrl, alt (option), shift print(cu.display.windows()) ``` - The request requires the `write:sandboxes` permission. - `cu.a11y` reads the accessibility tree and acts on controls, and `cu.recording` records the screen. ```typescript const cu = sandbox.computerUse await cu.start() const shot = await cu.screen.screenshot() // shot.screenshot is a base64 PNG await cu.mouse.click({ x: 640, y: 400 }) await cu.keyboard.type({ text: 'hello from Daytona' }) await cu.keyboard.hotkey({ keys: 'cmd+space' }) ``` - The request requires the `write:sandboxes` permission. - `cu.a11y` reads the accessibility tree and acts on controls, and `cu.recording` records the screen. ### VNC client [#vnc-client] Connect your own VNC client to the desktop. The desktop is also a VNC connection over a WebSocket. Make a token with the desktop operation and connect a noVNC client to the address below. The proxy does the VNC password step for you. Your client must support the DesktopSize encoding (noVNC does). ```text wss://proxy.us-macos.daytona.app/vnc/SANDBOX_ID?daytona_token=TOKEN ``` ```python token = sandbox.create_access_token(operations=["desktop"], ttl_seconds=3600) ``` ## Logs [#logs] A macOS sandbox has a console log, and your own processes can keep their own logs. The console log is erased with the Mac when the reservation ends. Copy what you need before then. | **Log** | **Description** | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Console log** | The macOS sandbox's console output and our lifecycle lines. The API route is `GET /sandboxes/SANDBOX_ID/console-logs`. | | **Your own process logs** | Run a command with `process.start(...)` and read `handle.logs()` or `handle.stream_logs()` (TypeScript: `logs()`, `streamLogs()`), or write logs to a file and copy it out. | | **Usage** | `daytona sandbox usage SANDBOX_ID`. | ```bash daytona sandbox logs SANDBOX_ID daytona sandbox logs SANDBOX_ID --follow ``` ## Errors [#errors] The SDKs raise these errors with the codes in the following table. If something does not work as this page says, send us the sandbox ID or the reservation ID and the time. We read the server logs from those. | **Code** | **Meaning** | **What to do** | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | | **`NO_ACTIVE_RESERVATION`** | You have no live reservation in the region, and auto-reserve is off. Resume also returns it when the reservation of the paused sandbox is `ending`. | Reserve a Mac, or use `reservation="new"`. | | **`NO_FREE_SLOT`** | Your reservations have no room for this size. | Use a smaller size, delete a sandbox, or reserve another Mac. | | **`MAC_DISK_FULL`** | The Macs of the reservations with room for this size have too little disk space left. A smaller `disk` does not help. | Delete a macOS sandbox on one of them, or reserve another Mac. | | **`NO_MAC_AVAILABLE`** | No Mac of the model is available to reserve. | Try again later, or reserve fewer (`min_count`). | | **`AUTO_RESERVE_LIMIT_REACHED`** | Auto-reserve holds its maximum number of reservations. | Reserve a Mac yourself, or ask an admin to raise the limit. | | **`IDEMPOTENCY_KEY_REUSED`** | The key was used for a different purchase, or for a sandbox create with a different size. | Use a new key. | | **`INSUFFICIENT_BALANCE`** | Your balance does not cover the period of each Mac you reserve (402). | Add balance, or reserve fewer Macs. | | **`CHARGE_FAILED`** | The charge for the period failed (402). | Contact us. | | **`SNAPSHOT_IN_PROGRESS`** | A snapshot of this sandbox is in progress. | Wait until the image is `ready`. | | **`NOT_SUPPORTED_FOR_CLASS`** | The action does not work on macOS, for example a fork with memory. | See the section for that action. | | **`FEATURE_NOT_ENABLED`** | macOS sandboxes are not on for your organization. | Contact us. | ## Permissions [#permissions] macOS sandboxes and Mac reservations use the sandbox permissions of their project, which you can grant to an [organization role](/docs/organizations#roles) or an [API key](/docs/api-keys). The macOS settings of the organization use organization permissions. The [audit logs](/docs/audit-logs) record sandbox creates and deletes, and Mac reservations and renewals. | **Permission** | **Grants** | | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------- | | **`read:sandboxes`** | Get sandboxes, and list and get Mac reservations | | **`write:sandboxes`** | Create, stop, start, pause, resume, and fork sandboxes, use the toolbox and SSH, and reserve, renew, and update Mac reservations | | **`delete:sandboxes`** | Delete sandboxes | | **`write:images`** | Capture filesystem snapshots as images | | **`read:organization`** | Get the macOS settings | | **`write:organization`** | Change the macOS settings | # GPU Sandboxes (/docs/gpu-sandboxes) GPU sandboxes are **Linux sandboxes with one or more dedicated GPUs** attached. Each sandbox has its own files, network connection, and fixed amount of processor, memory, and disk. The GPUs assigned to a sandbox are not shared with other sandboxes while it runs, and Daytona isolates each GPU sandbox from other sandboxes and from the host. GPU sandboxes run workloads that require GPU acceleration, such as model inference, training, fine-tuning, and reinforcement learning. A create request asks for a number of GPUs, and Daytona places the sandbox on a host that has enough free GPUs. A GPU sandbox is ephemeral: deleting it discards its filesystem. Its state can be saved as a checkpoint that includes its processes, memory, and GPU memory, and resumed in a new GPU sandbox. The available GPU models and the features and limits of GPU sandboxes may change over time. | **Term** | **Description** | | -------------- | ------------------------------------------------------------------------------------------------ | | **Sandbox** | An isolated Linux machine with dedicated GPUs, created on demand to run code. | | **GPU** | A graphics processing unit assigned to one sandbox at a time. | | **GPU count** | The number of GPUs a sandbox requests when it is created. | | **Host** | The physical server with GPUs that runs sandboxes. Daytona calls these servers runners. | | **Image** | A packaged filesystem that defines what software a sandbox starts with. | | **GPU memory** | The memory on a GPU that holds the data the GPU works on, such as model weights. | | **Checkpoint** | A saved copy of a sandbox's processes, memory, and GPU memory that a new GPU sandbox resumes from. | | **Ephemeral** | A sandbox whose filesystem is discarded when it is deleted. | GPU sandboxes for Daytona v2 are coming soon. # Isolation (/docs/isolation) Daytona sandboxes are isolated by default. Each sandbox runs as a hardware-isolated virtual machine with its own kernel: code running in a sandbox cannot read another sandbox's filesystem or memory, is not on a shared network with other sandboxes, and its credentials and API access are scoped to its own project. Isolation operates at three boundaries: | **Boundary** | **What is separated** | **Mechanisms** | | ------------ | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Runtime** | Kernel, processes, filesystem, and memory of each sandbox | • [**Sandboxes**](/docs/sandboxes)
• [**Resources**](/docs/sandboxes#resources) | | **Network** | Traffic entering (ingress) and leaving (egress) each sandbox | • [**Network policy**](/docs/network-limits)
• [**Preview**](/docs/preview)
• [**Ports**](/docs/linux-sandboxes#create-a-linux-sandbox) | | **Project** | Access to sandboxes, data, and credentials | • [**Projects**](/docs/projects)
• [**API keys**](/docs/api-keys#scopes)
• [**Secrets**](/docs/secrets) | ## Runtime isolation [#runtime-isolation] Runtime isolation separates what runs inside one sandbox from the host it executes on and from every other sandbox. Each sandbox runs as a virtual machine with its own kernel, filesystem, and network stack: Linux sandboxes on Firecracker, Windows and GPU sandboxes on Cloud Hypervisor, and macOS sandboxes on Apple's Virtualization framework ([hardware virtualization](/docs/sandboxes#hardware-virtualization)). The boundary is enforced by the hypervisor, not by the guest: code inside a sandbox cannot observe or interfere with other sandboxes or the host. Resources are part of the runtime boundary. Each sandbox has its own [**vCPU**, **memory**, and **disk**](/docs/sandboxes#resources), and the guest kernel sees only the resources of its own virtual machine. The guest boots with the burst ceiling of the sandbox, so the CPU count and the total memory it reports are that ceiling, not the guarantee. Tools that size themselves from the CPU count, such as parallel test runners and build tools, start one worker per visible CPU. ```bash nproc # vCPUs of the sandbox's virtual machine grep MemTotal /proc/meminfo # memory of the sandbox's virtual machine ``` ## Network isolation [#network-isolation] Network isolation controls traffic in each direction separately. Egress is open by default and locked down per sandbox with a network policy; ingress is closed by default and opened per endpoint; sandboxes never share a network. | **Direction** | **Default** | **Controls** | | ----------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Sandbox to internet** | Open egress | [**Network policy**](/docs/network-limits): default-deny with an allow list of IPs, CIDRs, and domains | | **Internet to sandbox** | Closed; no port is reachable until exposed | [**Preview URLs**](/docs/preview) (token-authenticated unless an endpoint is made public), [**declared ports**](/docs/linux-sandboxes#create-a-linux-sandbox), and [**SSH**](/docs/ssh-access) | | **Sandbox to sandbox** | No shared network | None; sandboxes reach each other only through exposed endpoints | **Outbound** traffic is open by default. A [network policy](/docs/network-limits) turns on blocking and admits only the domains and IPv4 ranges on its allow lists. With blocking on and empty allow lists, the sandbox reaches no external address and DNS resolves no names. ```python from daytona import Daytona daytona = Daytona() # Block all outbound traffic sandbox = daytona.v2.create(network_policy={"block_all": True}) # Or allow specific domains only sandbox = daytona.v2.create( network_policy={"allow_domains": ["example.com", "*.daytona.io"]}, ) # Or allow specific IPv4 ranges only sandbox = daytona.v2.create( network_policy={"block_all": True, "allow_cidrs": ["208.80.154.232/32", "192.168.1.0/24"]}, ) ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() // Block all outbound traffic const blocked = await daytona.v2.create({ networkPolicy: { blockAll: true }, }) // Or allow specific domains only const domainRestricted = await daytona.v2.create({ networkPolicy: { allowDomains: ['example.com', '*.daytona.io'] }, }) // Or allow specific IPv4 ranges only const cidrRestricted = await daytona.v2.create({ networkPolicy: { blockAll: true, allowCidrs: ['208.80.154.232/32', '192.168.1.0/24'] }, }) ``` ```bash # Block all outbound traffic daytona sandbox create --block-all # Or allow specific domains only daytona sandbox create \ --allow-domain example.com \ --allow-domain '*.daytona.io' # Or allow specific IPv4 ranges only daytona sandbox create \ --block-all \ --allow-cidr 208.80.154.232/32 \ --allow-cidr 192.168.1.0/24 ``` ```bash # Block all outbound traffic curl 'https://api.daytona.com/sandboxes' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "network_policy": { "block_all": true } }' # Or allow specific domains only curl 'https://api.daytona.com/sandboxes' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "network_policy": { "allow_domains": ["example.com", "*.daytona.io"] } }' # Or allow specific IPv4 ranges only curl 'https://api.daytona.com/sandboxes' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "network_policy": { "block_all": true, "allow_cidrs": ["208.80.154.232/32", "192.168.1.0/24"] } }' ``` **Inbound** traffic reaches a sandbox only through a port exposed as a [preview](/docs/preview) endpoint or through [SSH access](/docs/ssh-access). A port is exposed as a private endpoint when you first request its preview URL, and a private endpoint requires a preview token or an API key. A port made public accepts requests without a credential. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() # Requesting a preview link exposes the port as a private endpoint preview = sandbox.ports.preview_link(3000) print(preview.url) # https://3000-{sandboxId}.{proxy-domain} print(preview.token) # sent in the x-daytona-preview-token header # A public endpoint accepts requests without a credential sandbox.ports.expose(8080, public=True) ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() // Requesting a preview link exposes the port as a private endpoint const preview = await sandbox.ports.previewLink(3000) console.log(preview.url) // https://3000-{sandboxId}.{proxy-domain} console.log(preview.token) // sent in the x-daytona-preview-token header // A public endpoint accepts requests without a credential await sandbox.ports.expose(8080, { public: true }) ``` ```bash # Requesting a preview URL exposes the port as a private endpoint daytona sandbox port preview-url {sandboxId} 3000 ``` ```bash # Requesting a preview URL exposes the port as a private endpoint curl 'https://api.daytona.com/sandboxes/{sandboxId}/ports/3000/preview-url' \ --request POST \ --header 'Authorization: Bearer YOUR_API_KEY' # Authenticate to the private endpoint with the returned token curl 'https://3000-{sandboxId}.{proxy-domain}' \ --header 'x-daytona-preview-token: PREVIEW_TOKEN' # A public endpoint accepts requests without a credential curl 'https://api.daytona.com/sandboxes/{sandboxId}/ports/8080' \ --request PUT \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "public": true }' ``` ## Project isolation [#project-isolation] Project isolation separates tenants. [Organizations](/docs/organizations) are the unit of membership and billing; [projects](/docs/projects) are the unit of isolation. Every sandbox, image, snapshot, volume, secret, and project API key belongs to exactly one project, and access control is enforced at that boundary: a project API key cannot see or operate on another project's resources. Organization API keys are scoped to the organization. Within a project, access narrows further to the following mechanisms: | **Mechanism** | **What it scopes** | **How it works** | | ------------------------------------------------------------ | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [**Scoped API keys**](/docs/api-keys#scopes) | What a key can do | Each key carries an explicit `verb:resource` scope list chosen at creation, and every request is confined to those scopes; `write:` and `delete:` imply `read:` on the same resource. Keys can carry an expiry. Revocation takes effect immediately on the API; toolbox and SSH access through the proxy can continue for up to 30 seconds after revocation. | | [**Secrets**](/docs/secrets) | Credentials used in a sandbox | A sandbox holds an opaque placeholder; an outbound proxy substitutes the real value only for requests to the secret's allowed domains. Responses are not rewritten, so a destination that echoes the credential back returns the real value into the sandbox. | **[API key permissions](/docs/api-keys#scopes)** scope what a key can do. A key created with only the sandbox write and delete permissions can manage sandboxes but cannot read secrets or delete images. A key can hold only permissions its creator holds. ```bash # A key limited to creating and deleting sandboxes in one project daytona key mint --project PROJECT_ID \ --name tenant-a-key \ --permission write:sandboxes,delete:sandboxes \ --expires 720h ``` ```bash # A key limited to creating and deleting sandboxes in one project curl 'https://api.daytona.com/projects/PROJECT_ID/api-keys' \ --request POST \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "name": "tenant-a-key", "project_permissions": ["write:sandboxes", "delete:sandboxes"], "expires_at": "2027-01-01T00:00:00Z" }' ``` **[Secrets](/docs/secrets)** keep credentials out of sandboxes. A sandbox holds an opaque placeholder; an outbound proxy substitutes the real value only for HTTPS requests to the secret's allowed domains. Code in the sandbox can use the credential but cannot read it directly or send it to another host. Responses are not rewritten, so an allowed destination that echoes the credential back exposes the real value to the sandbox. ```python from daytona import Daytona daytona = Daytona() daytona.v2.secrets.set( "MY_API_KEY", "secret-value", allowed_domains=["api.example.com"], ) # The sandbox receives a placeholder, never the plaintext value sandbox = daytona.v2.create(secrets=["MY_API_KEY"]) # Code uses the credential without being able to read it sandbox.process.run( 'curl -H "Authorization: Bearer $MY_API_KEY" https://api.example.com/v1/data' ) ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() await daytona.v2.secrets.set('MY_API_KEY', 'secret-value', { allowedDomains: ['api.example.com'], }) // The sandbox receives a placeholder, never the plaintext value const sandbox = await daytona.v2.create({ secrets: ['MY_API_KEY'], }) // Code uses the credential without being able to read it await sandbox.process.run( 'curl -H "Authorization: Bearer $MY_API_KEY" https://api.example.com/v1/data' ) ``` ```bash printf %s 'secret-value' | daytona secret set MY_API_KEY --stdin --allowed-domain api.example.com # The sandbox receives a placeholder, never the plaintext value daytona sandbox create --secret MY_API_KEY # Code uses the credential without being able to read it daytona sandbox exec {sandboxId} -- sh -c \ 'curl -H "Authorization: Bearer $MY_API_KEY" https://api.example.com/v1/data' ``` ```bash curl 'https://api.daytona.com/secrets/MY_API_KEY' \ --request PUT \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "value": "secret-value", "allowed_domains": ["api.example.com"] }' # The sandbox receives a placeholder, never the plaintext value curl 'https://api.daytona.com/sandboxes' \ --request POST \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "secrets": ["MY_API_KEY"] }' ``` # Persistence (/docs/persistence) The writable filesystem of a Daytona sandbox exists only while the sandbox does. Deleting a sandbox discards its filesystem, memory, and processes. To keep state beyond the sandbox, capture it as an image or a snapshot, or write it to storage outside the sandbox. Snapshots on this page are Linux snapshots: they save memory and disk and restore on the runner that captured them, or on another runner of the region with the same CPU model and hypervisor version. A persistent macOS sandbox keeps its disk across stop and start, and a macOS snapshot saves only the disk of a stopped persistent sandbox, as an image that restores on any Mac of the region. See [macOS filesystem persistence](/docs/macos-sandboxes#filesystem-persistence). | **Layer** | **What is preserved** | **Mechanisms** | | -------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------- | | **Filesystem** | Files, packages, repositories, build artifacts | • [**Image capture**](/docs/images#capture-images) | | **Memory** | Processes, connections, states | • [**Snapshots**](/docs/snapshots#create-snapshots) | | **External storage** | Data that outlives any single sandbox | • [**Volumes**](/docs/volumes) | ## Use cases [#use-cases] Persistence is used when the state of a sandbox must survive past the sandbox itself. - **Prepared environments.** An image capture keeps installed packages, repositories, and configuration. New sandboxes start from the image with nothing to reinstall or rebuild. Capture works on a running Linux or Windows sandbox, which keeps running during the capture. - **Runs from a known state.** A snapshot copies a configured sandbox, so several runs or every agent in a fleet start from the same state. A restored sandbox continues with its processes still running. A snapshot restores in its home region, or, where Daytona has enabled cross-region restore, in another region if the source sandbox was not persistent. - **Servers that resume without a restart.** A snapshot taken after a server starts keeps the server in memory. A restored sandbox continues with the server already running, instead of starting it again after a clean boot. The restored sandbox gets a fresh IP and port mappings. - **Results that outlive the sandbox.** A sandbox writes its output to storage outside the sandbox, such as your own object storage, and the data stays after the sandbox is deleted. Data on a [volume](/docs/volumes) also stays, and a later sandbox can attach the same volume and read it. A disk volume mounts as a local filesystem, while a bucket volume writes straight to an S3 bucket. - **Work that survives timeouts and reclaims.** A [timeout](#retention-and-lifecycle) or a spot reclaim can delete a sandbox without a request from you, and a host failure loses an ephemeral sandbox, along with its state. Results on a volume or in a captured image stay when that happens. A persistent macOS sandbox stops on a timeout instead of being deleted, and keeps its disk. ## Filesystem persistence [#filesystem-persistence] Filesystem persistence keeps the contents of a sandbox's disk: files, installed packages, cloned repositories, and build artifacts. Delete discards a sandbox's filesystem, and a host failure loses an ephemeral sandbox. Capture an [**image**](/docs/images#capture-images) or write results to storage outside the sandbox to keep them. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() # Prepare the environment to capture sandbox.process.run("pip install requests") # An image capture keeps the filesystem beyond the sandbox image = sandbox.capture_image(name="my-env") # Capture runs asynchronously; wait until the image is ready while image.status not in ("ready", "failed"): image = daytona.v2.images.get(image.id, wait="ready") if image.status == "failed": raise RuntimeError(image.error) # Delete discards the sandbox; the image remains sandbox.delete() # Any number of new sandboxes can start from the same image clone = daytona.v2.create("my-env") response = clone.process.run("pip show requests") print(response.stdout) # requests is already installed ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() // Prepare the environment to capture await sandbox.process.run('pip install requests') // An image capture keeps the filesystem beyond the sandbox let image = await sandbox.captureImage({ name: 'my-env' }) // Capture runs asynchronously; wait until the image is ready while (image.status !== 'ready' && image.status !== 'failed') { image = await daytona.v2.images.get(image.id, { wait: 'ready' }) } if (image.status === 'failed') throw new Error(image.error ?? 'image capture failed') // Delete discards the sandbox; the image remains await sandbox.delete() // Any number of new sandboxes can start from the same image const clone = await daytona.v2.create('my-env') const response = await clone.process.run('pip show requests') console.log(response.stdout) // requests is already installed ``` ```bash daytona sandbox create # Prepare the environment to capture daytona sandbox exec {sandboxId} -- pip install requests # An image capture keeps the filesystem beyond the sandbox; the command waits until the image is ready daytona image capture {sandboxId} --name my-env # Delete discards the sandbox; the image remains daytona sandbox delete {sandboxId} --yes # Any number of new sandboxes can start from the same image daytona sandbox create --image my-env daytona sandbox exec {cloneId} -- pip show requests ``` ```bash curl 'https://api.daytona.com/sandboxes' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{}' # Prepare the environment to capture curl '{toolboxProxyUrl}/{sandboxId}/processes?waitMs=60000&logs=text' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{"kind": "exec", "shellCommand": "pip install requests"}' # An image capture keeps the filesystem beyond the sandbox curl 'https://api.daytona.com/sandboxes/{sandboxId}/images' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{"name": "my-env"}' # Capture runs asynchronously; block until the image is ready curl 'https://api.daytona.com/images/{imageId}?wait=ready' \ --header 'Authorization: Bearer YOUR_API_KEY' # Delete discards the sandbox; the image remains curl 'https://api.daytona.com/sandboxes/{sandboxId}' \ --request DELETE \ --header 'Authorization: Bearer YOUR_API_KEY' # Any number of new sandboxes can start from the same image curl 'https://api.daytona.com/sandboxes' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{"image": "my-env"}' ``` - The requests require the `write:sandboxes`, `write:images`, and `delete:sandboxes` permissions. - `{toolboxProxyUrl}` is the `toolbox_proxy_url` field of the [sandbox](/docs/sandboxes#get-a-sandbox). - The wait request returns at `ready` or `failed`, or after 30 seconds. - Repeat the wait request while the image status is `pending` or `building`. A `failed` image does not become `ready`. ## Memory persistence [#memory-persistence] Memory persistence keeps the runtime state of a sandbox: running processes, open connections, and everything loaded in RAM. A [**snapshot**](/docs/snapshots#create-snapshots) captures the memory and disk of a running persistent Linux sandbox or one served from a warm template, and a sandbox restored from it continues from the point it was captured, with processes still running, instead of starting from a clean boot. macOS snapshots do not save memory. ```python from daytona import Daytona daytona = Daytona() # Snapshot capture needs a persistent sandbox or one served from a warm template sandbox = daytona.v2.create() # Start a server that runs in the background sandbox.process.start("python3 -m http.server 8000") # A snapshot keeps memory and running processes beyond the sandbox snapshot = sandbox.create_snapshot("my-snapshot") # Capture runs asynchronously; wait until the snapshot is ready while snapshot.status not in ("ready", "failed"): snapshot = daytona.v2.snapshots.get(snapshot.id, wait="ready") if snapshot.status == "failed": raise RuntimeError(snapshot.error) # Delete discards the sandbox; the snapshot remains sandbox.delete() # The restored sandbox resumes the server without starting it again restored = daytona.v2.create_from_snapshot("my-snapshot") response = restored.process.run(argv=[ "python3", "-c", "import urllib.request; print(urllib.request.urlopen('http://localhost:8000').status)", ]) print(response.stdout) # 200 ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() // Snapshot capture needs a persistent sandbox or one served from a warm template const sandbox = await daytona.v2.create() // Start a server that runs in the background await sandbox.process.start('python3 -m http.server 8000') // A snapshot keeps memory and running processes beyond the sandbox let snapshot = await sandbox.createSnapshot('my-snapshot') // Capture runs asynchronously; wait until the snapshot is ready while (snapshot.status !== 'ready' && snapshot.status !== 'failed') { snapshot = await daytona.v2.snapshots.get(snapshot.id, { wait: 'ready' }) } if (snapshot.status === 'failed') throw new Error(snapshot.error ?? 'snapshot capture failed') // Delete discards the sandbox; the snapshot remains await sandbox.delete() // The restored sandbox resumes the server without starting it again const restored = await daytona.v2.createFromSnapshot('my-snapshot') const response = await restored.process.run({ argv: [ 'python3', '-c', "import urllib.request; print(urllib.request.urlopen('http://localhost:8000').status)", ], }) console.log(response.stdout) // 200 ``` ```bash # Snapshot capture needs a persistent sandbox or one served from a warm template daytona sandbox create # Start a server that runs in the background daytona sandbox exec {sandboxId} -- bash -c 'nohup python3 -m http.server 8000 > /tmp/server.log 2>&1 &' # A snapshot keeps memory and running processes beyond the sandbox; the command waits until the snapshot is ready daytona snapshot create {sandboxId} --name my-snapshot # Delete discards the sandbox; the snapshot remains daytona sandbox delete {sandboxId} --yes # The restored sandbox resumes the server without starting it again daytona sandbox create-from-snapshot my-snapshot daytona sandbox exec {restoredId} -- python3 -c "import urllib.request; print(urllib.request.urlopen('http://localhost:8000').status)" ``` ```bash # Snapshot capture needs a persistent sandbox or one served from a warm template curl 'https://api.daytona.com/sandboxes' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{}' # Start a server that runs in the background curl '{toolboxProxyUrl}/{sandboxId}/processes' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{"kind": "exec", "shellCommand": "python3 -m http.server 8000"}' # A snapshot keeps memory and running processes beyond the sandbox curl 'https://api.daytona.com/sandboxes/{sandboxId}/snapshots' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{"name": "my-snapshot"}' # Capture runs asynchronously; block until the snapshot is ready curl 'https://api.daytona.com/snapshots/{snapshotId}?wait=ready&timeout_ms=60000' \ --header 'Authorization: Bearer YOUR_API_KEY' # Delete discards the sandbox; the snapshot remains curl 'https://api.daytona.com/sandboxes/{sandboxId}' \ --request DELETE \ --header 'Authorization: Bearer YOUR_API_KEY' # The restored sandbox resumes the server without starting it again curl 'https://api.daytona.com/sandboxes/from-snapshot' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{"snapshot": "my-snapshot"}' curl '{toolboxProxyUrl}/{restoredId}/processes?waitMs=5000&logs=text' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{"kind": "exec", "argv": ["python3", "-c", "import urllib.request; print(urllib.request.urlopen(\"http://localhost:8000\").status)"]}' ``` - The requests require the `write:sandboxes`, `write:snapshots`, and `delete:sandboxes` permissions. - The wait request returns at `ready` or `failed`, or after `timeout_ms`. - Repeat the wait request while the snapshot status is `pending` or `building`. A `failed` snapshot does not become `ready`. ## Persistence beyond a sandbox [#persistence-beyond-a-sandbox] Deleting a sandbox deletes its state. To persist state beyond the sandbox itself, capture it as an **image** or a **snapshot**, or write it to storage outside the sandbox. ### Images and snapshots [#images-and-snapshots] An [image capture](/docs/images#capture-images) saves the filesystem of a running Linux or Windows sandbox under a name, and new sandboxes boot from it. A [snapshot](/docs/snapshots) saves the memory and disk of a running persistent Linux sandbox or one served from a warm template, and a restored sandbox resumes the captured processes. A snapshot restores on the runner that captured it, or on another runner of the region with the same CPU model and hypervisor version. A macOS snapshot is an image of the disk of a stopped persistent sandbox and restores on any Mac of the region ([macOS snapshots](/docs/macos-sandboxes#filesystem-snapshot)). A snapshot covers the sandbox's own state. A restored sandbox gets a fresh IP and port mappings. Deleting the source sandbox does not delete its snapshots. ### Volumes [#volumes] A [volume](/docs/volumes) is project-scoped storage that a sandbox attaches when it is created. Data on a volume stays when the sandbox is deleted, and a later sandbox can attach the same volume and read it. A disk volume is mounted as a local filesystem and commits each sandbox's changes in the background; a bucket volume mounts an S3 bucket, managed by Daytona or your own, and writes go straight to the bucket. ## Retention and lifecycle [#retention-and-lifecycle] When one of a sandbox's [timeouts](/docs/linux-sandboxes#timeouts) elapses, Daytona runs the action set for that timeout: delete, or stop for a [persistent](/docs/macos-sandboxes#lifecycle) macOS sandbox. The timeouts and actions come from the sandbox's lifecycle policy, the project's lifecycle defaults, or the platform default timeout. Two platform events also act on sandboxes without a request from you: - **Spot reclaim**: when the platform reclaims a [spot](/docs/preemption#spot-sandboxes) sandbox, an ephemeral sandbox is deleted, and a Windows sandbox is stopped with its disk kept. Reclaimed sandboxes record the time of the reclaim. See [preemption](/docs/preemption). - **Host failure**: an ephemeral sandbox on a failed host is lost. ```python from daytona import Daytona daytona = Daytona() # Create, use, delete sandbox = daytona.v2.create() # Run the workload and read the results before deleting response = sandbox.process.run("python3 -c 'print(1 + 1)'") print(response.stdout) # Delete discards the sandbox and all of its state sandbox.delete() ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() // Create, use, delete const sandbox = await daytona.v2.create() // Run the workload and read the results before deleting const response = await sandbox.process.run("python3 -c 'print(1 + 1)'") console.log(response.stdout) // Delete discards the sandbox and all of its state await sandbox.delete() ``` ```bash # Create, use, delete daytona sandbox create # Run the workload and read the results before deleting daytona sandbox exec {sandboxId} -- python3 -c 'print(1 + 1)' # Delete discards the sandbox and all of its state daytona sandbox delete {sandboxId} --yes ``` ```bash # Create, use, delete curl 'https://api.daytona.com/sandboxes' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{}' # Run the workload and read the results before deleting curl '{toolboxProxyUrl}/{sandboxId}/processes?waitMs=5000&logs=text' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{"kind": "exec", "shellCommand": "python3 -c '\''print(1 + 1)'\''"}' # Delete discards the sandbox and all of its state curl 'https://api.daytona.com/sandboxes/{sandboxId}' \ --request DELETE \ --header 'Authorization: Bearer YOUR_API_KEY' ``` # Scale (/docs/scale) Daytona sandboxes are designed to be created and operated at high volume. A single sandbox scales up by bursting beyond its guaranteed resources, a fleet scales out by running many sandboxes at once, and each sandbox runs multiple processes concurrently. Scale operates along three dimensions: | **Dimension** | **What scales** | **Mechanisms** | | ---------------------- | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Sandbox**
(vertical) | vCPU, RAM, and disk of a single sandbox | • [**Custom resources**](/docs/sandboxes#resources)
• [**Resource limits**](/docs/limits#sandbox-limits) | | **Fleet**
(horizontal) | Number of sandboxes running simultaneously | • [**Snapshot fan-out**](/docs/snapshots) | | **Workload**
(concurrency) | Concurrent processes in a sandbox | • [**Sessions**](/docs/process-execution#session-operations)
• [**Background commands**](/docs/process-execution#start-a-background-process)
• [**PTY sessions**](/docs/pty) | ## Sandbox scaling [#sandbox-scaling] Sandbox scaling sets the resources of a single sandbox: **vCPU**, **memory**, and **disk**. The resource envelope is fixed when the sandbox is created; there is no resize operation. The requested resources are a guaranteed floor, reserved at placement; beyond it the sandbox uses idle host capacity up to its [resource limits](/docs/limits#sandbox-limits), which default to the [plan caps](/docs/limits#sandbox-limits) of your organization. Size the guarantee for the workload's average, and let bursting absorb the peaks. For a fixed shape with no bursting, set every limit equal to its request. Guarantee CPU, memory, and disk when creating a sandbox. ```python from daytona import Daytona from daytona.v2 import Resources daytona = Daytona() # Guarantee 2 cores, 4 GiB of RAM, and 16 GiB of disk for the sandbox sandbox = daytona.v2.create( resources=Resources(cpu=2, memory=4, disk=16), ) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | ---------------------------------------- | | `cpu` | float | Sets the CPU guarantee in cores. The API raises the CPU guarantee to at least 1 core per 8 GiB of memory. The value can be fractional. | | `memory` | int | Sets the memory guarantee in GiB. | | `disk` | int | Sets the disk guarantee in GiB. | ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() // Guarantee 2 cores, 4 GiB of RAM, and 16 GiB of disk for the sandbox const sandbox = await daytona.v2.create({ resources: { cpu: 2, memory: 4, disk: 16 }, }) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | ---------------------------------------- | | `cpu` | number | Sets the CPU guarantee in cores. The API raises the CPU guarantee to at least 1 core per 8 GiB of memory. The value can be fractional. | | `memory` | number | Sets the memory guarantee in GiB. | | `disk` | number | Sets the disk guarantee in GiB. | ```bash # Guarantee 2 cores, 4 GiB of RAM, and 16 GiB of disk; --memory and --disk are MiB daytona sandbox create --cpu 2 --memory 4096 --disk 16384 ``` | **Flag** | **Type** | **Description** | | -------- | -------- | ---------------------------- | | `--cpu` | float | Sets the CPU guarantee in cores. The API raises the CPU guarantee to at least 1 core per 8192 MiB of memory. The value can be fractional. | ```bash curl 'https://api.daytona.com/sandboxes' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "cpu": 2, "memory_mib": 4096, "disk_mib": 16384 }' ``` | **Field** | **Type** | **Description** | | ------------- | --------- | ---------------------------- | | `cpu` | number | Sets the CPU guarantee in cores. The value can be fractional. The API raises `cpu` to at least 1 core per 8192 MiB of `memory_mib`. | | `memory_mib` | integer | In MiB. | | `disk_mib` | integer | In MiB. | A sandbox bursts beyond its guarantee up to the [plan caps](/docs/limits#sandbox-limits) of your organization: **4** cores (8 vCPUs) and **16** GiB of memory on Starter, **8** cores (16 vCPUs) and **32** GiB on Team, and the platform caps of **16** cores (32 vCPUs) and **32** GiB on Enterprise. The ranges below are the platform caps; a value above the plan cap is rejected. The per-sandbox core and memory limits lower those ceilings and cannot raise them. CPU guarantees can be fractional, as small as 0.125 cores. Usage above the guarantee is billed as measured; see [billing](/docs/billing). ```python from daytona import Daytona from daytona.v2 import Resources daytona = Daytona() # Guarantee half a core and 2 GiB, and burst up to 2 cores (4 vCPUs) and 8 GiB sandbox = daytona.v2.create( resources=Resources(cpu=0.5, cpu_max=2, memory=2, memory_max=8), ) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------------------------------- | | `cpu_max` | float | Sets the CPU limit in cores, a multiple of `0.5`, up to the plan cap. One core is 2 vCPUs. | | `memory_max` | float | Sets the memory limit in GiB, from 256 MiB to 32 GiB. | ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() // Guarantee half a core and 2 GiB, and burst up to 2 cores (4 vCPUs) and 8 GiB const sandbox = await daytona.v2.create({ resources: { cpu: 0.5, cpuMax: 2, memory: 2, memoryMax: 8 }, }) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | ------------------------------- | | `cpuMax` | number | Sets the CPU limit in cores, a multiple of `0.5`, up to the plan cap. One core is 2 vCPUs. | | `memoryMax` | number | Sets the memory limit in GiB, from 256 MiB to 32 GiB. | ```bash # Guarantee half a core and 2 GiB, and burst up to 2 cores (4 vCPUs) and 8 GiB daytona sandbox create --cpu 0.5 --cpu-max 2 --memory 2048 --memory-max 8192 ``` | **Flag** | **Type** | **Description** | | -------------- | -------- | ----------------------------------- | | `--cpu-max` | float | Cores, a multiple of 0.5, up to the plan cap. One core is 2 vCPUs. | | `--memory-max` | int32 | In MiB, from `256` to `32768`. | ```bash curl 'https://api.daytona.com/sandboxes' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "cpu": 0.5, "cores_max": 2, "memory_mib": 2048, "memory_max_mib": 8192 }' ``` | **Field** | **Type** | **Description** | | ------------- | --------- | ------------------------------ | | `cores_max` | number | Cores, a multiple of 0.5, up to the plan cap. One core is 2 vCPUs. | | `memory_max_mib` | integer | In MiB, from `256` to `32768`. | ## Fleet scaling [#fleet-scaling] Fleet scaling raises how many sandboxes run at once. The unit of scale is the sandbox: instead of packing unrelated workloads into one environment, create one per user, task, or agent. Each sandbox is a hardware-isolated microVM, so a fleet scales linearly: each sandbox adds capacity without contention, and a failure in one does not affect others. Creation is fast and asynchronous, so scale on demand: create when work arrives, delete when done. [Snapshot fan-out](/docs/snapshots) starts each unit of work from the memory and disk of one prepared snapshot, so any number of identical environments run from the same state. Snapshot fan-out works with Linux sandboxes. macOS sandboxes start from a disk image instead: see [macOS snapshots](/docs/macos-sandboxes#filesystem-snapshot). ```python from concurrent.futures import ThreadPoolExecutor from daytona import Daytona daytona = Daytona() def run_task(shard: int) -> str: # Each task gets its own isolated sandbox from the same snapshot sandbox = daytona.v2.create_from_snapshot("my-snapshot") response = sandbox.process.run(f"python3 run.py --shard {shard}") # Delete the sandbox when the task is done sandbox.delete() return response.stdout # Create and run 20 sandboxes concurrently from the same snapshot with ThreadPoolExecutor(max_workers=20) as pool: results = list(pool.map(run_task, range(20))) print(results) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | ----------------------------------------------------------------------------------- | | `wait` | int | Sets how many seconds `create_from_snapshot` waits for the sandbox to start. When `wait` runs out, `create_from_snapshot` returns the sandbox without raising. The returned sandbox may not have started. The default is `60`. | ```python import asyncio from daytona import AsyncDaytona async def run_task(daytona: AsyncDaytona, shard: int) -> str: # Each task gets its own isolated sandbox from the same snapshot sandbox = await daytona.v2.create_from_snapshot("my-snapshot") response = await sandbox.process.run(f"python3 run.py --shard {shard}") # Delete the sandbox when the task is done await sandbox.delete() return response.stdout async def main() -> None: async with AsyncDaytona() as daytona: # Create and run 20 sandboxes concurrently from the same snapshot results = await asyncio.gather(*(run_task(daytona, i) for i in range(20))) print(results) asyncio.run(main()) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | ----------------------------------------------------------------------------------- | | `wait` | int | Sets how many seconds `create_from_snapshot` waits for the sandbox to start. When `wait` runs out, `create_from_snapshot` returns the sandbox without raising. The returned sandbox may not have started. The default is `60`. | ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() async function runTask(shard: number): Promise { // Each task gets its own isolated sandbox from the same snapshot const sandbox = await daytona.v2.createFromSnapshot('my-snapshot') const response = await sandbox.process.run(`python3 run.py --shard ${shard}`) // Delete the sandbox when the task is done await sandbox.delete() return response.stdout } // Create and run 20 sandboxes concurrently from the same snapshot const results = await Promise.all( Array.from({ length: 20 }, (_, i) => runTask(i)) ) console.log(results) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------------------------------------------------------------------------- | | `wait` | number | Sets how many seconds `createFromSnapshot` waits for the sandbox to start. When `wait` runs out, `createFromSnapshot` returns the sandbox without throwing. The returned sandbox may not have started. The default is `60`. | ```bash # Create each sandbox from the same snapshot (run commands concurrently as needed) daytona sandbox create-from-snapshot my-snapshot ``` ```bash # Create each sandbox from the same snapshot (issue requests concurrently as needed) curl 'https://api.daytona.com/sandboxes/from-snapshot' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "snapshot": "my-snapshot" }' ``` ## Workload concurrency [#workload-concurrency] Workload concurrency runs multiple processes inside a single sandbox. A single sandbox can run an API server, a database, and background workers side by side: all processes share the sandbox's filesystem and network, and exposed ports are reachable through [previews](/docs/preview). Every command runs as a process: run starts a process and waits for it, while start returns a handle immediately and the process continues in the background. [Sessions](/docs/process-execution#session-operations) are shared shells: commands in a session run sequentially and share state, so parallelism comes from separate sessions or background processes. [Pseudo terminal (PTY) sessions](/docs/pty) add interactive terminals. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() # Start the server as a background process; the handle returns immediately sandbox.process.start("python3 -m http.server 8000") # Other commands run concurrently in the same sandbox response = sandbox.process.run(argv=[ "python3", "-c", "import time, urllib.request as u; time.sleep(1); print(u.urlopen('http://localhost:8000').status)", ]) print(response.stdout) ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() // Start the server as a background process; the handle returns immediately await sandbox.process.start('python3 -m http.server 8000') // Other commands run concurrently in the same sandbox const response = await sandbox.process.run({ argv: ['python3', '-c', "import time, urllib.request as u; time.sleep(1); print(u.urlopen('http://localhost:8000').status)"], }) console.log(response.stdout) ``` ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() # start returns a handle immediately while the command runs in the background handle = sandbox.process.start("pip install numpy") # Wait for completion and read the exit code later result = handle.wait() print(result.exit_code) ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() // start returns a handle immediately while the command runs in the background const handle = await sandbox.process.start('pip install numpy') // Wait for completion and read the exit code later const result = await handle.wait() console.log(result.exitCode) ``` ## Capacity and throughput [#capacity-and-throughput] Fleet size operates within per-sandbox platform and plan caps and your organization's credit balance. | **Control** | **What it limits** | **Scope** | | --------------------------------------------- | ----------------------------------------------------------------------------- | ------------ | | [**Resources**](/docs/sandboxes#resources) | Maximum vCPU, memory, and disk of a single sandbox | Sandbox | | [**Credits**](/docs/billing) | Spending across sandboxes; creates are rejected when the balance is exhausted | Organization | ### Reclaiming capacity [#reclaiming-capacity] Delete sandboxes when their work is done to release compute and storage: - **Sandboxes** release compute and storage immediately on delete. - **[Spot sandboxes](/docs/preemption#spot-sandboxes)** are reclaimed automatically when the platform needs capacity. See [preemption](/docs/preemption). ### Operating at scale [#operating-at-scale] At high creation rates, two practices keep an application efficient: - Make creates safe to retry with an [idempotency key](/docs/linux-sandboxes#create-a-linux-sandbox): a retried create with the same key returns the same sandbox instead of minting a new one. - Wait with long-polls, not tight polling. The SDKs block on create until the sandbox runs. On the API, `wait` long-polls one sandbox, and the batch wait endpoint waits on up to `200` sandboxes over one connection, returning once one reaches the target state or `timeout_ms` elapses. ```bash # Wait for one sandbox to reach running without tight polling curl 'https://api.daytona.com/sandboxes/{sandboxId}?wait=running' \ --header 'Authorization: Bearer YOUR_API_KEY' # Wait on a whole batch over one connection (up to 200 IDs) curl 'https://api.daytona.com/sandboxes/batch-wait?ids={sandboxId1},{sandboxId2},{sandboxId3}&wait=running&timeout_ms=60000' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` # Preemption (/docs/preemption) Daytona sandboxes run on reserved capacity by default: once placed, a sandbox keeps its resources until you delete it. A [spot](#spot-sandboxes) sandbox is preemptible: it is billed at a discount, and Daytona can reclaim it at any time to free capacity for full-price sandboxes. The tier is set when the sandbox is created and cannot be changed afterwards. A reclaimed ephemeral Linux spot sandbox is deleted, with its filesystem. To continue the work of an ephemeral sandbox, create a new sandbox and keep results in storage outside the sandbox, such as your own object storage. A reclaimed [Windows](/docs/windows-sandboxes) spot sandbox is stopped, with the disk kept, and a start boots Windows from the preserved disk. ## Use cases [#use-cases] Spot sandboxes are used for work that tolerates an interruption in exchange for a lower price. - **Batch jobs.** Data processing, builds, and test runs start again from the beginning when a sandbox is reclaimed. Spot multiplies the CPU, memory, and disk price by 0.7. Each job opts in to spot when its sandbox is created, and the tier cannot change afterwards. - **Evaluation and reinforcement learning (RL).** Many short test cases or episodes run on spot sandboxes. A reclaimed test case or episode runs again in a new sandbox. Newer spot sandboxes are reclaimed before older ones, so a reclaim interrupts the least accumulated work first. - **Stateless workers.** Workers that keep no state in the sandbox lose nothing on a reclaim. A new spot sandbox replaces the reclaimed one. Daytona does not create the replacement on its own, so the application creates it. - **Results outside the sandbox.** A spot sandbox writes its output to storage outside the sandbox, such as your own object storage, so a reclaim loses only the work in progress. A replacement sandbox continues from the last checkpoint in that storage. The [reclaim time](#reclaim-detection) on the old sandbox tells a reclaim apart from a delete you requested. - **Development and experiments.** Sandboxes whose loss costs only a restart run at the spot price. A reclaim comes with no warning, and an ephemeral sandbox loses its filesystem. GPU sandboxes cannot be spot, so GPU experiments run at full price. ## Spot sandboxes [#spot-sandboxes] A spot sandbox differs from an on-demand sandbox only in price and reclaim. In every other respect it is an ordinary sandbox: it supports the same images, resources, and lifecycle operations as an on-demand sandbox of its type. Spot multiplies the CPU, memory, and disk price by 0.7; see [pricing dimensions](/docs/billing#pricing-dimensions). Linux and Windows sandboxes can be spot. GPU sandboxes cannot. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create(spot=True) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------------------------------------------------------------- | | `spot` | bool | Places the sandbox on discounted, reclaimable capacity. The default is `False`. The value is fixed at create. `create_from_snapshot()` has no `spot` parameter. | ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create({ spot: true }) ``` | **Parameter** | **Type** | **Description** | | ------------- | --------- | --------------------------------------------------------------------- | | `spot` | boolean | Places the sandbox on discounted, reclaimable capacity. The default is `false`. The value is fixed at create. `createFromSnapshot()` has no `spot` option. | ```bash daytona sandbox create --spot ``` | **Flag** | **Type** | **Description** | | -------- | -------- | --------------- | | `--spot` | bool | Places the sandbox on discounted, reclaimable capacity. The default is `false`. The value is fixed at create. `sandbox create-from-snapshot` has no `--spot` flag. | ```bash curl 'https://api.daytona.com/sandboxes' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{"spot": true}' ``` | **Field** | **Type** | **Description** | | --------- | --------- | --------------------------------------------------------------------- | | `spot` | boolean | Places the sandbox on discounted, reclaimable capacity. The default is `false`. The value is fixed at create. `POST /sandboxes/windows` also accepts `spot`. `POST /sandboxes/gpu` and `POST /sandboxes/from-snapshot` do not accept `spot`. | ## Reclaim policy [#reclaim-policy] Daytona tracks the CPU, memory, and disk reserved on each host. When the reservation on a host crosses a threshold on any of the three, Daytona reclaims running spot sandboxes on that host until the projected reservation drops below it. Newer spot sandboxes are reclaimed before older ones, interrupting the least accumulated work first. On-demand sandboxes are never reclaimed. A reclaim is immediate. Daytona does not notify the sandbox or your application in advance, and there is no grace period. Daytona does not replace a reclaimed sandbox on its own when capacity frees up: creating a new one is up to you. A reclaimed sandbox is [billed](/docs/billing) like a sandbox you delete, pause, or stop. ## Reclaim outcomes [#reclaim-outcomes] Daytona records the reclaim time, then tears an ephemeral sandbox down like a user request: the sandbox is deleted, and only data in storage outside the sandbox remains. A Windows sandbox is stopped, since Windows cannot pause, and keeps its disk. For the full state model, see [lifecycle](/docs/sandboxes#sandbox-lifecycle). ## Reclaim detection [#reclaim-detection] Reclaim detection tells a reclaim apart from a delete you requested. Every reclaimed sandbox carries the time of the reclaim until it is started or resumed. A sandbox that was never reclaimed carries no reclaim time. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.get("{sandboxId}") # None unless the platform reclaimed this spot sandbox if sandbox.spot_evicted_at: print(f"reclaimed at {sandbox.spot_evicted_at}, state: {sandbox.state}") # Find spot sandboxes page = daytona.v2.search(spot=True) for sandbox in page.items: print(sandbox.id, sandbox.state, sandbox.spot_evicted_at) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | ------------------------------------------------------------------------------------- | | `spot` | bool | Filters by capacity type. `True` returns only spot sandboxes, and `False` returns only on-demand sandboxes. The default is `None`, which returns both. | ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.get('{sandboxId}') // undefined unless the platform reclaimed this spot sandbox if (sandbox.spotEvictedAt) { console.log(`reclaimed at ${sandbox.spotEvictedAt}, state: ${sandbox.state}`) } // Find spot sandboxes const page = await daytona.v2.search({ spot: true }) for (const item of page.items) { console.log(item.id, item.state, item.spotEvictedAt) } ``` | **Parameter** | **Type** | **Description** | | ------------- | --------- | ------------------------------------------------------------------------------------------ | | `spot` | boolean | Filters by capacity type. `true` returns only spot sandboxes, and `false` returns only on-demand sandboxes. By default, the search returns both. | ```bash # spot_evicted_at is present only if the platform reclaimed the sandbox daytona sandbox get {sandboxId} --output json # Find spot sandboxes daytona sandbox search --spot ``` | **Flag** | **Type** | **Description** | | -------- | -------- | --------------- | | `--spot` | bool | Filters by capacity type. `--spot` returns only spot sandboxes, and `--spot=false` returns only on-demand sandboxes. By default, the search returns both. | ```bash # spot_evicted_at is an RFC 3339 timestamp, or null if the sandbox was never reclaimed curl 'https://api.daytona.com/sandboxes/{sandboxId}' \ --header 'Authorization: Bearer YOUR_API_KEY' # Find spot sandboxes curl 'https://api.daytona.com/sandboxes/search?spot=true' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` | **Field** | **Type** | **Description** | | --------- | --------- | ------------------------------------------------------------------------------------------ | | `spot` | boolean | Filters by capacity type. `true` returns only spot sandboxes, and `false` returns only on-demand sandboxes. By default, the search returns both. | ## Reclaim recovery [#reclaim-recovery] A reclaimed ephemeral sandbox is gone; continue in a new sandbox from data stored outside the sandbox. ```python from daytona import Daytona daytona = Daytona() previous = daytona.v2.get("{sandboxId}") # A reclaimed sandbox is deleted; only data outside it remains if previous.spot_evicted_at: sandbox = daytona.v2.create(spot=True) # Continue from the last checkpoint the previous sandbox wrote to your own storage sandbox.process.run("python3 train.py --resume-from s3://my-bucket/checkpoint") ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const previous = await daytona.v2.get('{sandboxId}') // A reclaimed sandbox is deleted; only data outside it remains if (previous.spotEvictedAt) { const sandbox = await daytona.v2.create({ spot: true }) // Continue from the last checkpoint the previous sandbox wrote to your own storage await sandbox.process.run('python3 train.py --resume-from s3://my-bucket/checkpoint') } ``` ## Opting in to preemption [#opting-in-to-preemption] Spot suits work that tolerates interruption and can be restarted or continued: batch jobs, evaluation and reinforcement learning rollouts, CI runs, and stateless workers. Keep spot off sandboxes that serve live traffic or hold state that exists nowhere else. - **Checkpoint to storage outside the sandbox** from spot sandboxes, so a replacement sandbox can continue where the reclaimed one stopped. - **Check after interruptions**: when a sandbox stops responding or changes state unexpectedly, read its [reclaim time](#reclaim-detection) to tell a reclaim apart from a failure. # Snapshots (/docs/snapshots) A snapshot is a capture of the memory and disk of a running sandbox, saved under a name. A sandbox restored from a snapshot resumes the captured processes and memory instead of booting. Deleting the source sandbox does not affect its snapshots. A Linux sandbox produces a full snapshot, and only a persistent sandbox or one served from a warm template can be captured. A GPU sandbox produces a [checkpoint](/docs/gpu-sandboxes) that also holds GPU memory. A full snapshot restores in its home region, on the runner that captured it or on another runner of the region with the same CPU model and hypervisor version. Where Daytona has enabled cross-region restore, a full snapshot of a sandbox that is not persistent can also restore in another region, which receives a copy of it first. Without it, a restore that names another region returns `400`. A checkpoint restores on any GPU runner in the region that meets the [restore requirements](/docs/gpu-sandboxes). Windows sandboxes do not support snapshots. macOS sandboxes do not produce these snapshots: a macOS filesystem snapshot saves the disk of a stopped persistent sandbox as an image, and it restores on any Mac of the region. A snapshot holds a running state. To save only the filesystem of a sandbox, [capture an image](/docs/images#capture-images) instead. To register a registry image or a Dockerfile build under a name, [pull](/docs/images#pull-images) or [build](/docs/images#build-images) an image. | **Concept** | **Description** | | ----------------- | ---------------------------------------------------------------------------------------------------------------- | | **Full snapshot** | The memory and disk of a running persistent Linux sandbox or one served from a warm template. | | **Checkpoint** | The processes, memory, and GPU memory of a running GPU sandbox. | | **Restore** | A new sandbox that resumes the captured processes and memory, with the CPU, memory, and disk of the source. | | **Home region** | The region of the source sandbox. A snapshot restores there unless the restore names another region. | | **Name** | Unique in the project. Snapshots and images share one name space. | ## Use cases [#use-cases] Snapshots are used when a new sandbox must continue from a running state instead of booting and repeating its setup. - **Checkpoints of running work.** A full snapshot saves the memory and disk of a running sandbox. A restore resumes the captured processes instead of starting them again. The capture runs in the background, and the source sandbox keeps running if the capture fails. - **Fast starts for slow-booting programs.** A full snapshot taken after a server, a kernel, or a model has loaded restores with that program already running. New sandboxes skip the load time. The program must run in a persistent Linux sandbox or one served from a warm template, because only those sandboxes can be captured. - **Evaluation and reinforcement learning (RL).** Each test case or episode resumes from the same snapshot. Results do not depend on another run. Every restored sandbox keeps the CPU, memory, and disk of the source, so each run gets the same resources. - **Long GPU jobs.** A checkpoint saves a GPU job together with its GPU memory. A new GPU sandbox resumes the job from the point it was saved. The checkpoint restores on any GPU runner in the region that meets the [restore requirements](/docs/gpu-sandboxes). - **Parallel attempts from one state.** Several sandboxes restore from the same snapshot, and each continues on its own. An agent tries several approaches from one point without repeating the setup. The snapshot cannot be deleted while a sandbox restored from it exists. ## Create snapshots [#create-snapshots] Create a snapshot of a running sandbox. The capture runs in the background: the snapshot starts as pending, is building while the runner captures the sandbox, and becomes ready when the capture finishes. Deleting the source sandbox during the capture fails the snapshot. ```python from daytona import Daytona daytona = Daytona() # Snapshot capture needs a persistent sandbox or one served from a warm template sandbox = daytona.v2.create() snapshot = sandbox.create_snapshot("my-snapshot") print(snapshot.id, snapshot.kind, snapshot.status) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------- | | `name` | str | Sets the snapshot name, 1 to 128 characters of letters, digits, `.`, `_`, and `-`. It cannot start with `.` or with the reserved prefixes `sbx_`, `vol_`, `fn_`, `snap-`, `build-`, `refs`, `by-digest`, `prj-`, and `glb-`. Names are case-sensitive. This parameter is required. Snapshots and images in the project share one name space. A name in use fails with `409`. | The response has the following fields: | **Field** | **Description** | | --------- | --------------- | | `status` | The status is `pending` or `building`, because the call returns before the capture finishes. To wait, call `daytona.v2.snapshots.get(snapshot.id, wait="ready")`. It returns at `ready` or `failed`, or after the server wait of 30 seconds. `timeout` sets a total wait in seconds: the SDK repeats the server wait until the snapshot is `ready` or `failed`, and raises `RequestTimeoutError` if the time runs out first. | - The request requires the `write:snapshots` permission. - The sandbox must be running. - On Linux, the sandbox must be persistent or served from a warm template. - This call does not support Windows sandboxes. ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() // Snapshot capture needs a persistent sandbox or one served from a warm template const sandbox = await daytona.v2.create() const snapshot = await sandbox.createSnapshot('my-snapshot') console.log(snapshot.id, snapshot.kind, snapshot.status) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------- | | `name` | string | Sets the snapshot name, 1 to 128 characters of letters, digits, `.`, `_`, and `-`. It cannot start with `.` or with the reserved prefixes `sbx_`, `vol_`, `fn_`, `snap-`, `build-`, `refs`, `by-digest`, `prj-`, and `glb-`. Names are case-sensitive. This parameter is required. Snapshots and images in the project share one name space. A name in use fails with `409`. | The response has the following fields: | **Field** | **Description** | | --------- | --------------- | | `status` | The status is `pending` or `building`, because the call returns before the capture finishes. To wait, call `daytona.v2.snapshots.get(snapshot.id, { wait: 'ready' })`. It returns at `ready` or `failed`, or after the server wait of 30 seconds. `timeoutSeconds` sets a total wait in seconds: the SDK repeats the server wait until the snapshot is `ready` or `failed`, and throws `RequestTimeoutError` if the time runs out first. | - The request requires the `write:snapshots` permission. - The sandbox must be running. - On Linux, the sandbox must be persistent or served from a warm template. - This call does not support Windows sandboxes. ```bash daytona snapshot create {sandboxId} --name my-snapshot ``` | **Flag** | **Type** | **Description** | | -------- | -------- | --------------- | | `--name` | string | Sets the snapshot name. This flag is required. | | `--timeout` | duration | Sets how long the command waits for the snapshot to be `ready`, as a duration such as `30s` or `10m`. The capture continues after the command stops waiting. The default is `10m`. | | `--no-wait` | boolean | Returns once the capture is queued, without waiting for `ready`. | | `--file`, `-f` | string | Reads the request body from a JSON file, or from standard input with `-`. Flags override its fields. | ```bash curl 'https://api.daytona.com/sandboxes/{sandboxId}/snapshots' \ --request POST \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "name": "my-snapshot" }' ``` The response has the following fields: | **Field** | **Description** | | --------- | --------------- | | `id` | Identifies the new snapshot. | | `status` | The status is `pending`. To wait, call `GET /snapshots/{snapshotId}?wait=ready&timeout_ms=60000`. It answers `200` at `ready` or `failed`, or when the wait expires. `timeout_ms` defaults to `30000` and is at most `60000`. | - The request requires the `write:snapshots` permission. - The sandbox must be running. - On Linux, the sandbox must be persistent or served from a warm template. | **Kind** | **Captures** | **Restore behavior** | | ---------------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`full`** | Memory and disk of a Linux sandbox | Resumes the captured processes and memory. Requires a persistent sandbox or one served from a warm template. Restores in its home region. A snapshot of a sandbox that is not persistent also restores in a region whose runners have the same CPU model and hypervisor version. | | **`checkpoint`** | Processes, memory, and GPU memory of a GPU sandbox | Resumes in a new GPU sandbox. See [GPU sandboxes](/docs/gpu-sandboxes). | | **Status** | **Meaning** | | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `pending` | Accepted; the capture job is queued on the sandbox's runner. | | `building` | The runner is pausing, copying, and packing the sandbox state. | | `ready` | Restorable. | | `failed` | Terminal. `error` carries the reason. The source sandbox keeps running. | ## Restore snapshots [#restore-snapshots] Restore a sandbox from a snapshot. It resumes the captured processes and memory and keeps the source sandbox's CPU, memory, disk, and persistence. The restore runs on the runner that captured the snapshot when that runner can take it, and otherwise on another runner of the region with the same CPU model and hypervisor version. Where cross-region restore is enabled, a restore in another region waits while the snapshot is copied there. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create_from_snapshot("my-snapshot") ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------- | | `snapshot` | str | Sets the snapshot to restore from, by name or by ID, `snap_...`. This parameter is required. | | `name` | str | Sets the display name. If omitted, a name is generated. | | `labels` | Dict\[str, str\] | Attaches key-value metadata to the sandbox. | | `lifecycle_policy` | LifecyclePolicyOptions | Sets the lifecycle policy. It takes the same fields as `lifecycle_policy` in [create a Linux sandbox](/docs/linux-sandboxes#create-a-linux-sandbox). | | `ports` | Sequence\[PortMapping\] | Forwards inbound ports to the sandbox. Import `PortMapping` from `daytona.v2`, for example `PortMapping(port=8080)`. | | `region` | str | Sets the region. The default is the snapshot's home region. Another region requires cross-region restore to be enabled, a source sandbox that was not persistent, and runners in that region with the CPU model and hypervisor version of the snapshot. | | `idempotency_key` | str | Makes a retried create return the same sandbox. If `name` is set, the key is derived from it. Otherwise, each call generates a new key. | | `wait_seconds` | int | Sets how many seconds create waits for the sandbox to start. The server holds the request for up to 3 seconds, and the SDK waits for the rest. `0` returns immediately. The default is `60`. | | `create_timeout_seconds` | int | Sets how many seconds the sandbox has to reach running before it is deleted, at most `86400`. `-1` sets the maximum. The default is `3600`. | - The request requires the `write:sandboxes` permission. - The snapshot must have the `ready` status. ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.createFromSnapshot('my-snapshot') ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------- | | `snapshot` | string | Sets the snapshot to restore from, by name or by ID, `snap_...`. This parameter is required. | | `name` | string | Sets the display name. If omitted, a name is generated. | | `labels` | Record\ | Attaches key-value metadata to the sandbox. | | `lifecyclePolicy` | LifecyclePolicyOptions | Sets the lifecycle policy. It takes the same fields as `lifecyclePolicy` in [create a Linux sandbox](/docs/linux-sandboxes#create-a-linux-sandbox). | | `ports` | PortMapping\[\] | Forwards inbound ports to the sandbox, for example `[{ port: 8080 }]`. | | `region` | string | Sets the region. The default is the snapshot's home region. Another region requires cross-region restore to be enabled, a source sandbox that was not persistent, and runners in that region with the CPU model and hypervisor version of the snapshot. | | `idempotencyKey` | string | Makes a retried create return the same sandbox. If `name` is set, the key is derived from it. Otherwise, each call generates a new key. | | `waitSeconds` | number | Sets how many seconds create waits for the sandbox to start. The server holds the request for up to 3 seconds, and the SDK waits for the rest. `0` returns immediately. The default is `60`. | | `createTimeoutSeconds` | number | Sets how many seconds the sandbox has to reach running before it is deleted, at most `86400`. `-1` sets the maximum. The default is `3600`. | - The request requires the `write:sandboxes` permission. - The snapshot must have the `ready` status. ```bash daytona sandbox create-from-snapshot my-snapshot --name resumed ``` | **Flag** | **Type** | **Description** | | -------- | -------- | --------------- | | `--name` | string | Sets the display name. If omitted, a name is generated. | | `--label` | stringArray | Attaches a label as `KEY=VALUE`. Repeat the flag for each label. | | `--port` | stringArray | Forwards an inbound port as `PORT` or `PORT/PROTO`. Repeat the flag for each port. | | `--region` | string | Sets the region. The default is the snapshot's home region. Another region requires cross-region restore to be enabled, a source sandbox that was not persistent, and runners in that region with the CPU model and hypervisor version of the snapshot. | | `--idempotency-key` | string | Makes a retried create return the same sandbox. The default is a key derived from `--name`, or a random key when no name is set. | | `--lifecycle-timeout` | duration | Sets the wall-clock lifetime as a Go duration such as `2h`, until `--on-lifecycle-timeout` fires. The default is the project or platform default, if one is enabled. | | `--on-lifecycle-timeout` | string | Sets the action when `--lifecycle-timeout` elapses. The CLI accepts only `delete`. The default is `pause` when the source sandbox of the snapshot was persistent, and `delete` otherwise. | | `--idle-timeout` | duration | Sets the idle time as a Go duration, at least `1m`, until `--on-idle-timeout` fires. By default, there is no idle timeout unless the project sets one. | | `--on-idle-timeout` | string | Sets the action when `--idle-timeout` elapses, `delete`. It is required with `--idle-timeout`. | | `--create-ttl` | duration | Sets how long the sandbox has to reach running before the server deletes it, as a Go duration. `max` sets the server maximum, 24 hours. The default is `1h`. | | `--timeout` | duration | Sets how long the command waits for the sandbox to run, as a duration such as `30s` or `10m`. The default is `10m`. | | `--no-wait` | boolean | Prints the create response once the server answers, without waiting for the sandbox to run. The server holds the response for up to 3 seconds. | | `--file`, `-f` | string | Reads the request body from a JSON file, or from standard input with `-`. Flags override its fields. | - The request requires the `write:sandboxes` permission. - The snapshot must have the `ready` status. - Reference the snapshot by name or by ID, `snap_...`. ```bash curl 'https://api.daytona.com/sandboxes/from-snapshot' \ --request POST \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "snapshot": "my-snapshot" }' ``` | **Field** | **Type** | **Description** | | --------- | -------- | --------------- | | `snapshot` | string | Sets the snapshot to restore from, by name or by ID, `snap_...`. This field is required. | | `name` | string | Sets the display name. If omitted, a name is generated. | | `labels` | object | Attaches key-value metadata to the sandbox. | | `lifecycle_policy` | object | Sets the lifecycle policy. It takes the same fields as `lifecycle_policy` in [create a Linux sandbox](/docs/linux-sandboxes#create-a-linux-sandbox). | | `ports` | array | Forwards inbound ports to the sandbox. | | `region_id` | string | Sets the region. The default is the snapshot's home region. Another region requires cross-region restore to be enabled, a source sandbox that was not persistent, and runners in that region with the CPU model and hypervisor version of the snapshot. A region that covers other regions, such as `us-east`, requires `idempotency_key`. | | `idempotency_key` | string | Makes a retried create return the same sandbox. You can also send it as the `Idempotency-Key` header. | | `create_timeout_seconds` | integer | Sets how many seconds the sandbox has to reach running before it is deleted, at most `86400`. `-1` sets the maximum. The default is `3600`. | | `wait_seconds` | integer | Sets how many seconds the server holds the request for the sandbox to start, at most `3`. `0` returns immediately. The default is `3`. | - The request requires the `write:sandboxes` permission. - The snapshot must have the `ready` status. ## Operations [#operations] ### List snapshots [#list-snapshots] ```python from daytona import Daytona daytona = Daytona() page = daytona.v2.snapshots.list() for snapshot in page.items: print(snapshot.name, snapshot.kind, snapshot.status) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------- | | `name` | str | Filters the list by exact snapshot name. | | `sandbox_id` | str | Filters the list to snapshots captured from this sandbox. | | `limit` | int | Sets the page size, from `1` to `200`. The default is `100`. | | `cursor` | str | Resumes the list after the previous page. Pass the `next_cursor` of that page. | ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const page = await daytona.v2.snapshots.list() for (const snapshot of page.items) { console.log(snapshot.name, snapshot.kind, snapshot.status) } ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------- | | `name` | string | Filters the list by exact snapshot name. | | `sandboxId` | string | Filters the list to snapshots captured from this sandbox. | | `limit` | number | Sets the page size, from `1` to `200`. The default is `100`. | | `cursor` | string | Resumes the list after the previous page. Pass the `nextCursor` of that page. | ```bash daytona snapshot list ``` | **Flag** | **Type** | **Description** | | -------- | -------- | --------------- | | `--limit` | int | Sets the page size, from `1` to `200`. The default is `100`. | | `--cursor` | string | Resumes the list after the previous page. | ```bash curl 'https://api.daytona.com/snapshots' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` | **Field** | **Type** | **Description** | | --------- | -------- | --------------- | | `name` | string | Filters the list by exact snapshot name. | | `sandbox_id` | string | Filters the list to snapshots captured from this sandbox. | | `limit` | integer | Sets the page size, from `1` to `200`. The default is `100`. | | `cursor` | string | Resumes the list after the previous page. Pass the `next_cursor` of that page. | The API returns the following fields. The SDKs use the same names, except where the description says otherwise. | **Field** | **Description** | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ | | `id` | Snapshot ID. | | `name` | Unique name within the project. Used for restore. | | `class` | `linux` or `gpu`. The SDKs name it `sandbox_class` in Python and `sandboxClass` in TypeScript. | | `kind` | `full` for Linux, or `checkpoint` for GPU. | | `status` | `pending`, `building`, `ready`, or `failed`. | | `sandbox_id` | The ID of the source sandbox. It stays after the source sandbox is deleted, and becomes `null` once Daytona purges the record of the deleted sandbox. | | `region_id` | Home region. The SDKs name it `region`. | | `region_ids` | The home region, followed by every other region that holds a copy of the snapshot. The SDKs name it `available_in` in Python and `availableIn` in TypeScript. | | `bytes` | Size of the captured disk in bytes. `null` for `full` snapshots. | | `memory_bytes` | Size of the captured memory, `full` only. | | `error` | Failure reason when `status` is `failed`. | #### Iterate over all snapshots [#iterate-over-all-snapshots] ```python from daytona import Daytona daytona = Daytona() for snapshot in daytona.v2.snapshots.iter(): print(snapshot.name, snapshot.kind, snapshot.status) ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() for await (const snapshot of daytona.v2.snapshots.iter()) { console.log(snapshot.name, snapshot.kind, snapshot.status) } ``` ```bash # Follow every page until the server returns no cursor daytona snapshot list --all ``` ```bash curl 'https://api.daytona.com/snapshots?cursor={next_cursor}' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ### Get a snapshot [#get-a-snapshot] ```python from daytona import Daytona daytona = Daytona() snapshot = daytona.v2.snapshots.get("{snapshotId}") print(snapshot.kind, snapshot.status) ``` - The request requires the `read:snapshots` permission. - `get` takes the snapshot ID, `snap_...`, or the name. ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const snapshot = await daytona.v2.snapshots.get('{snapshotId}') console.log(snapshot.kind, snapshot.status) ``` - The request requires the `read:snapshots` permission. - `get` takes the snapshot ID, `snap_...`, or the name. ```bash daytona snapshot get {snapshotId} ``` - The request requires the `read:snapshots` permission. - The command takes the snapshot ID, `snap_...`, or the name. ```bash curl 'https://api.daytona.com/snapshots/{snapshotId}' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` | **Field** | **Type** | **Description** | | --------- | -------- | --------------- | | `id_only` | boolean | Resolves the path value only as an ID, without falling back to a name. The default is `false`. | - The request requires the `read:snapshots` permission. - The path takes the snapshot ID, `snap_...`, or the name. ### Delete snapshots [#delete-snapshots] Delete a snapshot. It cannot be deleted while a sandbox restored from it exists, including a restored sandbox whose deletion has not finished. 1. Go to [Daytona Dashboard ↗](https://app.daytona.com/dashboard/snapshots) 2. Open the actions menu of a snapshot and click 3. Click to confirm ```python from daytona import Daytona daytona = Daytona() daytona.v2.snapshots.delete("{snapshotId}") ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() await daytona.v2.snapshots.delete('{snapshotId}') ``` ```bash daytona snapshot delete {snapshotId} ``` - The request requires the `delete:snapshots` permission. - The command asks for confirmation. - A non-interactive shell requires `--yes`. ```bash curl 'https://api.daytona.com/snapshots/{snapshotId}' \ --request DELETE \ --header 'Authorization: Bearer YOUR_API_KEY' ``` | **Field** | **Type** | **Description** | | --------- | -------- | --------------- | | `id_only` | boolean | Resolves the path value only as an ID, without falling back to a name. The default is `false`. | ## Errors [#errors] The SDKs raise these errors with the codes in the following table, and the API returns them in the `code` field. | **Code** | **Meaning** | **What to do** | | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | **`SNAPSHOT_NOT_FOUND`** | The restore names a snapshot that does not exist in the project. | Check the name or ID with [list snapshots](#list-snapshots). | | **`SNAPSHOT_NOT_READY`** | The restore names a snapshot that is `pending`, `building`, or `failed`. | Wait until the snapshot is `ready`. A `failed` snapshot does not become `ready`: create a new one. | | **`NOT_SUPPORTED_FOR_CLASS`** | The snapshot create names a Windows or macOS sandbox. | To save the disk, [capture an image](/docs/images#capture-images). | | **`IDEMPOTENCY_KEY_REQUIRED`** | An API restore names a region that covers other regions, such as `us-east`, without an `Idempotency-Key` header. The SDKs and the CLI always send a key. | Pass an idempotency key, or name a single region. | | **`CONFLICT`** | The name is in use by a snapshot or an image, the sandbox is not running, the Linux sandbox is neither persistent nor served from a warm template, the target region has no runner with the CPU model and hypervisor version of the snapshot, or a delete names a snapshot that a sandbox still references. | Use another name, start the sandbox, restore in the home region, or delete the restored sandboxes first. | | **`BAD_REQUEST`** | The snapshot name is invalid, the restore names another region that the snapshot cannot be copied to (for example, cross-region restore is not enabled, the source sandbox was persistent, or the snapshot is too large), the restore names a `checkpoint`, or the path value matches both a snapshot ID and the name of another snapshot. | Fix the name, restore in the home region, restore a `checkpoint` as a [GPU sandbox](/docs/gpu-sandboxes), or pass `id_only`. | ## Permissions [#permissions] Snapshots are scoped to a project. Access is governed by three permissions, which you can grant to an [organization role](/docs/organizations#roles) or an [API key](/docs/api-keys). Restoring a snapshot creates a sandbox, so it requires the permission to create sandboxes. The [audit logs](/docs/audit-logs) record snapshot creates and deletes. | **Permission** | **Grants** | | ---------------------- | ---------------------- | | **`read:snapshots`** | List and get snapshots | | **`write:snapshots`** | Create snapshots | | **`delete:snapshots`** | Delete snapshots | # Images (/docs/images) An image is the filesystem a sandbox boots from, together with the environment variables, working directory, entrypoint, and command the sandbox starts with. Daytona accepts standard OCI images, the same ones you build and push with Docker, and converts each one into a boot-optimized format when you register it. Images belong to a project, and a sandbox references its image by name or ID. A sandbox create does not pull from a registry, so a sandbox boots only from an image already registered in the project. Every sandbox created from an image starts with the same filesystem and configuration. An image holds no running processes or memory. A [snapshot](/docs/snapshots) saves the memory and disk of a running sandbox, and a restored sandbox resumes its processes. | **Concept** | **Description** | | ---------------------- | --------------------------------------------------------------------------------------------------- | | **Registry image** | An image pulled from a public or private registry and registered under a name. | | **Dockerfile build** | An image Daytona builds from Dockerfile text, with or without a build context. | | **Capture** | An image made from the filesystem of a running Linux or Windows sandbox. | | **Windows base image** | A base image Daytona provides for Windows sandboxes. It boots in every region. | | **Anonymous image** | An image without a name. Daytona deletes it after it goes unused for its idle window. | | **Status** | Pending, building, ready, or failed. Sandboxes boot only from a ready image. | | **Home region** | The region where Daytona builds, pulls, or captures the image. | ## Use cases [#use-cases] Images are used when many sandboxes need the same software, files, or configuration. - **Preinstalled dependencies.** Packages, language runtimes, and tools are installed once in a Dockerfile build, and every sandbox from the image starts with them. A repeat build of the same Dockerfile and build context reuses the earlier build instead of running a new one. A Dockerfile that copies local files needs a [build context](#build-context) of at most 1 GiB. - **Configured sandboxes as templates.** A sandbox set up by hand or by an agent is captured, and new sandboxes start from its filesystem. The source sandbox keeps running during the capture. A named capture stays until you delete it. - **Private application images.** Images that a CI pipeline pushes to a private registry are imported with the project's [registry credentials](/docs/registries) and boot in sandboxes. Pulling again under the same name re-imports the image, and creates from it fail until the new pull is ready. The API call returns once the pull is queued, and the SDKs and the CLI wait by default until the image is ready. - **Environments written by agents.** An agent writes a Dockerfile, builds it, and boots sandboxes from the result, without access to your build infrastructure. The SDKs build the image and create the sandbox in one call. A failed build creates no sandbox. - **Evaluation and reinforcement learning (RL).** Each test case or episode starts in a new sandbox from the same image, so results do not depend on another run. An image holds no running processes or memory, so each run boots from the same files. Runs that need processes already running start from a [snapshot](/docs/snapshots) instead, which saves memory and disk. ## Create sandboxes from images [#create-sandboxes-from-images] Create a sandbox from an image registered in the project, by its name or ID. A sandbox create does not pull from a registry, so the image is [pulled](#pull-images), [built](#build-images), or [captured](#capture-images) first. Registration runs in the background, and a create from an image that is not ready yet fails. ```python from daytona import Daytona daytona = Daytona() # Register python:3.12-slim under the name python-3.12 image = daytona.v2.images.pull("python:3.12-slim", name="python-3.12") # Each wait returns after 30 seconds at most; a create from an image that is not ready fails while image.status not in ("ready", "failed"): image = daytona.v2.images.get(image.id, wait="ready") if image.status == "failed": raise RuntimeError(image.error) sandbox = daytona.v2.create("python-3.12") ``` - The requests require the `write:images` and `write:sandboxes` permissions. - Set `timeout` in seconds to wait in one call until the image is ready or failed. When the time runs out first, the call raises `RequestTimeoutError`. - A create rejects a value that contains `/` or `:` as a registry reference, so pass the name or ID of a registered image. ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() // Register python:3.12-slim under the name python-3.12 let image = await daytona.v2.images.pull('python:3.12-slim', { name: 'python-3.12' }) // Each wait returns after 30 seconds at most; a create from an image that is not ready fails while (image.status !== 'ready' && image.status !== 'failed') { image = await daytona.v2.images.get(image.id, { wait: 'ready' }) } if (image.status === 'failed') throw new Error(image.error ?? 'image build failed') const sandbox = await daytona.v2.create('python-3.12') ``` - The requests require the `write:images` and `write:sandboxes` permissions. - Set `timeoutSeconds` to wait in one call until the image is ready or failed. When the time runs out first, the call throws `RequestTimeoutError`. - A create rejects a value that contains `/` or `:` as a registry reference, so pass the name or ID of a registered image. ```bash # Register python:3.12-slim under the name python-3.12; waits until the image is ready daytona image create python-3.12 --ref python:3.12-slim daytona sandbox create --image python-3.12 ``` - The requests require the `write:images` and `write:sandboxes` permissions. - A create rejects a value that contains `/` or `:` as a registry reference, so pass the name or ID of a registered image. ```bash # Register python:3.12-slim under the name python-3.12; the response carries its id curl 'https://api.daytona.com/images' \ --request POST \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "name": "python-3.12", "source": { "type": "registry", "ref": "python:3.12-slim" } }' # Returns on ready or failed, or after timeout_ms; repeat while status is pending or building curl 'https://api.daytona.com/images/{imageId}?wait=ready&timeout_ms=60000' \ --header 'Authorization: Bearer YOUR_API_KEY' curl 'https://api.daytona.com/sandboxes' \ --request POST \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "image": "python-3.12" }' ``` - The requests require the `write:images` and `write:sandboxes` permissions. - The default `timeout_ms` is `30000`, and the maximum is `60000`. Larger values are treated as `60000`. - A create rejects a value that contains `/` or `:` as a registry reference, so pass the name or ID of a registered image. ### Inline Dockerfile [#inline-dockerfile] Build an image from Dockerfile text and create a sandbox from it. The SDKs do both in one call. The image is anonymous: it has no name, and the default image list does not show it. If the same Dockerfile was built before under a name, the sandbox starts from that named image instead. Daytona deletes an anonymous image once it goes unused for its idle window, the server maximum of 7 days by default; every sandbox create from the image restarts the window. The window starts when the image is created, so a window shorter than the build deletes the image before it is ready. The Dockerfile must be self-contained. There is no build context, so instructions that copy local files have nothing to copy. Use a [build context](#build-context) for those. ```python from daytona import Daytona from daytona.v2 import ImageBuilder daytona = Daytona() # Builds an anonymous image from the Dockerfile, then creates the sandbox from it sandbox = daytona.v2.create_from_build( ImageBuilder.from_dockerfile("FROM python:3.12-slim\nRUN pip install requests\n") ) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | `build_timeout` | float | Sets how many seconds the build can take. A build that runs longer fails with `408` `REQUEST_TIMEOUT` and creates no sandbox. The build keeps running, and its anonymous image is deleted after its idle window. By default, or with `0`, there is no limit. | | `wait_seconds` | int | Sets how many seconds the create waits for the sandbox to start, as in `create`. It does not limit the build. The default is `60`. | | `idle_expiry_seconds` | int | Sets the idle window of the image in seconds. It applies only to the image. It is ignored when the build reuses the build of a named image. | | `region` | str | Selects the region for both the build and the sandbox. | - The requests require the `write:images` and `write:sandboxes` permissions. - `cpu_arch` also applies to both the build and the sandbox. - Every other keyword argument goes to `create`. ```typescript import { Daytona } from '@daytona/sdk' import { ImageBuilder } from '@daytona/sdk/v2' const daytona = new Daytona() // Builds an anonymous image from the Dockerfile, then creates the sandbox from it const sandbox = await daytona.v2.createFromBuild( ImageBuilder.fromDockerfile('FROM python:3.12-slim\nRUN pip install requests\n'), ) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | `buildTimeoutSeconds` | number | Sets how many seconds the build can take. A build that runs longer fails with `408` `REQUEST_TIMEOUT` and creates no sandbox. The build keeps running, and its anonymous image is deleted after its idle window. By default, or with `0`, there is no limit. | | `waitSeconds` | number | Sets how many seconds the create waits for the sandbox to start, as in `create`. It does not limit the build. The default is `60`. | | `idleExpirySeconds` | number | Sets the idle window of the image in seconds. It applies only to the image. It is ignored when the build reuses the build of a named image. | | `region` | string | Selects the region for both the build and the sandbox. | - The requests require the `write:images` and `write:sandboxes` permissions. - `cpuArch` also applies to both the build and the sandbox. ```bash # Build an anonymous image from the inline Dockerfile; the response carries its id curl 'https://api.daytona.com/images' \ --request POST \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "dockerfile": "FROM python:3.12-slim\nRUN pip install requests\n" }' # Returns on ready or failed, or after timeout_ms; repeat while status is pending or building curl 'https://api.daytona.com/images/{imageId}?wait=ready&timeout_ms=60000' \ --header 'Authorization: Bearer YOUR_API_KEY' # Create the sandbox from the image id curl 'https://api.daytona.com/sandboxes' \ --request POST \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "image": "{imageId}" }' ``` | **Field** | **Type** | **Description** | | --------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | `dockerfile` | string | Sets the Dockerfile text. The Dockerfile must not copy local files. This field is required. This field cannot be sent together with `source`. | | `name` | string | Sets the image name. Without a name, the image is anonymous, unless the build reuses the build of a named image; the call then returns that named image. | | `idle_expiry_seconds` | integer | Sets the idle window of the image in seconds, from `1` up to the server maximum. `-1` sets the maximum. Other values return `400` `IDLE_OUT_OF_RANGE`. The default is the server maximum. It is ignored when the build reuses the build of a named image. When the build reuses an anonymous image, that image keeps the longer of the two windows. | ### Windows images [#windows-images] Create a [Windows sandbox](/docs/windows-sandboxes) from a Windows image. Windows sandboxes boot only from Windows images: a platform base image, which boots in every region, or a Windows image captured in the project, which boots only in the region it lives in. {/* snippet-check: skip POST /sandboxes/windows is hidden from the public API contract until relaunch. */} ```bash curl 'https://api.daytona.com/sandboxes/windows' \ --request POST \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "image": "win2022" }' ``` | **Field** | **Type** | **Description** | | --------- | -------- | ----------------------------------------------------------------------------------------------------------- | | `image` | string | Sets the Windows image by name or ID. The image is a platform base image or a Windows image captured in the project. This field is required. | - The request requires the `write:sandboxes` permission. - The organization must have the `windows_sandboxes` feature flag. - Windows sandboxes are available on request. ## Pull images [#pull-images] Pull an image from a registry and register it under a name. The pull runs in the background. The API call returns once the pull is queued, and the SDKs and the CLI wait until the image is ready by default. Pulling again under the name of an existing registry or Dockerfile image re-imports the image: it keeps its ID, returns to pending, and sandbox creates from it fail until the new pull is ready. A failed pull keeps its name, so pull again under the name to retry. A private registry authenticates with the [registry credential](/docs/registries) stored for the image host. ```python from daytona import Daytona daytona = Daytona() image = daytona.v2.images.pull("node:22-slim", name="my-awesome-image") ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | ------------------------------------- | | `name` | str | Sets the image name. The name is 1 to 128 characters of letters, digits, `.`, `_`, and `-`. It must not start with `.`, `sbx_`, `vol_`, `fn_`, `snap-`, `build-`, `refs`, `by-digest`, `prj-`, or `glb-`. It must not have the format of an image ID, `img_...`. Without a name, the image is anonymous. An anonymous pull reuses an existing pending, building, or ready anonymous image of the same reference in the same region. Images and snapshots share one name space per project. A name that belongs to a captured image, a Windows image, or a snapshot returns `409`. | - The request requires the `write:images` permission. - `images.pull` waits until the image is ready unless you pass `wait=False`. ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const image = await daytona.v2.images.pull('node:22-slim', { name: 'my-awesome-image' }) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | ------------------------------------- | | `name` | string | Sets the image name. The name is 1 to 128 characters of letters, digits, `.`, `_`, and `-`. It must not start with `.`, `sbx_`, `vol_`, `fn_`, `snap-`, `build-`, `refs`, `by-digest`, `prj-`, or `glb-`. It must not have the format of an image ID, `img_...`. Without a name, the image is anonymous. An anonymous pull reuses an existing pending, building, or ready anonymous image of the same reference in the same region. Images and snapshots share one name space per project. A name that belongs to a captured image, a Windows image, or a snapshot returns `409`. | - The request requires the `write:images` permission. - `images.pull` waits until the image is ready unless you pass `wait: false`. ```bash daytona image create my-awesome-image --ref node:22-slim ``` | **Flag** | **Type** | **Description** | | -------- | -------- | --------------- | | `--ref` | string | Sets the registry reference to pull. This flag is required. | | `--timeout` | string | Sets how long the command waits for the pull to finish. The default is `10m`. | | `--no-wait` | boolean | Returns once the pull is queued, without waiting for it to finish. | - The request requires the `write:images` permission. - The name is 1 to 128 characters of letters, digits, `.`, `_`, and `-`. - The name must not start with `.`, `sbx_`, `vol_`, `fn_`, `snap-`, `build-`, `refs`, `by-digest`, `prj-`, or `glb-`. - The name must not have the format of an image ID, `img_...`. - Images and snapshots share one name space per project, so the name must not belong to a captured image, a Windows image, or a snapshot. ```bash curl 'https://api.daytona.com/images' \ --request POST \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "name": "my-awesome-image", "source": { "type": "registry", "ref": "node:22-slim" } }' ``` - The request requires the `write:images` permission. - Wait with `GET /images/{imageId}?wait=ready`, using the `id` from the response, before creating sandboxes. - The name is 1 to 128 characters of letters, digits, `.`, `_`, and `-`. - The name must not start with `.`, `sbx_`, `vol_`, `fn_`, `snap-`, `build-`, `refs`, `by-digest`, `prj-`, or `glb-`. - The name must not have the format of an image ID, `img_...`. - Images and snapshots share one name space per project, so the name must not belong to a captured image, a Windows image, or a snapshot. ## Build images [#build-images] Build an image from a Dockerfile and register it under a name. The build runs in the background: the call returns once it is queued, and the image can be used once it is ready. Builds are deduplicated within a project and region. Submitting the same Dockerfile and build context for the same CPU architecture reuses the earlier build instead of running a new one; if that build already finished, the new image is ready at once. A build without a name that reuses the build of a named image returns that named image, which stays permanent. ```python from daytona import Daytona from daytona.v2 import ImageBuilder daytona = Daytona() image = daytona.v2.images.build( ImageBuilder.from_dockerfile("FROM python:3.12-slim\nRUN pip install requests"), name="my-awesome-image", ) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | ------------------------------------- | | `name` | str | Sets the image name. Without a name, the image is anonymous, unless the build reuses the build of a named image; the call then returns that named image. | | `idle_expiry_seconds` | int | Sets how many seconds an anonymous image can go without a sandbox create before deletion. `-1` sets the maximum. The default is the server maximum. It is allowed only without `name`. It is ignored when the build reuses the build of a named image. When the build reuses an anonymous image, that image keeps the longer of the two windows. | - The request requires the `write:images` permission. - `images.build` takes an `ImageBuilder`, not a raw Dockerfile string. - Wait with `images.get(image.id, wait="ready")` before you use the image. ```typescript import { Daytona } from '@daytona/sdk' import { ImageBuilder } from '@daytona/sdk/v2' const daytona = new Daytona() const image = await daytona.v2.images.build( ImageBuilder.fromDockerfile('FROM python:3.12-slim\nRUN pip install requests'), { name: 'my-awesome-image' }, ) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | ------------------------------------- | | `name` | string | Sets the image name. Without a name, the image is anonymous, unless the build reuses the build of a named image; the call then returns that named image. | | `idleExpirySeconds` | number | Sets how many seconds an anonymous image can go without a sandbox create before deletion. `-1` sets the maximum. The default is the server maximum. It is allowed only without `name`. It is ignored when the build reuses the build of a named image. When the build reuses an anonymous image, that image keeps the longer of the two windows. | - The request requires the `write:images` permission. - Wait with `images.get(image.id, { wait: 'ready' })` before you use the image. ```bash # The CLI uploads a build context; write the Dockerfile into it first mkdir -p build && printf 'FROM python:3.12-slim\nRUN pip install requests\n' > build/Dockerfile # Waits until the image is ready daytona image build my-awesome-image --context build ``` - The request requires the `write:images` permission. - The command waits up to `--timeout`, which defaults to `10m`. ```bash curl 'https://api.daytona.com/images' \ --request POST \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "name": "my-awesome-image", "dockerfile": "FROM python:3.12-slim\nRUN pip install requests" }' ``` | **Field** | **Type** | **Description** | | ------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `dockerfile` | string | Sets the Dockerfile text. The Dockerfile must not copy local files. To send a build context, use the multipart form in [build context](#build-context). | | `name` | string | Sets the image name. Without a name, the image is anonymous, unless the build reuses the build of a named image; the call then returns that named image. | The response has the following fields: | **Field** | **Description** | | --------- | --------------- | | `id` | Identifies the new image. | | `status` | The status is `pending` for a new build. It is `building` when the request joined a build in progress, and `ready` when the request reused a finished build. | ### Build context [#build-context] Build an image from a Dockerfile and a build context. Daytona uploads the context to the image's home region and runs the build there. A build context is needed when the Dockerfile copies local files. Without one, the Dockerfile is sent as text, as in [build images](#build-images). The SDKs and the CLI upload a context of up to 1 GiB. ```python from daytona import Daytona daytona = Daytona() # The context holds the Dockerfile at its root image = daytona.v2.images.build_from_context("context.tar", name="my-awesome-image") ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------- | | `context` | bytes or str | Sets the build context: the bytes of a tar archive, or the path of a `.tar` file. The archive is at most 1 GiB. This parameter is required. | | `dockerfile` | str | Sets the path of the Dockerfile inside the context. The default is `Dockerfile`. | | `name` | str | Sets the image name. Without a name, the image is anonymous, unless the build reuses the build of a named image; the call then returns that named image. | | `idle_expiry_seconds` | int | Sets how many seconds an anonymous image can go without a sandbox create before deletion. The default is the server maximum. It is allowed only without `name`. It is ignored when the build reuses the build of a named image. When the build reuses an anonymous image, that image keeps the longer of the two windows. | - The request requires the `write:images` permission. - `region` and `cpu_arch` work as in [build options](#build-options). - Wait with `images.get(image.id, wait="ready")` before you use the image. ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() // The context holds the Dockerfile at its root const image = await daytona.v2.images.buildFromContext('context.tar', { name: 'my-awesome-image' }) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------- | | `context` | Uint8Array, Blob, or string | Sets the build context: the bytes of a tar archive, or in Node.js the path of a `.tar` file. The archive is at most 1 GiB. This parameter is required. | | `dockerfile` | string | Sets the path of the Dockerfile inside the context. The default is `Dockerfile`. | | `name` | string | Sets the image name. Without a name, the image is anonymous, unless the build reuses the build of a named image; the call then returns that named image. | | `idleExpirySeconds` | number | Sets how many seconds an anonymous image can go without a sandbox create before deletion. The default is the server maximum. It is allowed only without `name`. It is ignored when the build reuses the build of a named image. When the build reuses an anonymous image, that image keeps the longer of the two windows. | - The request requires the `write:images` permission. - `region` and `cpuArch` work as in [build options](#build-options). - Wait with `images.get(image.id, { wait: 'ready' })` before you use the image. ```bash # The context holds the Dockerfile at its root daytona image build my-awesome-image --context context.tar ``` | **Flag** | **Type** | **Description** | | -------------- | -------- | ------------------------------------------------------------------ | | `--context` | string | Sets the build context, a tar archive or a directory. A directory is uploaded without the files its `.dockerignore` excludes. The uploaded context is at most 1 GiB. This flag is required. | | `--dockerfile` | string | Sets the path of the Dockerfile inside the context. The default is `Dockerfile`. | | `--timeout` | string | Sets how long the command waits for the build to finish. The default is `10m`. | | `--no-wait` | boolean | Returns once the build is queued, without waiting for it to finish. | ```bash curl 'https://api.daytona.com/images' \ --request POST \ --header 'Authorization: Bearer YOUR_API_KEY' \ --form 'name=my-awesome-image' \ --form 'context=@context.tar' ``` | **Field** | **Type** | **Description** | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------ | | `context` | file | Sets the build context as a tar archive, at most 64 MiB. This field is required. | | `name` | string | Sets the image name. Without a name, the image is anonymous, unless the build reuses the build of a named image; the call then returns that named image. | | `dockerfile` | string | Sets the path of the Dockerfile inside the context. The default is `Dockerfile`. | | `region_id` | string | Sets the home region of the build. The default is the resolved default region. | | `cpu_arch` | string | Sets the CPU architecture, `amd64` or `arm64`. The default is the region's architecture. | - The request requires the `write:images` permission. - The multipart form takes a context of at most 64 MiB. Upload a larger context, up to 1 GiB, as in [large build contexts](#large-build-contexts). - Wait with `GET /images/{imageId}?wait=ready` before creating sandboxes. ### Large build contexts [#large-build-contexts] Upload a build context of up to 1 GiB and build an image from it. The upload declares the archive by its size and SHA-256, sends the archive in parts straight to storage, and is then completed. Completing the upload verifies the stored archive: its size and SHA-256 must match the declared ones, it must be a well-formed tar archive, and its Dockerfile must be accepted for a build. An archive that fails verification is deleted. An upload belongs to one region, and only a build in that region can use it. When the project already holds a verified upload of the same archive in the region, Daytona returns that upload and the archive is not sent again. The SDKs and the CLI run these steps when they upload a [build context](#build-context). ```bash # Size in bytes and SHA-256 of the archive (on macOS use: shasum -a 256 context.tar) wc -c < context.tar sha256sum context.tar # Declare the upload: replace 10240 with the size from wc and {sha256} with the hash from sha256sum curl 'https://api.daytona.com/build-contexts' \ --request POST \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "bytes": 10240, "sha256": "{sha256}" }' # Split the archive into parts of part_size bytes: part 1 is part-aa, part 2 is part-ab, and so on split -b {partSize} context.tar part- # Upload each part to its url, without an Authorization header curl '{partUrl}' --upload-file part-aa # Verify the uploaded archive curl 'https://api.daytona.com/build-contexts/{uploadId}/complete' \ --request POST \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "region_id": "{regionId}" }' # Build from the verified upload curl 'https://api.daytona.com/images' \ --request POST \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "name": "my-awesome-image", "context_upload_id": "{uploadId}" }' ``` | **Field** | **Type** | **Description** | | --------- | -------- | --------------- | | `bytes` | integer | Sets the size of the archive in bytes, from `1` to `1073741824` (1 GiB). This field is required. | | `sha256` | string | Sets the SHA-256 of the archive, as 64 lowercase hex characters. This field is required. | | `dockerfile` | string | Sets the path of the Dockerfile inside the context. The default is `Dockerfile`. | | `region_id` | string | In the declare request, sets the region of the upload. The default is the resolved default region. In the complete request, it is the `region_id` the declare request returned. This field is required in the complete request. | | `context_upload_id` | string | Sets the `ready` upload to build. The image must be created in the region of the upload. It cannot be combined with `dockerfile` or `source`. | | `name` | string | Sets the image name. Without a name, the image is anonymous, unless the build reuses the build of a named image; the call then returns that named image. | The declare and complete requests return the upload, with the following fields: | **Field** | **Description** | | --------- | --------------- | | `id` | Identifies the upload. | | `region_id` | The region the upload belongs to. | | `state` | The state is `uploading` until the upload is completed and verified, then `ready`. | | `part_size` | The size of every part but the last, in bytes. It is set while the upload is `uploading`. | | `parts` | The parts to upload, each with its `part_number`, its size in `bytes`, and its `url`. It is empty once the upload is `ready`. | | `urls_expire_at` | The time the part URLs stop accepting uploads. | | `upload_expires_at` | The time an upload that was not completed expires and is deleted. | | `expires_at` | The time a `ready` upload can no longer be used by a build. | - The requests require the `write:images` permission. - When the declare request returns the upload as `ready`, the archive is already stored; skip to the build. - Part `n` holds the archive bytes from `(n - 1) * part_size` on. Each part URL accepts one `PUT` of exactly the part's `bytes`. The URL is a credential; do not log or share it. - Upload every part before `urls_expire_at`, complete the upload before `upload_expires_at`, and build before `expires_at`. - Wait with `GET /images/{imageId}?wait=ready` before creating sandboxes. ### Build options [#build-options] [Build](#build-images) accepts an optional home region and CPU architecture. [Pull](#pull-images) accepts a home region and always uses the region's architecture. The same Dockerfile built for two architectures produces two separate images. ```python from daytona import Daytona from daytona.v2 import ImageBuilder daytona = Daytona() image = daytona.v2.images.build( ImageBuilder.from_dockerfile("FROM python:3.12-slim\nRUN pip install requests"), name="my-awesome-image", region="us-east", cpu_arch="amd64", ) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | -------------------------------------------------------------------------------------------------------------------- | | `region` | str | Sets the home region of the image. Earth and country-wide regions such as `us` return an error. The default is the resolved default region for the project, organization, or platform. | | `cpu_arch` | str | Sets the CPU architecture to build for, `amd64` or `arm64`. A build for an architecture that no runner in the region provides stays `pending`. `images.pull` also accepts `cpu_arch`, but a pull ignores the value and uses the region's architecture. A `from_registry` builder with no steps ignores the value the same way. The default is the region's architecture. | ```typescript import { Daytona } from '@daytona/sdk' import { ImageBuilder } from '@daytona/sdk/v2' const daytona = new Daytona() const image = await daytona.v2.images.build( ImageBuilder.fromDockerfile('FROM python:3.12-slim\nRUN pip install requests'), { name: 'my-awesome-image', region: 'us-east', cpuArch: 'amd64' }, ) ``` | **Parameter** | **Type** | **Description** | | ------------- | --------- | ---------------------------------------------------------------------------------------------------------- | | `region` | string | Sets the home region of the image. Earth and country-wide regions such as `us` return an error. The default is the resolved default region for the project, organization, or platform. | | `cpuArch` | CpuArch | Sets the CPU architecture to build for, `amd64` or `arm64`. A build for an architecture that no runner in the region provides stays `pending`. `images.pull` also accepts `cpuArch`, but a pull ignores the value and uses the region's architecture. A `fromRegistry` builder with no steps ignores the value the same way. The default is the region's architecture. | ```bash # build/ holds the Dockerfile from Build images; cpu_arch is read from the JSON request body on stdin echo '{ "cpu_arch": "amd64" }' | daytona image build my-awesome-image \ --context build \ --region us-east \ --file - ``` | **Flag** | **Type** | **Description** | | ---------- | -------- | ----------------------------------------------------------------------------------------------------------------------- | | `--region` | string | Sets the home region of the image. Earth and country-wide regions such as `us` return an error. The default is the resolved default region for the project, organization, or platform. | | `--file` | string | Reads the JSON request body from a file, or from stdin with `-`. The `cpu_arch` field of the body sets the CPU architecture, `amd64` or `arm64`. A build for an architecture that no runner in the region provides stays `pending`. Without `cpu_arch`, the image is built for the region's architecture. | ```bash curl 'https://api.daytona.com/images' \ --request POST \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "name": "my-awesome-image", "dockerfile": "FROM python:3.12-slim\nRUN pip install requests", "region_id": "us-east", "cpu_arch": "amd64" }' ``` | **Field** | **Type** | **Description** | | ---------- | -------- | ---------------------------------------------------------------------------------------------------------- | | `region_id` | string | Sets the home region of the image. Earth and country-wide regions such as `us` return an error. The default is the resolved default region for the project, organization, or platform. | | `cpu_arch` | string | Sets the CPU architecture to build for, `amd64` or `arm64`. A build for an architecture that no runner in the region provides stays `pending`. The default is the region's architecture. | ### Declarative builds [#declarative-builds] Describe an image in code instead of writing a Dockerfile. Start from a registry image, chain the steps the image needs, and build it like any other image. Each step adds one Dockerfile instruction, and the SDK renders the Dockerfile when the build is submitted. Both SDKs render the same Dockerfile for the same steps, so a build submitted from Python and the same build submitted from TypeScript are [deduplicated](#build-images) into one image. A sandbox booted from the image gets its environment variables and runs its entrypoint and command in its working directory, or in the user's home directory when the image sets none or sets the root directory. A sandbox runs as the image's user, or as root when the image sets none, sets root, or sets a numeric user ID. A user set when the sandbox is created replaces the image's user. ```python from daytona import Daytona from daytona.v2 import ImageBuilder daytona = Daytona() builder = ( ImageBuilder.from_registry("python:3.12-slim") .pip_install("requests", "numpy>=1.26") .run_commands("mkdir -p /app/data") .env({"LOG_LEVEL": "debug"}) .workdir("/app") ) image = daytona.v2.images.build(builder, name="my-awesome-image") ``` | **Method** | **Type** | **Description** | | --------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | `from_registry` | str | Sets the registry image reference to start from, rendered as `FROM`. A builder from `from_registry` with no steps is a registry import, not a build. `images.build` pulls that image as [pull images](#pull-images) does. `from_dockerfile` starts from Dockerfile text instead, and the steps are appended after that text. This method is required unless the builder starts from `from_dockerfile`. | | `pip_install` | \*str | Adds Python packages as one `RUN python -m pip install` step. Each package is shell-quoted, so a version specifier such as `numpy>=1.26` stays one argument. | | `run_commands` | \*str | Adds shell commands as one `RUN` step per command. | | `env` | str, str or Mapping\[str, str\] | Sets one variable as a name and a value, or several as a mapping. Each variable is rendered as one `ENV` step. | | `workdir` | str | Sets the working directory, rendered as `WORKDIR`. | - The request requires the `write:images` permission. - Each method returns a new builder and leaves the original unchanged, so one base builder can start several images. ```typescript import { Daytona } from '@daytona/sdk' import { ImageBuilder } from '@daytona/sdk/v2' const daytona = new Daytona() const builder = ImageBuilder.fromRegistry('python:3.12-slim') .pipInstall('requests', 'numpy>=1.26') .runCommands('useradd --create-home app') .env({ LOG_LEVEL: 'debug' }) .user('app') .workdir('/home/app') .entrypoint('python') .cmd('-m', 'http.server', '8080') const image = await daytona.v2.images.build(builder, { name: 'my-awesome-image' }) ``` | **Method** | **Type** | **Description** | | -------------- | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | `fromRegistry` | string | Sets the registry image reference to start from, rendered as `FROM`. A builder from `fromRegistry` with no steps is a registry import, not a build. `images.build` pulls that image as [pull images](#pull-images) does. `fromDockerfile` starts from Dockerfile text instead, and the steps are appended after that text. This method is required unless the builder starts from `fromDockerfile`. | | `pipInstall` | ...string\[\] | Adds Python packages as one `RUN python -m pip install` step. Each package is shell-quoted, so a version specifier such as `numpy>=1.26` stays one argument. | | `runCommands` | ...string\[\] | Adds shell commands as one `RUN` step per command. | | `env` | string, string or Record\ | Sets one variable as a name and a value, or several as a record. Each variable is rendered as one `ENV` step. | | `user` | string | Sets the user for the build steps that follow and for sandboxes from the image, rendered as `USER`. This method is available only in the TypeScript SDK. | | `workdir` | string | Sets the working directory, rendered as `WORKDIR`. | | `entrypoint` | ...string\[\] | Sets the image entrypoint, rendered as `ENTRYPOINT` in exec form. This method is available only in the TypeScript SDK. | | `cmd` | ...string\[\] | Sets the image command, rendered as `CMD` in exec form. With an entrypoint, the `cmd` values are the default arguments of the entrypoint. This method is available only in the TypeScript SDK. | - The request requires the `write:images` permission. - Each method returns a new builder and leaves the original unchanged, so one base builder can start several images. ### Preview the Dockerfile [#preview-the-dockerfile] Render the Dockerfile a builder describes, without submitting a build. Use it to review the generated instructions, or to send the build yourself through the API as the `dockerfile` field of `POST /images`. ```python from daytona.v2 import ImageBuilder builder = ImageBuilder.from_registry("python:3.12-slim").pip_install("requests") print(builder.to_dockerfile()) # FROM python:3.12-slim # RUN python -m pip install requests ``` ```typescript import { ImageBuilder } from '@daytona/sdk/v2' const builder = ImageBuilder.fromRegistry('python:3.12-slim').pipInstall('requests') console.log(builder.toDockerfile()) // FROM python:3.12-slim // RUN python -m pip install requests ``` ## Capture images [#capture-images] Capture the filesystem of a sandbox as an image, and boot new sandboxes from the image. The capture runs in the background, and the image becomes ready when the capture finishes. Linux and Windows sandboxes are captured while running, and they keep running. A macOS sandbox is captured when it is persistent and stopped, as a [filesystem snapshot](/docs/macos-sandboxes#filesystem-snapshot). A GPU sandbox saves its state as a [checkpoint](/docs/snapshots) instead. A named capture is permanent until you delete it. An unnamed capture is anonymous and is deleted once unused for its idle window, the server maximum of 7 days by default; every sandbox create from the image restarts the window. To keep an anonymous capture, [promote](#promote-images) it. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.process.run("pip install requests") image = sandbox.capture_image(name="my-env") # Wait until the capture is ready, then boot new sandboxes from it while image.status not in ("ready", "failed"): image = daytona.v2.images.get(image.id, wait="ready") if image.status == "failed": raise RuntimeError(image.error) clone = daytona.v2.create("my-env") ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------------------------------------------------------------------------------------------------------------------- | | `name` | str | Sets the image name. The default is `None`, which makes the image anonymous. The name must be unique in the project. | | `idle_expiry_seconds` | int | Sets how many seconds an anonymous image can go without a sandbox create before deletion. `-1` sets the maximum. The default is the server maximum. It is allowed only without `name`. | ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() await sandbox.process.run('pip install requests') let image = await sandbox.captureImage({ name: 'my-env' }) // Wait until the capture is ready, then boot new sandboxes from it while (image.status !== 'ready' && image.status !== 'failed') { image = await daytona.v2.images.get(image.id, { wait: 'ready' }) } if (image.status === 'failed') throw new Error(image.error ?? 'image build failed') const clone = await daytona.v2.create('my-env') ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------------------------------------------------------------------------------------------------------------------- | | `name` | string | Sets the image name. The default is `undefined`, which makes the image anonymous. The name must be unique in the project. | | `idleExpirySeconds` | number | Sets how many seconds an anonymous image can go without a sandbox create before deletion. `-1` sets the maximum. The default is the server maximum. It is allowed only without `name`. | ```bash # Named capture: permanent until deleted daytona image capture {sandboxId} --name my-env # Anonymous capture, deleted after the server maximum idle window without a sandbox create daytona image capture {sandboxId} ``` | **Flag** | **Type** | **Description** | | ---------- | -------- | --------------------------------------------------------------------------------------------------------------------------- | | `--name` | string | Sets the image name, which must be unique in the project. Without a name, the image is anonymous. | | `--timeout` | string | Sets how long the command waits for the image to be ready. The default is `10m`. | | `--no-wait` | boolean | Returns once the capture is queued, without waiting for the image to be ready. | ```bash curl 'https://api.daytona.com/sandboxes/{sandboxId}/images' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "name": "my-env" }' ``` | **Field** | **Type** | **Description** | | --------- | --------- | --------------------------------------------------------------------------------------------------------------------------- | | `name` | string | Sets the image name. Without a name, the image is anonymous. The name must be unique in the project. | | `idle_expiry_seconds` | integer | Sets how many seconds an anonymous image can go without a sandbox create before deletion. `-1` sets the maximum. The default is the server maximum. It is allowed only without `name`. | - The request requires the `write:images` and `write:sandboxes` permissions. - Wait with `GET /images/{imageId}?wait=ready` before using the image. ## Promote images [#promote-images] Promote an anonymous image by giving it a name. A promoted image is permanent: it is no longer deleted after its idle window, and the default image list shows it. Promotion works only on anonymous images; an image that already has a name cannot be renamed. ```python from daytona import Daytona daytona = Daytona() image = daytona.v2.images.promote("{imageId}", "my-env") print(image.name) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | ------------------------------------------------------- | | `image_id` | str | Identifies the image by its ID, `img_...`. This parameter is required. | | `name` | str | Sets the image name. This parameter is required. The name must be unique in the project. | ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const image = await daytona.v2.images.promote('{imageId}', 'my-env') console.log(image.name) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | ------------------------------------------------------- | | `imageId` | string | Identifies the image by its ID, `img_...`. This parameter is required. | | `name` | string | Sets the image name. This parameter is required. The name must be unique in the project. | ```bash daytona image promote {imageId} my-env ``` ```bash curl 'https://api.daytona.com/images/{imageId}' \ --request PATCH \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "name": "my-env" }' ``` | **Field** | **Type** | **Description** | | --------- | -------- | ---------------------------------------------------- | | `name` | string | Sets the image name. This field is required. The name must be unique in the project. | ## Convert images [#convert-images] Convert an image to the current image format before its first use. Images registered by the migration from Daytona v0 are stored in an older format until they are converted. Such an image converts on its first Linux sandbox create, which waits in the queued state while the conversion runs. GPU sandboxes, Windows sandboxes, and builds that name the image as their source refuse it until it is converted. Converting ahead of time removes the wait from the first create and makes the image usable everywhere. ```bash curl 'https://api.daytona.com/images/{imageId}/convert' \ --request POST \ --header 'Authorization: Bearer YOUR_API_KEY' # Returns on ready or failed, or after timeout_ms; repeat while status is pending or building curl 'https://api.daytona.com/images/{imageId}?wait=ready&timeout_ms=60000' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` The response has the following fields: | **Field** | **Description** | | --------- | --------------- | | `id` | Identifies the image. | | `converted` | The value is `true` when the call started a conversion or joined one in progress. The value is `false` when the image is already in the current format and nothing was queued. | | `from_format` | The `format_version` of the image before the call. | | `to_format` | The format the conversion targets, the current one. | | `status` | The image status after the call: `pending` or `building` while the image converts, or its own status when it is already in the current format. | - The requests require the `write:images` permission. - The call takes the image ID, `img_...`, or the image name. - An image that needs conversion has `format_outdated` set to `true`. ## Operations [#operations] ### List images [#list-images] List images in the project, newest first. The list returns named images by default. Anonymous images, such as the ones [inline Dockerfile](#inline-dockerfile) builds create, appear only when you ask for them. ```python from daytona import Daytona daytona = Daytona() page = daytona.v2.images.list() for image in page.items: print(image.name, image.status) ``` | **Parameter** | **Type** | **Description** | | ------------- | ------------------------- | --------------------------------------------------------------------------------- | | `anonymous` | bool | Selects which images to list. `True` returns anonymous images only, and `False` returns named images only. The default is `False`. | | `limit` | int | Sets the page size, from `1` to `200`. The default is `100`. | | `cursor` | str | Resumes the list after the previous page. Pass the `next_cursor` of that page, which is set when more images exist. | | `name` | str | Filters the list by exact image name. | | `sandbox_id` | str | Lists only the captures taken from this sandbox. | | `platform` | str | Selects platform images, which Daytona publishes for every project. `"true"` lists platform images only, `"false"` lists the project's images only, and `"any"` lists both. The default is `"false"`. | - The request requires the `read:images` permission. ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const page = await daytona.v2.images.list() for (const image of page.items) { console.log(image.name, image.status) } ``` | **Parameter** | **Type** | **Description** | | ------------- | --------------------------------- | ------------------------------------------------------------------- | | `anonymous` | boolean | Selects which images to list. `true` returns anonymous images only, and `false` returns named images only. The default is `false`. | | `limit` | number | Sets the page size, from `1` to `200`. The default is `100`. | | `cursor` | string | Resumes the list after the previous page. Pass the `nextCursor` of that page, which is set when more images exist. | | `name` | string | Filters the list by exact image name. | | `sandboxId` | string | Lists only the captures taken from this sandbox. | | `platform` | string | Selects platform images, which Daytona publishes for every project. `'true'` lists platform images only, `'false'` lists the project's images only, and `'any'` lists both. The default is `'false'`. | - The request requires the `read:images` permission. ```bash daytona image list ``` | **Flag** | **Type** | **Description** | | ------------- | -------- | ------------------------------------------------------- | | `--anonymous` | string | Selects which images to list. `true` lists anonymous images only, and `false` lists named images only. The default is `false`. | | `--platform` | string | Selects platform images, which Daytona publishes for every project. `true` lists platform images only, `false` lists the project's images only, and `any` lists both. The default is `false`. | | `--limit` | int | Sets the page size, from `1` to `200`. The default is `100`. | | `--cursor` | string | Resumes the list after the previous page. Pass the `next_cursor` of that page. | | `--all` | bool | Follows every page until the list is exhausted. | | `--name` | string | Filters the list by exact image name. | | `--sandbox` | string | Lists only the captures taken from this sandbox. | | `--region` | string | Lists only the images available in this region or a region inside it. A page can then hold fewer than `--limit` images. By default, the list covers every region. | - The request requires the `read:images` permission. ```bash curl 'https://api.daytona.com/images' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` | **Field** | **Type** | **Description** | | ------------ | -------- | ------------------------------------------------------------------------------- | | `limit` | integer | Sets the page size, clamped to `1` through `200`. The default is `100`. | | `cursor` | string | Resumes the list after the previous page. Pass the `next_cursor` of that page. | | `name` | string | Filters the list by exact image name. | | `anonymous` | boolean | Selects which images to list. `false` lists named images, and `true` lists anonymous images. The default is `false`. | | `sandbox_id` | string | Lists only the captures taken from this sandbox. | | `platform` | string | Selects platform images, which Daytona publishes for every project. `true` lists platform images only, `false` lists the project's images only, and `any` lists both. The default is `false`. | - The request requires the `read:images` permission. Each image has the following fields. The SDKs return `region_id` as `region`, `region_ids` as `available_in` (`availableIn` in TypeScript), and `class` as `sandbox_class` (`sandboxClass` in TypeScript). | **Field** | **Description** | | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | Image ID (`img_...`), used by the get, promote, convert, build-logs-url, and delete endpoints; returned as `id` when the image is created | | `name` | The name sandboxes reference through `image` | | `status` | `pending`, `building`, `ready`, or `failed` | | `error` | Build failure reason; `null` unless `status` is `failed` | | `source` | The build source as submitted: a registry reference, a named image, or a Dockerfile context; `null` for captured images | | `origin` | How the image was created, such as `registry`, `dockerfile`, or `capture` | | `class` | Sandbox class the image supports, such as `linux` or `macos` | | `anonymous` | `true` when the image has no name | | `retention` | `permanent` for a named image, `idle` for an anonymous image | | `expires_at` | When an anonymous image is deleted unless a sandbox create restarts its idle window; `null` for a permanent image | | `region_id` | Home region the image was built, pulled, or captured in | | `region_ids` | Regions that hold a copy of the image right now; the home region is listed only while its own copy is there. Empty until the build finishes and after every copy is evicted | | `platform` | `true` for a platform image that Daytona publishes for every project | | `default` | `true` for the image that a sandbox create without an image boots | | `deprecated` | `true` for a deprecated platform image, which is not listed and cannot be used by name; its ID still resolves | | `bytes` | Size of the converted image in bytes; `null` until the build completes | | `layer_count` | Number of layers in the converted image | | `disk_mib` | Disk size in MiB of a macOS sandbox created from the image without `disk_mib`, and the smallest disk such a create accepts; set for images captured from a macOS sandbox, `null` otherwise | | `format_version` | Storage format of the image: `1` for images registered by the migration from Daytona v0, `2` for the current format | | `format_outdated` | `true` when `format_version` is below the current format; [convert](#convert-images) the image before use outside Linux sandboxes | | `imported_from` | Source platform and resource ID of an image imported by the [migration from Daytona v0](/docs/migrate-from-v0), as `{"platform": "v0", "id": "..."}`; absent for an image created on Daytona v2 | | `created_at` | Creation timestamp | | `updated_at` | Timestamp of the last change | | `cursor` | Token to resume the list immediately after this row; returned by list only | #### Iterate over all images [#iterate-over-all-images] Iterate over every image in the project without handling page cursors. The iterator requests the next page when the current page is exhausted. ```python from daytona import Daytona daytona = Daytona() for image in daytona.v2.images.iter(): print(image.name, image.status) ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() for await (const image of daytona.v2.images.iter()) { console.log(image.name, image.status) } ``` ```bash # Follow every page until the server returns no cursor daytona image list --all ``` ```bash curl 'https://api.daytona.com/images?cursor={next_cursor}' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ### Get an image [#get-an-image] Get an image by its ID or name. The response carries the image fields described under [list images](#list-images), including its status and failure reason. ```python from daytona import Daytona daytona = Daytona() image = daytona.v2.images.get("{imageId}") print(image.name, image.status) ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const image = await daytona.v2.images.get('{imageId}') console.log(image.name, image.status) ``` ```bash daytona image get {imageId} ``` ```bash curl 'https://api.daytona.com/images/{imageId}' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ### Delete images [#delete-images] Delete an image. Deletion fails while a sandbox created from the image is not deleted. A captured image also cannot be deleted while another capture, sandbox, or snapshot still uses its files. ```python from daytona import Daytona daytona = Daytona() daytona.v2.images.delete("{imageId}") ``` - The request requires the `delete:images` permission. - `images.delete` takes the image ID, `img_...`, or the image name. ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() await daytona.v2.images.delete('{imageId}') ``` - The request requires the `delete:images` permission. - `images.delete` takes the image ID, `img_...`, or the image name. ```bash daytona image delete {imageId} ``` - The request requires the `delete:images` permission. - The command takes the image ID or the name. - The command asks for confirmation, and a non-interactive shell requires `--yes`. ```bash curl 'https://api.daytona.com/images/{imageId}' \ --request DELETE \ --header 'Authorization: Bearer YOUR_API_KEY' ``` - The request requires the `delete:images` permission. - The call takes the image ID or the name. ### Build logs [#build-logs] Read the output of an image build. Following the log streams output while the build runs and ends when it finishes. Stopping the reader does not stop the build. ```python from daytona import Daytona from daytona.v2 import ImageBuilder daytona = Daytona() image = daytona.v2.images.build( ImageBuilder.from_dockerfile("FROM python:3.12-slim\nRUN pip install requests"), name="my-awesome-image", ) daytona.v2.images.follow_build_logs(image.id, on_logs=lambda chunk: print(chunk, end="")) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | ------------------------------------------------------- | | `on_logs` | Callable | Receives the build output as text. Without `on_event`, it also receives one line per state change and per `gap`, `unavailable`, `source_changed`, or `error` event, prefixed with the event type, such as `[build logs: state]`. This parameter is required. | | `on_event` | Callable | Receives every stream event, including state changes. With `on_event`, these events no longer reach `on_logs`. | | `timeout` | float | Bounds the follow in seconds. When the timeout expires, the call raises `BuildLogInterruptedError` instead of returning. The `cursor` of the error resumes the follow. By default, there is no deadline. | The response has the following fields: | **Field** | **Description** | | --------- | --------------- | | `status` | The image status when the follow ended. | | `reason` | The reason is `terminal`, `deadline`, `not_applicable`, `resource_deleted`, or `unknown`. | | `output_complete` | The value is `true` when all build output was delivered. | | `cursor` | Resumes the follow after the last output. Pass this value in a later call. | ```typescript import { Daytona } from '@daytona/sdk' import { ImageBuilder } from '@daytona/sdk/v2' const daytona = new Daytona() const image = await daytona.v2.images.build( ImageBuilder.fromDockerfile('FROM python:3.12-slim\nRUN pip install requests'), { name: 'my-awesome-image' }, ) await daytona.v2.images.followBuildLogs(image.id, { onLogs: (chunk) => { process.stdout.write(chunk) } }) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | ---------------------------------------------------------------------------------------------- | | `onLogs` | function | Receives the build output as text. Without `onEvent`, it also receives one line per state change and per `gap`, `unavailable`, `source_changed`, or `error` event, prefixed with the event type, such as `[build logs: state]`. This parameter is required. | | `onEvent` | function | Receives every stream event, including state changes. With `onEvent`, these events no longer reach `onLogs`. | | `timeoutSeconds` | number | Bounds the follow in seconds. When the timeout expires, the call throws `BuildLogInterruptedError` instead of returning. The `cursor` of the error resumes the follow. By default, there is no deadline. | The response has the following fields: | **Field** | **Description** | | --------- | --------------- | | `status` | The image status when the follow ended. | | `reason` | The reason is `terminal`, `deadline`, `not_applicable`, `resource_deleted`, or `unknown`. | | `outputComplete` | The value is `true` when all build output was delivered. | | `cursor` | Resumes the follow after the last output. Pass this value in a later call. | ```bash # Stream output until the build finishes daytona image logs {imageId} --follow ``` | **Flag** | **Type** | **Description** | | ----------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- | | `--follow` | bool | Streams output until the build finishes. The command stops after `--timeout` and exits with an error, but the build keeps running. Without `--follow`, the command prints the log of a finished build, or the build state while the build runs. | | `--timeout` | string | Sets how long `--follow` runs before it stops. The default is `10m`. | ```bash BUILD_LOGS_URL=$(curl 'https://api.daytona.com/images/{imageId}/build-logs-url' \ --header 'Authorization: Bearer YOUR_API_KEY' | jq -r '.url') # Stream output until the build finishes curl --no-buffer "$BUILD_LOGS_URL?follow=true&format=sse" \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Accept: text/event-stream' ``` The stream has the following events: | **Event** | **Description** | | --------- | --------------- | | `state` | Carries the build `status`, the failure `error`, and `deadline_at`, the time by which the build must finish. | | `log` | Carries build output in `data_base64` as base64-encoded bytes, with the `start_offset` and `next_offset` of the bytes. | | `gap` | Reports output that is no longer stored, with the `requested_offset`, the `first_available_offset`, the `dropped_bytes`, and the `reason`. | | `unavailable` | Reports that the build output cannot be read right now, with the `reason`. The stream keeps retrying the source every 2 seconds. When the build has ended and the output stays unreadable, the stream ends with `done`, where `output_complete` is `false`. | | `source_changed` | Ends the stream when the log source changed, with the `reason`. | | `error` | Ends the stream with the `error` detail, its `code`, and whether the request is `retryable`. | | `done` | Ends the stream with the final `status`, the `reason`, `output_complete`, and the `cursor` that resumes the stream. | The stream sends the comment line `: heartbeat` every 10 seconds to keep the connection open. It is not an event. ### Build status [#build-status] Check an image build's progress. An image moves from pending to building and ends as ready or failed, with a failure reason when it fails. ```python from daytona import Daytona daytona = Daytona() image = daytona.v2.images.get("{imageId}") print(image.id, image.status, image.error) ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const image = await daytona.v2.images.get('{imageId}') console.log(image.id, image.status, image.error) ``` ```bash # Returns on ready or failed, or after timeout_ms curl 'https://api.daytona.com/images/{imageId}?wait=ready&timeout_ms=60000' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` The response has the following fields: | **Field** | **Description** | | --------- | --------------- | | `status` | The image status is `pending`, `building`, `ready`, or `failed`. | | `error` | Carries the failure detail. | ## Permissions [#permissions] Images are scoped to a project. Access is governed by three permissions, which you can grant to an [organization role](/docs/organizations#roles) or an [API key](/docs/api-keys). Creating a sandbox from an image requires the permission to create sandboxes, and capturing an image of a sandbox requires the `write:sandboxes` permission as well as `write:images`. The [audit logs](/docs/audit-logs) record image builds, captures, promotions, conversions, and deletes. | **Permission** | **Grants** | | ------------------- | ------------------------------------------------- | | **`read:images`** | List and get images, and read their build logs | | **`write:images`** | Build, pull, capture, promote, and convert images | | **`delete:images`** | Delete images | # Registries (/docs/registries) Registries hold the credentials Daytona uses to pull images from private container registries. A registry credential is a username and a password or token for one registry host. A project holds at most one credential per host, matched by the host in the image reference. Stored credentials apply to registry [images](/docs/images). Daytona uses the credential to import a registry image and to pull it again for a Linux or GPU sandbox. Pulls from a host without a credential, and the base image of a Dockerfile build, are anonymous and work only for public images. Windows and macOS sandboxes ignore stored credentials. Registry credentials work with [GitHub Container Registry](#github-container-registry), [Docker Hub](#docker-hub), [Google Artifact Registry](#google-artifact-registry), [Amazon ECR](#amazon-ecr), and any registry that accepts HTTP Basic authentication. Daytona encrypts the password or token at rest and never returns it. The provider kinds check the host when you store the credential, so a credential stored for the wrong host fails at that point instead of at pull time. 1. You store a credential for a registry host: the host, a kind, a username, and a password or token. The GitHub, Google, and Amazon ECR kinds validate the host, so a misconfigured credential fails at write time rather than silently at pull time. 2. Daytona takes the host from the registry reference of an image import. A sandbox create takes a registered image name or ID; when the image was imported from a registry and is not present in the target region, Daytona pulls it again from that image's registry reference. 3. If a credential is stored for that host, the pull authenticates with it; otherwise the pull is anonymous. No opt-in is needed on individual requests. 4. To rotate a credential, store the same host again with the new password. The update replaces the credential in place and takes effect on the next pull. | **Concept** | **Description** | | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | **Registry credential** | A username and a password or token, stored for one registry host in a project. | | **Host** | The registry host, with an optional port. A Docker Hub credential also applies to image references without a host. | | **Kind** | The authentication type. Basic authentication works with any registry that accepts it. The GitHub, Google, and Amazon ECR kinds also check the host. | | **Anonymous pull** | A pull from a host with no stored credential. It works only for public images. | | **Rotation** | Storing a credential for a host that already has one replaces it. The next pull uses the new credential. | ## Use cases [#use-cases] Registry credentials are used when the images that sandboxes boot from are not public. - **Private application images.** Images that a CI pipeline builds and pushes to a private registry are imported and boot in sandboxes. The import authenticates with the credential stored for the host in the image reference. No opt-in is needed on individual requests. - **Images in a cloud provider's registry.** Images stored in Amazon ECR or Google Artifact Registry are pulled with that provider's access keys, such as an AWS access key or a service account JSON key. For Amazon ECR, Daytona checks the keys with AWS STS when you store them. It refuses keys that AWS rejects or that belong to another account. - **Self-hosted registries.** Any registry that accepts HTTP Basic authentication works with a `basic` credential for its host. The host is a bare `host[:port]`, with no scheme or path. Without a stored credential, pulls from the host are anonymous and work only for public images. - **Credential rotation.** A leaked or expired token is replaced in place, and the next pull uses the new one with no change to images or sandboxes. To rotate, store a credential for the same host again with the new password or token. The API replaces the whole credential on each request, so an omitted kind resets to `basic`. - **Team access without shared tokens.** A credential is stored once per host for the whole project, and its token is encrypted and never returned. Team members import private images without holding the token. Reads return only the host, kind, username, description, creation time, and last update time. ## Container registries [#container-registries] Store a credential for a registry host. Storing a credential for a host that already has one replaces the stored credential. Daytona encrypts the password at rest, and reads return only the host, kind, username, description, creation time, and last update time. 1. Go to [Daytona Registries ↗](https://app.daytona.com/dashboard/registries) 2. Click 3. Enter the following details: - : the registry host, as `host[:port]` - : the registry kind: **Basic (username + password)**, **GitHub Container Registry**, **Google Container Registry**, or **Amazon ECR** - : the registry username - : the registry password or token - : an optional description 4. Click ```bash printf %s 'YOUR_REGISTRY_PASSWORD' | daytona registry set YOUR_REGISTRY_HOST \ --username YOUR_REGISTRY_USERNAME \ --password-stdin ``` | **Flag** | **Type** | **Description** | | --- | --- | --- | | `--username` | string | Sets the registry username. This flag is required. | | `--password-stdin` | bool | Reads the password or token from standard input. Pass exactly one of `--password-stdin` and `--password`. | | `--password` | string | Sets the password or token on the command line. The value is visible in the process list and shell history. Prefer `--password-stdin`. | | `--kind` | string | Sets the registry kind: `basic`, `ghcr`, `gcr`, `ecr`, or `ecr_role`. `ecr_role` takes the IAM role ARN as `--username` and no password. The default is `basic`, or the stored kind if the host already has a credential. | | `--description` | string | Sets the description. An empty string clears the stored description. The default is the stored description if the host already has a credential. | ```bash curl 'https://api.daytona.com/registries/YOUR_REGISTRY_HOST' \ --request PUT \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "username": "YOUR_REGISTRY_USERNAME", "password": "YOUR_REGISTRY_PASSWORD" }' ``` | **Field** | **Type** | **Description** | | --- | --- | --- | | `username` | string | Sets the registry username. This field is required. | | `password` | string | Sets the password or token, at most 64 KiB. This field is required for every kind except `ecr_role`, which ignores it. | | `kind` | string | Sets the registry kind: `basic`, `ghcr`, `gcr`, `ecr`, or `ecr_role`. For `ecr_role`, `username` is the IAM role ARN that Daytona assumes, with the organization ID as the external ID. If omitted, the kind resets to `basic`. | | `description` | string | Sets a free-form note. If omitted, the stored description is cleared. | A registry credential has the following fields: | **Field** | **Description** | | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | `host` | Bare `host[:port]`, no scheme or path. One credential per host. | | `kind` | `basic` (default), `ghcr`, `gcr`, `ecr`, or `ecr_role`. `ghcr` requires `ghcr.io`; `gcr` requires a `gcr.io`, `*.gcr.io`, or `*-docker.pkg.dev` host; `ecr` requires an `*.dkr.ecr..amazonaws.com` host; `ecr_role` requires an `*.dkr.ecr..amazonaws.com` or `public.ecr.aws` host. | | `username` | Registry username. | | `password` | Password or token, at most 64 KiB. Write-only: encrypted at rest and never returned. | | `description` | Optional free-form note. | ### Docker Hub [#docker-hub] Store a credential for Docker Hub. Daytona stores Docker Hub credentials under the host index.docker.io. The hosts docker.io, registry-1.docker.io, and registry.hub.docker.com refer to the same credential, and image references without a registry host, such as python:3.12, use it. ```bash printf %s 'YOUR_DOCKERHUB_TOKEN' | daytona registry set docker.io \ --username YOUR_DOCKERHUB_USERNAME \ --password-stdin ``` ```bash curl 'https://api.daytona.com/registries/docker.io' \ --request PUT \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "username": "YOUR_DOCKERHUB_USERNAME", "password": "YOUR_DOCKERHUB_TOKEN" }' ``` ### Google Artifact Registry [#google-artifact-registry] ```bash # The password is the service account JSON key daytona registry set us-docker.pkg.dev \ --kind gcr \ --username _json_key \ --password-stdin < service-account-key.json ``` ```bash curl 'https://api.daytona.com/registries/us-docker.pkg.dev' \ --request PUT \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "kind": "gcr", "username": "_json_key", "password": "YOUR_SERVICE_ACCOUNT_JSON_KEY" }' ``` ### GitHub Container Registry [#github-container-registry] ```bash printf %s 'YOUR_GITHUB_PAT' | daytona registry set ghcr.io \ --kind ghcr \ --username YOUR_GITHUB_USERNAME \ --password-stdin ``` ```bash curl 'https://api.daytona.com/registries/ghcr.io' \ --request PUT \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "kind": "ghcr", "username": "YOUR_GITHUB_USERNAME", "password": "YOUR_GITHUB_PAT" }' ``` ### Amazon ECR [#amazon-ecr] Store AWS access keys for an Amazon ECR registry. Daytona checks the keys with AWS STS on store and refuses keys that AWS rejects or that belong to an account other than the host's. A failed check leaves any existing credential for the host unchanged. ```bash printf %s 'YOUR_AWS_SECRET_ACCESS_KEY' | daytona registry set AWS_ACCOUNT_ID.dkr.ecr.AWS_REGION.amazonaws.com \ --kind ecr \ --username YOUR_AWS_ACCESS_KEY_ID \ --password-stdin ``` ```bash curl 'https://api.daytona.com/registries/AWS_ACCOUNT_ID.dkr.ecr.AWS_REGION.amazonaws.com' \ --request PUT \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "kind": "ecr", "username": "YOUR_AWS_ACCESS_KEY_ID", "password": "YOUR_AWS_SECRET_ACCESS_KEY" }' ``` ## Use private registry images [#use-private-registry-images] Import a private image into the project, then create sandboxes from it by name. The import authenticates with the credential stored for the host in the image reference. A Linux or GPU sandbox create takes a registered [image](/docs/images) name or ID, which must be ready first. ```python from daytona import Daytona daytona = Daytona() # The pull authenticates with the credential stored for ghcr.io image = daytona.v2.images.pull("ghcr.io/acme/private-runtime:latest", name="private-runtime") # The pull returns once it is queued; each wait returns after 30 seconds at most while image.status not in ("ready", "failed"): image = daytona.v2.images.get(image.id, wait="ready") if image.status == "failed": raise RuntimeError(image.error) sandbox = daytona.v2.create("private-runtime") ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() // The pull authenticates with the credential stored for ghcr.io let image = await daytona.v2.images.pull('ghcr.io/acme/private-runtime:latest', { name: 'private-runtime' }) // The pull returns once it is queued; each wait returns after 30 seconds at most while (image.status !== 'ready' && image.status !== 'failed') { image = await daytona.v2.images.get(image.id, { wait: 'ready' }) } if (image.status === 'failed') throw new Error(image.error ?? 'image build failed') const sandbox = await daytona.v2.create('private-runtime') ``` ```bash # The import authenticates with the credential stored for ghcr.io daytona image create private-runtime --ref ghcr.io/acme/private-runtime:latest daytona sandbox create --image private-runtime ``` - The requests require the `write:images` and `write:sandboxes` permissions. - `daytona image create` waits until the image is ready, for up to `--timeout`. - The default `--timeout` is `10m`. ```bash # The import authenticates with the credential stored for ghcr.io curl 'https://api.daytona.com/images' \ --request POST \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "name": "private-runtime", "source": { "type": "registry", "ref": "ghcr.io/acme/private-runtime:latest" } }' # Returns on ready or failed, or after timeout_ms; repeat while status is pending or building curl 'https://api.daytona.com/images/{imageId}?wait=ready&timeout_ms=60000' \ --header 'Authorization: Bearer YOUR_API_KEY' curl 'https://api.daytona.com/sandboxes' \ --request POST \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "image": "private-runtime" }' ``` - The requests require the `write:images` and `write:sandboxes` permissions. - `POST /images` returns once the pull is queued. - `{imageId}` is the `id` field of the `POST /images` response. - `timeout_ms` defaults to 30 seconds and is at most 60 seconds. ## Operations [#operations] ### List registries [#list-registries] ```bash daytona registry list ``` ```bash curl 'https://api.daytona.com/registries' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ### Get a registry [#get-a-registry] ```bash daytona registry get ghcr.io ``` ```bash curl 'https://api.daytona.com/registries/ghcr.io' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ### Delete a registry [#delete-a-registry] Delete the credential for a registry host. Later pulls from that host are anonymous. ```bash daytona registry delete ghcr.io ``` - The request requires the `delete:registries` permission. - The command asks for confirmation, and a non-interactive shell requires `--yes`. ```bash curl 'https://api.daytona.com/registries/ghcr.io' \ --request DELETE \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ## Permissions [#permissions] Registry credentials are scoped to a project. Access is governed by three permissions, which you can grant to an [organization role](/docs/organizations#roles) or an [API key](/docs/api-keys). The [audit logs](/docs/audit-logs) record credential stores, updates, and deletes. | **Permission** | **Grants** | | ----------------------- | ------------------------------------- | | **`read:registries`** | List and get registry credentials | | **`write:registries`** | Store and update registry credentials | | **`delete:registries`** | Delete registry credentials | # Volumes (/docs/volumes) A volume is persistent, project-scoped storage that a sandbox mounts as a directory. Data on a volume stays when the sandbox is deleted, and a sandbox created later can attach the same volume and read it. A sandbox attaches up to 8 volumes, and several sandboxes can attach the same volume at once. Daytona has two volume types. A disk volume is mounted as a local ext4 filesystem: the sandbox reads and writes a private copy of the volume at local disk speed, and Daytona commits its changes back to the volume in the background. A bucket volume is an S3 bucket mounted live inside the sandbox: every read and write goes to the bucket. Daytona creates and owns the bucket of a managed bucket volume, and an external bucket volume mounts a bucket you own with credentials stored as [secrets](/docs/secrets). Volumes are attached when a sandbox is created and stay attached until the sandbox is deleted. Linux sandboxes attach disk and bucket volumes, macOS sandboxes attach disk volumes, and Windows and GPU sandboxes do not attach volumes. | **Concept** | **Description** | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | **Disk volume** | A tree of files stored by Daytona and mounted as ext4. Each sandbox writes a private copy that is committed back. | | **Bucket volume** | An S3 bucket, or a key prefix in one, mounted live. Reads and writes go straight to the bucket. | | **Managed bucket** | A bucket volume whose bucket Daytona creates and deletes. | | **External bucket** | A bucket volume on a bucket you own, on AWS S3 or an S3-compatible service, accessed with keys stored as project secrets. | | **Mount** | The attachment of a volume to a sandbox at an absolute path, optionally limited to a subpath and, for bucket volumes, read-only. | | **Commit** | The background upload of a sandbox's changes on a disk volume. Other sandboxes see committed changes the next time they attach or pull. | | **Name** | Unique in the project. 1 to 128 ASCII letters, digits, periods, underscores, and hyphens, not starting with a period or a reserved prefix. | ## Use cases [#use-cases] Volumes are used when data must outlive a sandbox or be shared between sandboxes. - **Results that outlive the sandbox.** A sandbox writes its output to a volume, and the data stays after the sandbox is deleted. Deleting the sandbox runs a final commit of its disk volume changes. A sandbox created later attaches the same volume and reads the results once that commit is published, which can be seconds to minutes after the first sandbox reports deleted. Check that the results are present before the next sandbox depends on them. - **Shared datasets and model weights.** A dataset or a set of weights is written to a volume once, and every sandbox that needs it attaches the volume instead of downloading it again. Several sandboxes can attach the same volume at once. On a bucket volume, every sandbox that has the bucket mounted sees new changes. On a disk volume, give each writing sandbox its own files: a file that several sandboxes write keeps one sandbox's version. - **Caches across runs.** Package, build, and model caches on a volume carry over to the next sandbox, so it skips the downloads and builds the previous one already did. A new sandbox starts from the latest published commit of a disk volume. The sandbox reads and writes its cache in a private copy of the volume: the first read of a file fetches it from storage, and later reads and all writes run at local disk speed. - **Data in your own bucket.** An external bucket volume mounts a bucket you already use. Sandbox code reads and writes it as files, and the access keys never enter the sandbox. Deleting the volume leaves the bucket and its objects in place. - **Read-only inputs.** A bucket volume mounted read-only gives untrusted code access to input data that it cannot change or delete. Daytona enforces the read-only mount outside the sandbox, so even a process running as root cannot write to it. Only bucket volumes support read-only mounts. ## Create volumes [#create-volumes] Create a disk volume. A volume is ready as soon as the create returns, and its data starts empty. The size sets the capacity of the private copy each sandbox writes to, not a limit on the data the volume stores in total. ```python from daytona import Daytona daytona = Daytona() volume = daytona.v2.volumes.create(name="training-data", size_gib=200) print(volume.id, volume.status) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | ---------------------------------------------------------------------------------------------------------------- | | `name` | str | Sets the volume name. This parameter is required. The name must be unique in the project. | | `size_gib` | int | Sets the capacity of each sandbox's copy of a disk volume, from `1` to `1000` GiB. The default is `100`. | | `type` | str | Sets the volume type: `disk` or `bucket`. The default is `disk`. | - The request requires the `write:volumes` permission. - Disk volumes must be enabled for the organization. ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const volume = await daytona.v2.volumes.create({ name: 'training-data', sizeGib: 200 }) console.log(volume.id, volume.status) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | ---------------------------------------------------------------------------------------------------------------- | | `name` | string | Sets the volume name. This parameter is required. The name must be unique in the project. | | `sizeGib` | number | Sets the capacity of each sandbox's copy of a disk volume, from `1` to `1000` GiB. The default is `100`. | | `type` | string | Sets the volume type: `disk` or `bucket`. The default is `disk`. | - The request requires the `write:volumes` permission. - Disk volumes must be enabled for the organization. ```bash daytona volume create training-data --size-gib 200 ``` | **Flag** | **Type** | **Description** | | ------------- | -------- | --------------------------------------------------------------------------------------------------- | | `--size-gib` | int32 | Sets the capacity of each sandbox's copy of a disk volume, in GiB, from 1 to 1000. Defaults to 100. | | `--type` | string | Sets the volume type: `disk` or `bucket`. Defaults to `disk`. | - The request requires the `write:volumes` permission. - Disk volumes must be enabled for the organization. ```bash curl 'https://api.daytona.com/volumes' \ --request POST \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "name": "training-data", "type": "disk", "size_gib": 200 }' ``` | **Field** | **Type** | **Description** | | ---------- | --------- | ------------------------------------------------------------------------------------------------------------------------------- | | `name` | string | Sets the volume name, unique in the project. This field is required. A name that is taken returns `409 Conflict`. A name that starts with `sbx_`, `vol_`, `fn_`, `snap-`, `build-`, `refs`, `by-digest`, `prj-`, or `glb-` returns `400 Bad Request`. | | `type` | string | Sets the volume type: `disk` or `bucket`. Defaults to `disk`. | | `size_gib` | integer | Sets the capacity of each sandbox's copy of a disk volume, from 1 to 1000 GiB. Defaults to 100. A bucket volume returns `400 Bad Request`. | - The request requires the `write:volumes` permission. - Disk volumes must be enabled for the organization. ### Managed bucket volumes [#managed-bucket-volumes] Create a bucket volume without bucket settings to have Daytona create a new, empty bucket for it. Daytona owns the bucket: deleting the volume deletes the bucket and every object in it. Traffic to a bucket volume is billed per uploaded GiB, downloaded GiB, and 1,000 requests; see [billing](/docs/billing). ```python from daytona import Daytona daytona = Daytona() volume = daytona.v2.volumes.create(name="shared-outputs", type="bucket") print(volume.id, volume.status) ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const volume = await daytona.v2.volumes.create({ name: 'shared-outputs', type: 'bucket' }) console.log(volume.id, volume.status) ``` ```bash daytona volume create shared-outputs --type bucket ``` ```bash curl 'https://api.daytona.com/volumes' \ --request POST \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "name": "shared-outputs", "type": "bucket" }' ``` ### External bucket volumes [#external-bucket-volumes] Create a bucket volume on a bucket you own by passing its settings. Daytona stores only the settings: it does not create the bucket, and deleting the volume leaves the bucket and its objects in place. The bucket can be on AWS S3 or on an S3-compatible service. The SDKs do not create external bucket volumes. The access key and secret key are read from two project [secrets](/docs/secrets). The keys are used outside the sandbox: sandbox code reads and writes the bucket through Daytona and never receives the keys. ```bash daytona volume create corp-data --type bucket --bucket corp-data --bucket-region us-east-1 \ --prefix datasets/ --access-key-secret AWS_KEY --secret-key-secret AWS_SECRET ``` | **Flag** | **Type** | **Description** | | --------------------- | -------- | ------------------------------------------------------------------------------------------------------------------ | | `--bucket` | string | Sets the bucket name. This flag is required for an external bucket volume; without it, Daytona creates a managed bucket. | | `--bucket-region` | string | Sets the S3 region of the bucket, not a Daytona region. Defaults to the default bucket region of the deployment. | | `--endpoint` | string | Sets the endpoint of an S3-compatible service as an `http://` or `https://` URL. Omit it for AWS S3. | | `--prefix` | string | Limits the volume to keys under this prefix. | | `--path-style` | bool | Sends requests with path-style addressing instead of virtual-hosted addressing. | | `--access-key-secret` | string | Sets the name of the project secret that holds the access key. This flag is required. | | `--secret-key-secret` | string | Sets the name of the project secret that holds the secret key. This flag is required. | The rules for each value are the same as for the matching API field. - The request requires the `write:volumes` and `read:secrets` permissions. - Two project secrets must hold the access key and the secret key, each with allowed domains that include the host that requests to the bucket are signed for. ```bash curl 'https://api.daytona.com/volumes' \ --request POST \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "name": "corp-data", "type": "bucket", "bucket": { "name": "corp-data", "region": "us-east-1", "prefix": "datasets/", "credentials": { "access_key_secret": "AWS_KEY", "secret_key_secret": "AWS_SECRET" } } }' ``` | **Field** | **Type** | **Description** | | -------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `bucket.name` | string | Sets the bucket name: 3 to 63 characters of `a-z`, `0-9`, `.`, and `-`, starting and ending with a letter or digit. This field is required. | | `bucket.region` | string | Sets the bucket region: 1 to 64 characters of `a-z`, `0-9`, and `-`. Defaults to the default bucket region of the deployment. | | `bucket.endpoint` | string | Sets the endpoint of an S3-compatible service as an `http://` or `https://` URL with a public host. Omit it for AWS S3. | | `bucket.prefix` | string | Limits the volume to keys under this prefix. A trailing `/` is added. The prefix is a relative path with no empty or `..` segments, up to 511 characters. | | `bucket.path_style` | boolean | Sends requests with path-style addressing instead of virtual-hosted addressing. Defaults to `false`. | | `bucket.credentials.access_key_secret` | string | Sets the name of the project secret that holds the access key. This field is required. | | `bucket.credentials.secret_key_secret` | string | Sets the name of the project secret that holds the secret key. This field is required. | The host that each secret's allowed domains must include depends on the endpoint and the addressing style: | **Endpoint** | **Path style** | **Host** | | ------------ | -------------- | --------------------------------------- | | Omitted | `false` | `.s3..amazonaws.com` | | Omitted | `true` | `s3..amazonaws.com` | | Set | `false` | `.` | | Set | `true` | `` | - The request requires the `write:volumes` and `read:secrets` permissions. - Two project secrets must hold the access key and the secret key, each with allowed domains that include the host that requests to the bucket are signed for. ## Attach volumes [#attach-volumes] Attach volumes to a sandbox by listing them when the sandbox is created. Each mount names a volume by name or ID and an absolute path inside the sandbox. A mount can be limited to a subpath: a directory of a disk volume, or a key prefix under a bucket volume's own prefix. A mount never reaches outside the volume. Volumes cannot be attached to or detached from a running sandbox. To change the volumes of a sandbox, create a new sandbox with the volumes it needs. The examples attach two disk volumes, `training-data` and `home-dirs`, and the external bucket volume `corp-data`. Create them first, as described in [Create volumes](#create-volumes) and [External bucket volumes](#external-bucket-volumes). ```python from daytona import Daytona from daytona.v2 import VolumeMount daytona = Daytona() sandbox = daytona.v2.create( volumes=[ VolumeMount(volume_id="training-data", mount_path="/mnt/data"), VolumeMount(volume_id="home-dirs", mount_path="/home/alice", subpath="users/alice"), VolumeMount(volume_id="corp-data", mount_path="/mnt/corp", read_only=True), ], ) ``` | **Parameter** | **Type** | **Description** | | ------------------------ | --------------------- | ------------------------------------------------------------------------------------------------------------------- | | `volumes` | Sequence\[VolumeMount\] | Sets the volumes to attach. At most 8. | | `VolumeMount.volume_id` | str | Sets the volume by name or by `vol_` ID. Each volume can be attached once per sandbox. This parameter is required. | | `VolumeMount.mount_path` | str | Sets the absolute path of the mount, with no `..`. Repeated and trailing slashes are ignored, and each mount needs a different path. `/` and paths at or under `/bin`, `/boot`, `/dev`, `/etc`, `/lib`, `/lib32`, `/lib64`, `/mnt/scratch`, `/overlay`, `/proc`, `/sbin`, `/sys`, and `/usr` are reserved. This parameter is required. | | `VolumeMount.subpath` | str | Mounts only this relative path of the volume, with no empty or `..` segments. | | `VolumeMount.read_only` | bool | Mounts the volume without write access. Supported only for bucket volumes. | - The request requires the `write:sandboxes` permission. - Each volume must exist in the project and have the `ready` status. - A macOS sandbox attaches only disk volumes, read-write, and a macOS sandbox with volumes cannot be persistent. - A sandbox with bucket volumes must be created in a region whose runners mount bucket volumes. - A sandbox with volumes cannot be created from an image that is not yet available in the sandbox's region. - Create the sandbox without volumes, or retry once the image is available. - `create_macos` takes the same `volumes` list to attach disk volumes to a macOS sandbox. ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create({ volumes: [ { volumeId: 'training-data', mountPath: '/mnt/data' }, { volumeId: 'home-dirs', mountPath: '/home/alice', subpath: 'users/alice' }, { volumeId: 'corp-data', mountPath: '/mnt/corp', readOnly: true }, ], }) ``` | **Parameter** | **Type** | **Description** | | ----------------------- | -------------- | ---------------------------------------------------------------------------------------------------- | | `volumes` | VolumeMount\[\] | Sets the volumes to attach. At most 8. | | `volumes[].volumeId` | string | Sets the volume by name or by `vol_` ID. Each volume can be attached once per sandbox. This field is required. | | `volumes[].mountPath` | string | Sets the absolute path of the mount, with no `..`. Repeated and trailing slashes are ignored, and each mount needs a different path. `/` and paths at or under `/bin`, `/boot`, `/dev`, `/etc`, `/lib`, `/lib32`, `/lib64`, `/mnt/scratch`, `/overlay`, `/proc`, `/sbin`, `/sys`, and `/usr` are reserved. This field is required. | | `volumes[].subpath` | string | Mounts only this relative path of the volume, with no empty or `..` segments. | | `volumes[].readOnly` | boolean | Mounts the volume without write access. Supported only for bucket volumes. | - The request requires the `write:sandboxes` permission. - Each volume must exist in the project and have the `ready` status. - A macOS sandbox attaches only disk volumes, read-write, and a macOS sandbox with volumes cannot be persistent. - A sandbox with bucket volumes must be created in a region whose runners mount bucket volumes. - A sandbox with volumes cannot be created from an image that is not yet available in the sandbox's region. - Create the sandbox without volumes, or retry once the image is available. - `createMacos` takes the same `volumes` list to attach disk volumes to a macOS sandbox. ```bash daytona sandbox create \ --volume training-data:/mnt/data \ --volume home-dirs:/home/alice:users/alice \ --volume corp-data:/mnt/corp:ro ``` | **Flag** | **Type** | **Description** | | ---------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `--volume` | stringArray | Attaches a volume as `VOLUME:MOUNT_PATH[:SUBPATH][:ro]`. `VOLUME` is a name or `vol_` ID, and a trailing `:ro`, in any case, mounts it read-only. Paths cannot contain `:`, and a third field of `ro` is read as the read-only marker, not as a subpath. Repeat the flag for each mount, at most 8, with each volume once. | - The request requires the `write:sandboxes` permission. - Each volume must exist in the project and have the `ready` status. - A macOS sandbox attaches only disk volumes, read-write, and a macOS sandbox with volumes cannot be persistent. - A sandbox with bucket volumes must be created in a region whose runners mount bucket volumes. - A sandbox with volumes cannot be created from an image that is not yet available in the sandbox's region. - Create the sandbox without volumes, or retry once the image is available. - `daytona sandbox create-macos` takes the same `--volume` flag, without `:ro`, to attach disk volumes to a macOS sandbox. ```bash curl 'https://api.daytona.com/sandboxes' \ --request POST \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "volumes": [ { "volume": "training-data", "mount_path": "/mnt/data" }, { "volume": "home-dirs", "mount_path": "/home/alice", "subpath": "users/alice" }, { "volume": "corp-data", "mount_path": "/mnt/corp", "read_only": true } ] }' ``` | **Field** | **Type** | **Description** | | ---------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `volumes` | object\[\] | Sets the volumes to attach. At most 8. A longer list returns `400 Bad Request`. | | `volumes[].volume` | string | Sets the volume by name or by `vol_` ID. Each volume can be attached once per sandbox. This field is required. | | `volumes[].mount_path` | string | Sets the absolute path of the mount, with no `..`. Repeated and trailing slashes are ignored, and each mount needs a different path. `/` and paths at or under `/bin`, `/boot`, `/dev`, `/etc`, `/lib`, `/lib32`, `/lib64`, `/mnt/scratch`, `/overlay`, `/proc`, `/sbin`, `/sys`, and `/usr` are reserved. This field is required. | | `volumes[].subpath` | string | Mounts only this relative path of the volume, with no empty or `..` segments. | | `volumes[].read_only` | boolean | Mounts the volume without write access. Supported only for bucket volumes; a disk volume returns `400 Bad Request`. | - The request requires the `write:sandboxes` permission. - Each volume must exist in the project and have the `ready` status. - A macOS sandbox attaches only disk volumes, read-write, and a macOS sandbox with volumes cannot be persistent. - A sandbox with bucket volumes must be created in a region whose runners mount bucket volumes. - A sandbox with volumes cannot be created from an image that is not yet available in the sandbox's region. - Create the sandbox without volumes, or retry once the image is available. - `POST /sandboxes/macos` takes the same `volumes` list to attach disk volumes to a macOS sandbox. ## Disk volume data [#disk-volume-data] A sandbox reads and writes a disk volume as a local ext4 filesystem. When the sandbox starts, Daytona builds a private copy of the volume's latest published commit for that sandbox. The first read of a file fetches it from storage, and later reads and all writes go to the private copy at local disk speed. Daytona commits a sandbox's changes to the volume in the background. A commit runs at most every 5 seconds, and only once the sandbox has stopped writing to the volume for about 1 second. A sandbox that never pauses writing for 1 second does not commit until it is stopped or deleted. Run the sync command in the sandbox before you depend on a recent write being in the next commit. Stopping or deleting the sandbox runs a final commit. The sandbox can report stopped or deleted before that commit is published, which takes from a few seconds to several minutes for large changes. Until then, a sandbox that attaches the volume sees the earlier contents, and the stopped sandbox cannot be started again. Check that the files you need are present before a new sandbox depends on them. A sandbox sees other sandboxes' commits when it attaches the volume, which happens when the sandbox is created or started. Changes another sandbox commits while this sandbox runs are not visible to it until it [pulls the volume](#pull-volume-changes). A commit stores file contents, directories, symbolic links, hard links, permission modes, and modification times. It does not store file owners, named pipes, sockets, device nodes, or extended attributes: files come back owned by root. Holes in sparse files are stored as zeros, so a sparse file takes its full size in each sandbox's copy and in the volume's reported size. When several sandboxes change the same volume, each commit merges its changes into the latest contents of the volume instead of replacing them: | **Change** | **Result** | | ----------------------------------------------- | -------------------------------------------------------------------------- | | A path changed by only one sandbox | That sandbox's version is kept. | | A path changed by two sandboxes | The version with the newer modification time is kept. | | A path modified by one sandbox, deleted by another | The modified version is kept. | | A path that is a file in one sandbox and a directory in another | The directory is kept. | The merge compares file modification times set by the sandboxes. A tool that preserves old modification times, such as an archive extraction, can lose to an older edit made in another sandbox. The version that loses is discarded and cannot be recovered. Each path is merged on its own. Files that must stay consistent with each other, such as a database and its write-ahead log or a Git object store, can end up combined from different sandboxes. Write them from one sandbox only, and have other sandboxes read them or write their own files. A commit is the point where a disk volume write becomes durable. If the host fails before a commit, the changes since the last commit can be lost. ## Pull volume changes [#pull-volume-changes] Pull a disk volume to bring the changes other sandboxes committed into a running sandbox, without restarting it. If the volume has new commits, the pull first commits this sandbox's own changes, merges them as a background commit does, and then applies the merged contents to the sandbox's copy. If the volume has no new commits, the pull returns without committing local changes. A pull can outlast its wait: a pending result means the pull has no result yet, and repeating the request with the same request ID returns its result. Bucket volumes need no pull, because every read goes to the bucket. A pull stages incoming changes in a `.rlp-sync` directory at the root of the mount. Daytona does not commit this directory, and a pull fails when the name is taken by a file or by a directory Daytona did not create. ```python from daytona import Daytona from daytona.v2 import VolumeMount daytona = Daytona() sandbox = daytona.v2.create(volumes=[VolumeMount(volume_id="training-data", mount_path="/mnt/data")]) volume = daytona.v2.volumes.get("training-data") result = sandbox.volumes.pull(volume.id, request_id="refresh-42", timeout=10) while result.status == "pending": result = sandbox.volumes.pull(volume.id, request_id="refresh-42", timeout=10) print(result.status, result.manifest_id) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `volume_id` | str | Sets the `vol_` ID of a volume attached to the sandbox. This is the first positional argument. | | `request_id` | str | Sets the identity of the pull: 1 to 128 ASCII letters, digits, underscores, and hyphens. Reuse it to retry the pull or read its result. This parameter is required. | | `timeout` | float | Sets how many seconds the server waits for the pull, from `0` to `30`. `0` submits the pull, or returns the last result of a known request ID without waiting or retrying it. A wait above `0` retries a pull that is pending, unavailable (`503`), or refused by the rate limit. The default is `30`. | The result has the following fields: | **Field** | **Description** | | ------------- | --------------------------------------------------------------------------------------------------------------- | | `status` | `pulled` when the sandbox received new changes, `unchanged` when the volume had none, `pending` when the pull has no result within the wait, or `unknown` when the SDK does not recognize the status the server returns. | | `raw_status` | The status exactly as the server returns it. Read it when `status` is `unknown`. | | `manifest_id` | The version of the volume that the pull applied or found. `None` while the pull is pending. | - The request requires the `write:sandboxes` permission. - Pull supports disk volumes attached to Linux sandboxes. - A sandbox starts at most one new pull of a volume per second. ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create({ volumes: [{ volumeId: 'training-data', mountPath: '/mnt/data' }] }) const volume = await daytona.v2.volumes.get('training-data') let result = await sandbox.volumes.pull(volume.id, { requestId: 'refresh-42', timeoutSeconds: 10 }) while (result.status === 'pending') { result = await sandbox.volumes.pull(volume.id, { requestId: 'refresh-42', timeoutSeconds: 10 }) } console.log(result.status, result.manifestId) ``` | **Parameter** | **Type** | **Description** | | ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `volumeId` | string | Sets the `vol_` ID of a volume attached to the sandbox. This is the first positional argument. | | `options.requestId` | string | Sets the identity of the pull: 1 to 128 ASCII letters, digits, underscores, and hyphens. Reuse it to retry the pull or read its result. This field is required. | | `options.timeoutSeconds` | number | Sets how many seconds the server waits for the pull, from `0` to `30`. `0` submits the pull, or returns the last result of a known request ID without waiting or retrying it. A wait above `0` retries a pull that is pending, unavailable (`503`), or refused by the rate limit. The default is `30`. | The result has the following fields: | **Field** | **Description** | | ------------ | --------------------------------------------------------------------------------------------------------------- | | `status` | `pulled` when the sandbox received new changes, `unchanged` when the volume had none, `pending` when the pull has no result within the wait, or `unknown` when the SDK does not recognize the status the server returns. | | `rawStatus` | The status exactly as the server returns it. Read it when `status` is `unknown`. | | `manifestId` | The version of the volume that the pull applied or found. `undefined` while the pull is pending. | - The request requires the `write:sandboxes` permission. - Pull supports disk volumes attached to Linux sandboxes. - A sandbox starts at most one new pull of a volume per second. ```bash curl '{toolboxProxyUrl}/{sandboxId}/volumes/{volumeId}/pull' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "requestId": "refresh-42", "waitMs": 10000 }' ``` | **Field** | **Type** | **Description** | | ----------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `volumeId` | path | Sets the `vol_` ID of a volume attached to the sandbox. | | `requestId` | string | Sets the identity of the pull: 1 to 128 ASCII letters, digits, underscores, and hyphens. Reuse it to retry the pull or read its result. This field is required. | | `waitMs` | integer | Sets how many milliseconds the server waits for the pull, from `0` to `30000`. `0` submits the pull, or returns the last result of a known request ID without waiting or retrying it. A wait above `0` retries a pull that is pending, unavailable (`503`), or refused by the rate limit. The default is `30000`. | The response has the following fields: | **Field** | **Description** | | ------------ | --------------------------------------------------------------------------------------------------------------- | | `status` | `pulled` when the sandbox received new changes, `unchanged` when the volume had none, or `pending` when the pull has no result within the wait. | | `manifestId` | The version of the volume that the pull applied or found. `null` while the pull is pending. | - The request requires the `write:sandboxes` permission. - `{toolboxProxyUrl}` is the `toolbox_proxy_url` field of the [sandbox](/docs/sandboxes#get-a-sandbox). - Pull supports disk volumes attached to Linux sandboxes. - A sandbox starts at most one new pull of a volume per second. ## Bucket volume data [#bucket-volume-data] A sandbox mounts a bucket volume with [Mountpoint for Amazon S3](https://github.com/awslabs/mountpoint-s3). Each read and write is a request to the bucket, and closing a written file returns only after the object is stored, or with an error if the upload fails. Changes are visible to every sandbox that has the bucket mounted and to any other client of the bucket. Files on a bucket volume are S3 objects, so file system operations that S3 does not support are not available. A file is written sequentially from the start, an existing file can be replaced but not modified in place, and symbolic links, hard links, and permission changes are not supported. Every file operation is a round trip to the bucket, so workloads with many small files run slower than on a disk volume. A read-only mount is enforced outside the sandbox. A process in the sandbox, including one running as root, cannot write to or delete from a read-only mount. ## Operations [#operations] ### List volumes [#list-volumes] List the volumes of the project, newest first. The list returns one page at a time, and each page holds the cursor of the next one. Volumes that are being deleted are listed with the deleting status, and deleted volumes are not listed. ```python from daytona import Daytona daytona = Daytona() cursor = None while True: page = daytona.v2.volumes.list(limit=50, cursor=cursor) for v in page.items: print(v.id, v.name, v.type, v.status) cursor = page.next_cursor # None on the last page if cursor is None: break ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | ------------------------------------------------------------------------- | | `limit` | int | Sets the page size, from `1` to `200`. The default is `100`. | | `cursor` | str | Resumes the list after the previous page. Pass the `next_cursor` of that page. Omit it for the first page. | ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() let cursor: string | undefined do { const page = await daytona.v2.volumes.list({ limit: 50, cursor }) for (const v of page.items) { console.log(v.id, v.name, v.type, v.status) } cursor = page.nextCursor // undefined on the last page } while (cursor) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | ------------------------------------------------------------------------- | | `limit` | number | Sets the page size, from `1` to `200`. The default is `100`. | | `cursor` | string | Resumes the list after the previous page. Pass the `nextCursor` of that page. Omit it for the first page. | ```bash daytona volume list --limit 50 daytona volume list --all ``` | **Flag** | **Type** | **Description** | | ---------- | -------- | ------------------------------------------------------------------- | | `--limit` | int | Sets the page size, from 1 to 200. Defaults to 100. | | `--cursor` | string | Starts from the cursor of a previous page. | | `--all` | bool | Reads every page. | ```bash curl 'https://api.daytona.com/volumes?limit=50' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` | **Parameter** | **Type** | **Description** | | ------------- | --------- | ----------------------------------------------------------------------- | | `limit` | integer | Sets the page size, from `1` to `200`. A value outside the range is set to the nearest bound. The default is `100`. | | `cursor` | string | Resumes the list after the previous page. Pass the `next_cursor` of that page. Omit it for the first page. | The response has the following fields: | **Field** | **Description** | | ------------- | --------------------------------------------------------- | | `volumes` | Lists the volumes of the page, newest first. | | `next_cursor` | The cursor of the next page, or `null` on the last page. | #### Iterate over all volumes [#iterate-over-all-volumes] Iterate over every volume of the project without handling page cursors. The iterator fetches the next page when the current one is exhausted and stops when the server returns no cursor. ```python from daytona import Daytona daytona = Daytona() for v in daytona.v2.volumes.iter(): print(v.id, v.name, v.type, v.status) ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() for await (const v of daytona.v2.volumes.iter()) { console.log(v.id, v.name, v.type, v.status) } ``` ### Get a volume [#get-a-volume] Get a volume by name or ID. The response holds the volume's type, status, size, and options. For a disk volume, it also reports the size of the volume's files at the last commit and when that size was observed; both are empty until the first commit. Bucket volume options include the bucket settings and the names of the credential secrets, never the keys. ```python from daytona import Daytona daytona = Daytona() volume = daytona.v2.volumes.get("training-data") print(volume.type, volume.status, volume.size_gib, volume.used_bytes, volume.used_bytes_at) # Create the disk volume if it does not exist volume = daytona.v2.volumes.get("scratch-cache", create=True) ``` | **Parameter** | **Type** | **Description** | | -------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- | | `name_or_id` | str | Sets the volume by name or by `vol_` ID. This is the first positional argument. | | `create` | bool | Creates a disk volume with this name and the default size when none exists. If another caller creates it first, the call fails; repeat it. Ignored with `id_only`. Defaults to `False`. | | `id_only` | bool | Resolves the value only as an ID, without falling back to a name. Defaults to `False`. | ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const volume = await daytona.v2.volumes.get('training-data') console.log(volume.type, volume.status, volume.sizeGib, volume.usedBytes, volume.usedBytesAt) // Create the disk volume if it does not exist const cache = await daytona.v2.volumes.get('scratch-cache', { create: true }) ``` | **Parameter** | **Type** | **Description** | | ---------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- | | `nameOrId` | string | Sets the volume by name or by `vol_` ID. This is the first positional argument. | | `options.create` | boolean | Creates a disk volume with this name and the default size when none exists. If another caller creates it first, the call fails; repeat it. Ignored with `idOnly`. Defaults to `false`. | | `options.idOnly` | boolean | Resolves the value only as an ID, without falling back to a name. Defaults to `false`. | ```bash daytona volume get training-data ``` ```bash curl 'https://api.daytona.com/volumes/training-data' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` | **Parameter** | **Type** | **Description** | | ------------- | --------- | ------------------------------------------------------------------------------------------------ | | `id_only` | boolean | Resolves the path value only as an ID, without falling back to a name. The default is `false`. | ### Delete volumes [#delete-volumes] Delete a volume by name or ID. Deletion runs in the background: the volume moves to the deleting status and then to deleted. Deleting a disk volume deletes its data, and deleting a managed bucket volume deletes the bucket and every object in it. Deleting an external bucket volume leaves the bucket and its objects in place. ```python from daytona import Daytona daytona = Daytona() daytona.v2.volumes.delete("training-data") ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | ---------------------------------------------------------------------------------------- | | `name_or_id` | str | Sets the volume by name or by `vol_` ID. This is the first positional argument. | | `id_only` | bool | Resolves the value only as an ID, without falling back to a name. The default is `False`. | - The request requires the `delete:volumes` permission. - Every sandbox that attached the volume must be deleted, and its final commit must be complete. The volume is released shortly after the sandbox reports deleted. ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() await daytona.v2.volumes.delete('training-data') ``` | **Parameter** | **Type** | **Description** | | ---------------- | -------- | ---------------------------------------------------------------------------------------- | | `nameOrId` | string | Sets the volume by name or by `vol_` ID. This is the first positional argument. | | `options.idOnly` | boolean | Resolves the value only as an ID, without falling back to a name. Defaults to `false`. | - The request requires the `delete:volumes` permission. - Every sandbox that attached the volume must be deleted, and its final commit must be complete. The volume is released shortly after the sandbox reports deleted. ```bash daytona volume delete training-data --yes ``` | **Flag** | **Type** | **Description** | | -------- | -------- | --------------------------------------- | | `--yes` | bool | Skips the confirmation prompt. | - The request requires the `delete:volumes` permission. - Every sandbox that attached the volume must be deleted, and its final commit must be complete. The volume is released shortly after the sandbox reports deleted. ```bash curl 'https://api.daytona.com/volumes/training-data' \ --request DELETE \ --header 'Authorization: Bearer YOUR_API_KEY' ``` - The request requires the `delete:volumes` permission. - Every sandbox that attached the volume must be deleted, and its final commit must be complete. The volume is released shortly after the sandbox reports deleted. ## Permissions [#permissions] Volumes are scoped to a project. A volume in one project cannot be attached to a sandbox in another. Access is governed by three permissions, which you can grant to an [organization role](/docs/organizations) or an [API key](/docs/api-keys). Creating an external bucket volume also requires permission to read secrets, because the volume references project secrets. Pulling a volume runs through the toolbox of the sandbox and requires the sandbox write permission. The [audit logs](/docs/audit-logs) record volume creates and deletes. | **Permission** | **Grants** | | -------------------- | ------------------------------------------------- | | **`read:volumes`** | List and get volumes | | **`write:volumes`** | Create volumes | | **`delete:volumes`** | Delete volumes | # Regions (/docs/regions) Every Daytona sandbox runs in a **region**: a geographic or logical grouping of compute infrastructure. When creating a sandbox, you can target a specific region, and Daytona schedules the workload on available capacity within that region. A create request that names no region uses the project's default region, then the organization's, then Earth. Regions form one flat list, and each region names the broader regions it is inside, from Earth down to its direct parent. Earth covers every other region and means anywhere: a sandbox created in Earth can land in any geography. A broader region lets Daytona place the sandbox anywhere inside it; a narrower region keeps the sandbox closer to you. Each region has its own price multiplier, applied to the base price of the sandbox's resources, and a region without one is billed at Earth's. The hierarchy does not set the price: a narrower region can cost less than its parent, so check the multiplier of the region you name. A listed region describes topology, not capacity: a create request can still fail for lack of capacity or matching hardware. ## Shared regions [#shared-regions] Regions managed by Daytona and available to all organizations: ```python from daytona import Daytona daytona = Daytona() # Create a sandbox anywhere in Earth sandbox = daytona.v2.create(region="earth") ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() // Create a sandbox anywhere in Earth const sandbox = await daytona.v2.create({ region: 'earth' }) ``` ```bash # Create a sandbox anywhere in Earth daytona sandbox create --region earth ``` ```bash # Create a sandbox anywhere in Earth curl 'https://api.daytona.com/sandboxes' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "region_id": "earth" }' ``` ## Operations [#operations] ### List regions [#list-regions] List regions. The list contains every region you can name in a create request, as one flat list in tree order: Earth first, then each region followed by the regions inside it. Each region names its parent regions, so a client can rebuild the hierarchy from the list. Regions that cannot be used are left out. A region that covers others stays listed when none of them accepts automatic placement, marked as unavailable, and cannot be named in a create request. ```bash # Regions available to the current project, as NAME, ID, PRICE MULTIPLIER, and AVAILABLE columns daytona region list # Include parent regions daytona region list --output json ``` ```bash # Regions available to the current project curl 'https://api.daytona.com/regions' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` The response contains one entry per region and the ID of your default region, with the following fields: | **Field** | **Description** | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | Region ID, the value a create request names in `region_id`. | | `name` | Display name. | | `parent_region_ids` | IDs of the broader regions this region is inside, outermost first, so the last one is its direct parent. Empty for `earth`. Every ID is listed in the same response. | | `available` | Whether a create request can name this region. For a region that covers others, whether at least one of them accepts automatic placement. Not a health or capacity signal. | | `api_base_url` | The API base URL of the region, when it publishes its own. | | `default_region_id` | ID of your default region: the project's default region, else the organization's, else the platform's. `null` when that region is not listed. | ### List region price multipliers [#list-region-price-multipliers] List region price multipliers. The list contains the price multiplier of every region a create request can name, Earth first, then every other region ordered by ID. A sandbox's CPU, memory, GPU, and storage are billed at the base price times the multiplier of the region its create request named. A create request that names no region is billed at its default region's multiplier, or at Earth's when no default is set. For the other pricing dimensions, see [billing](/docs/billing#pricing-dimensions). ```bash # The PRICE MULTIPLIER column of the region list daytona region list ``` ```bash curl 'https://api.daytona.com/orgs/ORGANIZATION_ID/billing/region-multipliers' \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' ``` The response contains one entry per region, Earth first and the rest ordered by ID, with the following fields: | **Field** | **Description** | | ------------ | --------------------------------------------------------------------- | | `region_id` | The region ID accepted by create requests. | | `multiplier` | The multiplier applied to base CPU, memory, GPU, and storage prices. | # Network Limits (/docs/network-limits) Network limits control outbound internet access from sandboxes. Each sandbox runs behind a firewall that restricts which external IP addresses and domains it can reach, preventing untrusted code from exfiltrating data or contacting arbitrary hosts. Egress is open by default. You can restrict access per sandbox with a network policy: a default-deny allow list of IPv4 CIDR ranges and domains. Set the policy when you [create a sandbox](#create-sandboxes-with-network-restrictions), then [update](#update-network-policy) or [reset](#reset-network-policy) it while the sandbox exists. Enabling unrestricted network access may pose security risks when executing untrusted code. It is recommended to allow only the network addresses or domains you need, or block all network access. Test network connectivity before starting critical development work. ## Use cases [#use-cases] Network limits are used when code in a sandbox must not reach arbitrary hosts. - **Untrusted or generated code.** Code from users or agents runs with no outbound access, so it cannot send data out of the sandbox. With blocking on and empty allow lists, DNS resolves no names either. Network policies apply to Linux and macOS sandboxes, and Windows and GPU sandboxes do not accept them. - **Agents that call known services.** A domain allow list lets an agent reach the model provider and the APIs it needs, and blocks every other host. The sandbox resolves only the names on the list. A domain allow list turns blocking on by itself. - **Dependency installs.** The domains of package registries, such as PyPI or npm, are allowed, and the rest of the internet is blocked. A wildcard entry covers the subdomains of a registry host but not the host itself, which needs its own entry. Each entry is a hostname without a protocol, path, port, or query string. - **Sensitive data.** A sandbox that processes private files or datasets reaches only the hosts on its allow list. DNS is filtered as well, so a name that is not on the list does not resolve. Egress is open by default, so the sandbox gets its policy when it is [created](#create-sandboxes-with-network-restrictions). - **Restrict after setup.** A sandbox installs its dependencies with open egress, and its policy is updated to block all egress before untrusted code runs. The update applies in the background, and the policy status reads applied once the sandbox enforces it. An update works while the sandbox is running, paused, or stopped. ## Create sandboxes with network restrictions [#create-sandboxes-with-network-restrictions] Create a sandbox with a network policy. With blocking turned on, the sandbox can reach only the domains and IPv4 ranges on its allow lists. A domain allow list turns blocking on by itself, while an IPv4 allow list restricts egress only when blocking is on. When a policy has both lists, web traffic on ports 80 and 443 needs a listed domain, even to a listed IPv4 range. Network policies apply to [Linux sandboxes](/docs/linux-sandboxes) and [macOS sandboxes](/docs/macos-sandboxes); the examples below create Linux sandboxes, and a macOS create takes the same policy. [Windows](/docs/windows-sandboxes) and [GPU](/docs/gpu-sandboxes) sandboxes do not accept them. ```python from daytona import Daytona daytona = Daytona() # Allow access to specific domains; everything else is denied sandbox = daytona.v2.create( network_policy={"block_all": True, "allow_domains": ["example.com", "*.daytona.io"]}, ) ``` | **Parameter** | **Type** | **Description** | | ---------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | `network_policy` | NetworkPolicyInput | Sets the outbound network policy. It accepts only the `block_all`, `allow_cidrs`, and `allow_domains` keys. Any other key raises `BadRequestError` before the request is sent. If `allow_domains` is set, an omitted `block_all` becomes `True`. Setting `block_all=False` with `allow_domains` is rejected. | ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() // Allow access to specific domains; everything else is denied const sandbox = await daytona.v2.create({ networkPolicy: { blockAll: true, allowDomains: ['example.com', '*.daytona.io'] }, }) ``` | **Parameter** | **Type** | **Description** | | --------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `networkPolicy` | NetworkPolicyInput | Sets the outbound network policy. It accepts only the `blockAll`, `allowCidrs`, and `allowDomains` fields. Any other field throws `BadRequestError` before the request is sent. If `allowDomains` is set, an omitted `blockAll` becomes `true`. Setting `blockAll: false` with `allowDomains` is rejected. | ```bash # Allow access to specific domains; everything else is denied daytona sandbox create \ --block-all \ --allow-domain example.com \ --allow-domain '*.daytona.io' ``` | **Flag** | **Type** | **Description** | | ---------------- | -------- | -------------------------------- | | `--allow-domain` | string | Adds one entry to the domain allow list. It implies `--block-all`. Repeat the flag for more entries. | | `--allow-cidr` | string | Adds one entry to the network allow list. Repeat the flag for more entries. It requires `--block-all` or `--allow-domain`. | - The request requires the `write:sandboxes` permission. - Only `daytona sandbox create` and `daytona sandbox create-macos` accept the network flags. ```bash # Allow access to specific domains; everything else is denied curl 'https://api.daytona.com/sandboxes' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "network_policy": { "block_all": true, "allow_domains": ["example.com", "*.daytona.io"] } }' ``` - The request requires the `write:sandboxes` permission. - The API rejects `"block_all": false` together with `allow_domains`. - Without `allow_domains`, `block_all` defaults to `false`. - The `allow_cidrs` and `allow_domains` lists hold at most 128 entries combined. ### Block all egress [#block-all-egress] Create a sandbox with no outbound access, for code that needs no network. With blocking on and empty allow lists, the sandbox reaches no external address and DNS resolves no names. ```python from daytona import Daytona daytona = Daytona() # Deny all outbound traffic sandbox = daytona.v2.create(network_policy={"block_all": True}) ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() // Deny all outbound traffic const sandbox = await daytona.v2.create({ networkPolicy: { blockAll: true }, }) ``` ```bash # Deny all outbound traffic daytona sandbox create --block-all ``` ```bash # Deny all outbound traffic curl 'https://api.daytona.com/sandboxes' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "network_policy": { "block_all": true } }' ``` ### Allow IPv4 ranges [#allow-ipv4-ranges] Create a sandbox that reaches only specific IPv4 addresses and ranges, in the [network allow list format](#network-allow-list-format). An IPv4 allow list applies only when blocking is on, so turn it on explicitly. Without a domain allow list, DNS resolves a name only to its IPv4 addresses inside the allowed ranges, and a name with no address in them resolves to no address. IPv6 lookups are refused. ```python from daytona import Daytona daytona = Daytona() # Allow one address and one subnet; everything else is denied sandbox = daytona.v2.create( network_policy={"block_all": True, "allow_cidrs": ["1.1.1.1/32", "208.80.152.0/22"]}, ) ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() // Allow one address and one subnet; everything else is denied const sandbox = await daytona.v2.create({ networkPolicy: { blockAll: true, allowCidrs: ['1.1.1.1/32', '208.80.152.0/22'] }, }) ``` ```bash # Allow one address and one subnet; everything else is denied daytona sandbox create \ --block-all \ --allow-cidr 1.1.1.1/32 \ --allow-cidr 208.80.152.0/22 ``` ```bash # Allow one address and one subnet; everything else is denied curl 'https://api.daytona.com/sandboxes' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "network_policy": { "block_all": true, "allow_cidrs": ["1.1.1.1/32", "208.80.152.0/22"] } }' ``` ### Allow domains [#allow-domains] Create a sandbox that reaches only specific hosts by name, in the [domain allow list format](#domain-allow-list-format). The sandbox resolves and connects to the listed domains; a wildcard covers every subdomain of a host but not the host itself. The domain list turns blocking on by itself. ```python from daytona import Daytona daytona = Daytona() # Allow a host and all of its subdomains; everything else is denied sandbox = daytona.v2.create( network_policy={"allow_domains": ["pythonhosted.org", "*.pythonhosted.org", "pypi.org"]}, ) ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() // Allow a host and all of its subdomains; everything else is denied const sandbox = await daytona.v2.create({ networkPolicy: { allowDomains: ['pythonhosted.org', '*.pythonhosted.org', 'pypi.org'] }, }) ``` ```bash # Allow a host and all of its subdomains; everything else is denied daytona sandbox create \ --allow-domain pythonhosted.org \ --allow-domain '*.pythonhosted.org' \ --allow-domain pypi.org ``` ```bash # Allow a host and all of its subdomains; everything else is denied curl 'https://api.daytona.com/sandboxes' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "network_policy": { "allow_domains": ["pythonhosted.org", "*.pythonhosted.org", "pypi.org"] } }' ``` ## Network allow list format [#network-allow-list-format] Allow outbound traffic to specific IPv4 addresses and ranges. Each entry on the network allow list is a single address or a CIDR block, and the sandbox can reach it on any port. With a domain allow list, ports 80 and 443 still need a listed hostname, whatever address the sandbox connects to: a web request that names a host not on the domain allow list is refused with `403`, even when its address is on the network allow list, and UDP port 443 is blocked. The list takes effect only when blocking is on. The SDKs, the API, and the CLI reject a non-empty list unless blocking or a domain allow list is set; the API returns `400`. | **Rule** | **Description** | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **IPv4 only** | IPv6 addresses and IPv6 CIDR blocks are not supported. | | **CIDR format** | Use standard CIDR notation (`A.B.C.D/N`) with a prefix length up to `32`. The address must be the network address of the range: a CIDR with host bits set, such as `208.80.154.0/22`, returns `400`. A bare address such as `208.80.154.232` is also accepted. | | **No private ranges** | Loopback (`127.0.0.0/8`), private (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`), link-local (`169.254.0.0/16`), carrier-grade NAT (`100.64.0.0/10`), multicast (`224.0.0.0/4`), benchmarking (`198.18.0.0/15`), `0.0.0.0/8`, `192.0.0.0/24`, `240.0.0.0/4` (which includes the broadcast address), and `168.63.129.16` return `400`, as does any range that overlaps them, such as `0.0.0.0/0`. | | **No nested entries** | Do not list an entry that lies inside another entry, such as `208.80.154.232/32` together with `208.80.152.0/22`; the policy fails to apply, and at creation the sandbox does not start. List the larger range only. | | **Max 128 entries** | `allow_cidrs` and `allow_domains` combined. | | **Whitespace is ignored** | Entries are trimmed. An empty entry returns `400`. | | **Example** | **Value** | | --------------------- | -------------------------------------------- | | **Single IP** | `208.80.154.232/32` (Wikipedia) | | **Subnet** | `208.80.152.0/22` (Wikimedia) | | **Multiple networks** | `["1.1.1.1/32", "208.80.152.0/22"]` | ## Domain allow list format [#domain-allow-list-format] Allow outbound traffic to specific hosts by name. Each entry is a hostname, or a wildcard covering a hostname's subdomains. A domain allow list turns blocking on by itself. DNS is filtered as well: the sandbox resolves only the names on the list and refuses all others. A policy with only IPv4 entries resolves a name only to its addresses inside the allowed ranges, and a policy with empty lists resolves no names at all. The domain allow list also covers web traffic to the addresses on the network allow list. On ports 80 and 443, the sandbox reaches a host only by a name on the domain allow list, and connecting to a listed IPv4 address does not change which host it reaches. | **Rule** | **Description** | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Domains only** | Use hostnames such as `example.com` or `api.openai.com`. Do not include protocols, paths, ports, or query strings. | | **Wildcards supported** | Prefix a domain with `*.` to allow its subdomains, for example `*.daytona.io`. A wildcard does not match the bare domain; add `daytona.io` as its own entry. The wildcard needs at least two labels after `*.`, so `*.com` returns `400`. | | **ASCII only** | Write internationalized names in punycode, for example `xn--bcher-kva.de` for `bücher.de`. A name with other characters returns `400`. | | **Case-insensitive** | Entries are lowercased before matching. | | **Whitespace is ignored** | Entries are trimmed. An empty entry returns `400`. | | **Empty list** | An empty `allow_domains` list also turns blocking on. | | **Max 128 entries** | `allow_cidrs` and `allow_domains` combined. | | **Example** | **Value** | | -------------------- | --------------------------------------------------- | | **Single domain** | `example.com` | | **Wildcard domain** | `*.daytona.io` | | **Multiple domains** | `["example.com", "*.daytona.io", "api.openai.com"]` | ## Operations [#operations] The SDKs and the API get, update, and reset the network policy of an existing sandbox. The CLI sets a policy only when it creates a sandbox. ### Get network policy [#get-network-policy] Get the network policy of a sandbox. The response carries two policies: the desired policy, which is the last one you set, and the applied policy, which the sandbox currently enforces. A change is applied in the background, so the two differ until the sandbox catches up. The response also carries an ETag that identifies the current revision; an update or reset must send it back. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() policy = sandbox.get_network_policy() print(policy.status, policy.desired, policy.applied, policy.etag) ``` The response has the following fields: | **Field** | **Description** | | --- | --- | | `desired` | The last policy set on the sandbox, or `None`. | | `desired_revision` | The revision of `desired`. | | `applied` | The policy the sandbox enforces, or `None`. | | `applied_revision` | The revision of `applied`, or `None`. | | `applied_start_id` | The sandbox start that `applied` was applied to, or `None`. | | `etag` | The revision token to send back when you update or reset the policy. | | `http_status` | The HTTP status code of the response. | | `status` | The status is `pending`, `applied`, or `failed`. It is `None` for a sandbox that never had a policy. | | `error` | Explains why the policy is not applied yet, or why it failed when `status` is `failed`. | ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() const policy = await sandbox.getNetworkPolicy() console.log(policy.status, policy.desired, policy.applied, policy.etag) ``` The response has the following fields: | **Field** | **Description** | | --- | --- | | `desired` | The last policy set on the sandbox, or `undefined`. | | `desiredRevision` | The revision of `desired`. | | `applied` | The policy the sandbox enforces, or `undefined`. | | `appliedRevision` | The revision of `applied`, or `undefined`. | | `appliedStartId` | The sandbox start that `applied` was applied to, or `undefined`. | | `etag` | The revision token to send back when you update or reset the policy. | | `httpStatus` | The HTTP status code of the response. | | `status` | The status is `pending`, `applied`, or `failed`. It is `undefined` for a sandbox that never had a policy. | | `error` | Explains why the policy is not applied yet, or why it failed when `status` is `failed`. | ```bash # --include prints the ETag response header curl 'https://api.daytona.com/sandboxes/{sandboxId}/network-policy' \ --include \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ```json { "desired": { "version": 2, "block_all": true, "allow_cidrs": [], "allow_domains": ["example.com"] }, "desired_revision": 1, "applied": { "version": 2, "block_all": true, "allow_cidrs": [], "allow_domains": ["example.com"] }, "applied_revision": 1, "applied_start_id": "5b145d87c75d565a5e2b23a91fc1e325/60ad3ddc7c17b94141852ad65fdd10e5", "status": "applied", "error": null } ``` The response has the following fields: | **Field** | **Description** | | --- | --- | | `ETag` | Holds the revision as `"np-"`, for example `"np-1"`. This value is a response header. | | `status` | The status is `pending`, `applied`, or `failed`. For a sandbox that never had a policy, `status` is `null` and the revision is `0`. | ### Update network policy [#update-network-policy] Replace the whole network policy of an existing sandbox, with the same fields and rules as at [create time](#create-sandboxes-with-network-restrictions). The sandbox must be running, paused, or stopped. The new policy is stored at once and applied in the background; get the policy to see when it takes effect. Every update sends the ETag of the revision it replaces. If the policy changed since, the update is rejected instead of overwriting it; get the policy and retry with the new ETag. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() current = sandbox.get_network_policy() updated = sandbox.update_network_policy( network_policy={"block_all": True, "allow_domains": ["pypi.org", "files.pythonhosted.org"]}, if_match=current.etag, ) print(updated.status) # pending until the sandbox applies it ``` | **Parameter** | **Type** | **Description** | | ---------------- | -------------------- | ------------------------------------------------------------------------------- | | `network_policy` | NetworkPolicyInput | Sets the full new policy, with the `block_all`, `allow_cidrs`, and `allow_domains` keys. This parameter is required. | | `if_match` | str | Passes the `etag` from the last `get_network_policy()` or update. This parameter is required. | ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() const current = await sandbox.getNetworkPolicy() const updated = await sandbox.updateNetworkPolicy( { blockAll: true, allowDomains: ['pypi.org', 'files.pythonhosted.org'] }, { ifMatch: current.etag }, ) console.log(updated.status) // pending until the sandbox applies it ``` | **Parameter** | **Type** | **Description** | | ----------------- | -------------------- | ---------------------------------------------------------------------------------- | | `networkPolicy` | NetworkPolicyInput | Sets the full new policy, with the `blockAll`, `allowCidrs`, and `allowDomains` fields. This parameter is required. | | `options.ifMatch` | string | Passes the `etag` from the last `getNetworkPolicy()` or update. This parameter is required. | ```bash curl 'https://api.daytona.com/sandboxes/{sandboxId}/network-policy' \ --request PUT \ --header 'Content-Type: application/json' \ --header 'If-Match: {etag}' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "block_all": true, "allow_domains": ["pypi.org", "files.pythonhosted.org"] }' ``` | **Header** | **Description** | | ----------- | --------------------------------------------------------------------------------------------------------------------- | | `If-Match` | Passes the `ETag` from the last get or update, with its quotes, for example `"np-1"`. This header is required. | The response has the following fields: | **Field** | **Description** | | ------------- | -------------------------------------------------------------------------------------- | | Body | The updated network policy, in the same shape as a get. | | `ETag` header | The revision tag of the updated policy. Send it as `If-Match` on the next update. | ### Reset network policy [#reset-network-policy] Reset the network policy of a sandbox to open egress. A reset removes the restrictions but keeps the revision history, so it follows the same ETag rules as an update. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() current = sandbox.get_network_policy() sandbox.reset_network_policy(if_match=current.etag) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | -------------------------------------------------------------------- | | `if_match` | str | Passes the `etag` from the last `get_network_policy()` or update. This parameter is required. | ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() const current = await sandbox.getNetworkPolicy() await sandbox.resetNetworkPolicy({ ifMatch: current.etag }) ``` | **Parameter** | **Type** | **Description** | | ----------------- | -------- | ------------------------------------------------------------------- | | `options.ifMatch` | string | Passes the `etag` from the last `getNetworkPolicy()` or update. This parameter is required. | ```bash # A literal null body resets the policy to open egress curl 'https://api.daytona.com/sandboxes/{sandboxId}/network-policy' \ --request PUT \ --header 'Content-Type: application/json' \ --header 'If-Match: {etag}' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data 'null' ``` | **Header** | **Description** | | ----------- | --------------------------------------------------------------------------------------------------------------------- | | `If-Match` | Passes the `ETag` from the last get or update, with its quotes, for example `"np-2"`. This header is required. | ### Test network access [#test-network-access] Run the commands inside the sandbox. They test the allow lists only when blocking is on: a sandbox without a network policy has open egress, so both commands succeed. With blocking on, each command succeeds only when its target is on the sandbox's allow list. ```bash # Test HTTP connectivity to an allowed address; needs 208.80.152.0/22 on the network allow list curl -I http://208.80.154.232 # Test HTTP connectivity to an allowed domain; needs example.com on the domain allow list curl -I https://example.com ``` ## Permissions [#permissions] Network policies use the sandbox permissions of the project, which you can grant to an [organization role](/docs/organizations#roles) or an [API key](/docs/api-keys). The [audit logs](/docs/audit-logs) record network policy updates. | **Permission** | **Grants** | | --------------------- | ---------------------------------------------------------------------------------- | | **`read:sandboxes`** | Get the network policy of a sandbox | | **`write:sandboxes`** | Create sandboxes with network restrictions, and update or reset the network policy | # File System Operations (/docs/file-system-operations) File system operations are available through the file system module of a sandbox. Each sandbox has its own isolated filesystem, and operations run through the Daytona API, so your application manages files in a sandbox directly, without executing shell commands inside it. The file system module covers listing directories, reading file metadata, creating directories, uploading and downloading files, setting permissions, searching file contents, watching directories for changes, and moving, renaming, or deleting files. The sandbox streams uploads to disk and downloads from disk, so transfer size is bounded by sandbox storage, not sandbox memory. Most SDK methods hold file content in your application's memory; to move large files without buffering them, stream them from and to local disk with the SDK, as in [upload large files](#upload-large-files) and [download large files](#download-large-files), or use [presigned URLs](#presigned-urls) with an HTTP client. The API serves file system requests at the sandbox's toolbox proxy URL, written as `{toolboxProxyUrl}` in the examples. It is the `toolbox_proxy_url` field of the [sandbox](/docs/sandboxes#get-a-sandbox), such as `https://proxy.ash-1.us-east.daytona.app/toolbox`. Sandbox paths must be absolute, starting with a slash. The SDKs raise `BadRequestError` for a relative path before any request is sent, the CLI rejects it, and the API returns `400 INVALID_FILE_PATH`. ## Use cases [#use-cases] File system operations are used when an application moves or inspects files in a sandbox without a shell. - **Input files.** An application uploads source code, datasets, or configuration before code runs. Several files upload in one request, and a failed file does not stop the others. Missing parent directories are created, and an existing file at the destination is overwritten. - **Results and artifacts.** Generated files, reports, and build outputs are downloaded after a run. Several files download in one request, and a missing or unreadable file does not stop the others. The SDK methods hold every downloaded file in memory before they return. - **Agent file tools.** An agent lists, reads, searches, and edits files through the API as tools. The agent needs no shell commands inside the sandbox to do this. - **Large transfers.** Large files stream between local disk and the sandbox without being held in the application's memory. Uploads have no request size limit, so free sandbox disk space bounds the upload size. A failed or cancelled SDK download leaves an existing destination file unchanged. - **Direct transfers for other clients.** A presigned URL lets a browser or another service upload or download one file without an API key. A URL is valid for at most 7 days. Rotating the sandbox signing key revokes every outstanding URL within 30 seconds. ## List files and directories [#list-files-and-directories] List files and directories. By default, only entries directly inside the directory are listed. A depth option lists nested entries up to 32 levels deep; a listing over 10,000 entries fails, so request a smaller depth for large trees. Symbolic links are listed, not followed. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.fs.write_text("/home/daytona/workspace/hello.txt", "hello") # List files in a directory files = sandbox.fs.list("/home/daytona/workspace") for file in files.items: print(f"Name: {file.name}") print(f"Is directory: {file.is_dir}") print(f"Size: {file.size}") print(f"Modified: {file.modified_at}") ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() await sandbox.fs.writeText('/home/daytona/workspace/hello.txt', 'hello') // List files in a directory const files = await sandbox.fs.list('/home/daytona/workspace') files.items.forEach(file => { console.log(`Name: ${file.name}`) console.log(`Is directory: ${file.isDir}`) console.log(`Size: ${file.size}`) console.log(`Modified: ${file.modifiedAt ?? file.modTime}`) }) ``` ```bash curl '{toolboxProxyUrl}/{sandboxId}/files?path=/home/daytona/workspace' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ## Get directory or file information [#get-directory-or-file-information] Get metadata for a file or directory. The metadata describes the entry at the path itself: for a symbolic link, it describes the link, not its target. | **Field** | **Format** | | ----------------------- | -------------------------------------------------------------------------- | | **Mode** | Symbolic, such as `-rw-r--r--`; `d` first for a directory, `L` for a link. | | **Permissions** | The four-digit octal form, such as `0644`. | | **Owner** and **group** | Numeric user and group IDs as strings, such as `1000`, not names. | ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.fs.write_text("/home/daytona/workspace/data/file.txt", "hello") # Get file metadata info = sandbox.fs.stat("/home/daytona/workspace/data/file.txt") print(f"Size: {info.size} bytes") print(f"Modified: {info.modified_at}") print(f"Mode: {info.mode}") ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() await sandbox.fs.writeText('/home/daytona/workspace/data/file.txt', 'hello') // Get file metadata const info = await sandbox.fs.stat('/home/daytona/workspace/data/file.txt') console.log(`Size: ${info.size} bytes`) console.log(`Modified: ${info.modifiedAt ?? info.modTime}`) console.log(`Mode: ${info.mode}`) ``` ```bash curl '{toolboxProxyUrl}/{sandboxId}/files/info?path=/home/daytona/workspace/data/file.txt' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ```json { "name": "file.txt", "path": "/home/daytona/workspace/data/file.txt", "size": 1024, "isDir": false, "mode": "-rw-r--r--", "permissions": "0644", "owner": "1000", "group": "1000", "modifiedAt": "2026-09-13T09:41:12Z", "modTime": "2026-09-13 09:41:12 +0000 UTC" } ``` ## Create directories [#create-directories] Create a directory and any missing parents, with octal mode 755 by default. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.fs.mkdir("/home/daytona/workspace/new-dir") ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() await sandbox.fs.mkdir('/home/daytona/workspace/new-dir') ``` ```bash curl '{toolboxProxyUrl}/{sandboxId}/files/folder?path=/home/daytona/workspace/new-dir' \ --request POST \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ## Upload files [#upload-files] ### Upload a single file [#upload-a-single-file] Upload a file to a sandbox. Missing parent directories at the destination are created, and an existing file at the destination is overwritten. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() with open("local_file.txt", "rb") as f: sandbox.fs.write_bytes("/home/daytona/remote_file.txt", f.read()) ``` ```typescript import { readFile } from 'node:fs/promises' import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() await sandbox.fs.writeBytes('/home/daytona/remote_file.txt', await readFile('local_file.txt')) ``` ```bash # The sandbox side is : daytona sandbox cp local_file.txt {sandboxId}:/home/daytona/remote_file.txt ``` - The request requires the `write:sandboxes` permission. - Exactly one of the two arguments must be a sandbox path. - A sandbox destination that ends with `/` receives the file under its local name. ```bash curl '{toolboxProxyUrl}/{sandboxId}/files/upload?path=/home/daytona/remote_file.txt' \ --request POST \ --header 'Authorization: Bearer YOUR_API_KEY' \ --form 'file=@local_file.txt' ``` ### Upload multiple files [#upload-multiple-files] Upload several files in one request. Each file is written independently: missing parent directories are created, existing files are overwritten, and a file that fails does not stop the others. The result lists each file written with its byte count, and an error message for each failure. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() result = sandbox.fs.write_many({ "/home/daytona/data/file1.txt": b"Content of file 1", "/home/daytona/data/file2.txt": b"Content of file 2", }) # Partial success is reported in the result, not raised for error in result.errors: print(f"Error: {error}") ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() const result = await sandbox.fs.writeMany({ '/home/daytona/data/file1.txt': new TextEncoder().encode('Content of file 1'), '/home/daytona/data/file2.txt': new TextEncoder().encode('Content of file 2'), }) // Partial success is reported in the result, not thrown result.errors.forEach(error => console.error(`Error: ${error}`)) ``` ```bash curl '{toolboxProxyUrl}/{sandboxId}/files/bulk-upload' \ --request POST \ --header 'Authorization: Bearer YOUR_API_KEY' \ --form 'files[0].path=/home/daytona/data/file1.txt' \ --form 'files[0].file=@file1.txt' \ --form 'files[1].path=/home/daytona/data/file2.txt' \ --form 'files[1].file=@file2.txt' ``` ```json { "files": [ { "path": "/home/daytona/data/file1.txt", "bytes": 17 }, { "path": "/home/daytona/data/file2.txt", "bytes": 17 } ], "errors": [] } ``` - The request requires the `write:sandboxes` permission. - Each `files[i].path` part must come before its `files[i].file` part. ### Upload large files [#upload-large-files] Upload large files from local disk. The SDK streams the file in chunks without holding it in memory, and reports progress as it sends. The sandbox writes the upload to disk as it arrives with no request size limit, so free sandbox disk space bounds the upload size. The CLI streams the file from disk over a [presigned URL](#presigned-urls) it creates. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() def on_progress(sent: int, total: int | None) -> None: print(f"Uploaded {sent} of {total} bytes") sandbox.fs.upload_file("large_dataset.csv", "/home/daytona/workspace/dataset.csv", on_progress=on_progress) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------ | | `local_path` | str \| os.PathLike\[str\] | Sets the local file to upload. This parameter is required. | | `remote_path` | str | Sets the destination path in the sandbox. This parameter is required. | | `on_progress` | TransferProgressCallback | Reports upload progress. The callback receives the bytes sent so far and the total file size in bytes. Exceptions raised inside the callback are ignored. | | `cancel` | TransferCancelSignal | Stops the upload when the event is set. The event is a `threading.Event` or an `asyncio.Event`. Without `atomic`, a stopped upload leaves the bytes sent so far at the destination. | | `atomic` | bool | Writes through a temporary file in the destination directory, then renames the file into place. The default is `False`. | ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() await sandbox.fs.uploadFile('large_dataset.csv', '/home/daytona/workspace/dataset.csv', { onProgress: (sent, total) => console.log(`Uploaded ${sent} of ${total} bytes`), }) ``` | **Parameter** | **Type** | **Description** | | -------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------ | | `localPath` | string | Sets the local file to upload. This parameter is required. | | `remotePath` | string | Sets the destination path in the sandbox. This parameter is required. | | `options.onProgress` | TransferProgressCallback | Reports upload progress. The callback receives the bytes sent so far and the total file size in bytes. Errors thrown inside the callback are ignored. | | `options.signal` | AbortSignal | Stops the upload when the signal is aborted. Without `options.atomic`, a stopped upload leaves the bytes sent so far at the destination. | | `options.atomic` | boolean | Writes through a temporary file in the destination directory, then renames the file into place. The default is `false`. | - The request requires the `write:sandboxes` permission. - `uploadFile` works in Node.js only, not in a browser. ```bash daytona sandbox cp large_dataset.csv {sandboxId}:/home/daytona/workspace/dataset.csv ``` ```bash curl '{toolboxProxyUrl}/{sandboxId}/files/upload?path=/home/daytona/workspace/dataset.csv' \ --request POST \ --header 'Authorization: Bearer YOUR_API_KEY' \ --form 'file=@large_dataset.csv' ``` ## Download files [#download-files] ### Download a single file [#download-a-single-file] ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.fs.write_text("/home/daytona/file1.txt", "Content of file 1") content = sandbox.fs.read_bytes("/home/daytona/file1.txt") print(content.decode("utf-8")) ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() await sandbox.fs.writeText('/home/daytona/file1.txt', 'Content of file 1') const content = await sandbox.fs.readBytes('/home/daytona/file1.txt') console.log(new TextDecoder().decode(content)) ``` ```bash daytona sandbox cp {sandboxId}:/home/daytona/file1.txt file1.txt ``` - The request requires the `write:sandboxes` permission. - A local destination that ends in `/` or names a directory keeps the sandbox file name. ```bash curl '{toolboxProxyUrl}/{sandboxId}/files/download?path=/home/daytona/file1.txt' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` #### Download a text file [#download-a-text-file] Download a text file. The SDK downloads the file and decodes its content as UTF-8. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.fs.write_text("/home/daytona/file1.txt", "Content of file 1") content = sandbox.fs.read_text("/home/daytona/file1.txt") print(content) ``` - The request requires the `write:sandboxes` permission. - The file must be valid UTF-8. ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() await sandbox.fs.writeText('/home/daytona/file1.txt', 'Content of file 1') const content = await sandbox.fs.readText('/home/daytona/file1.txt') console.log(content) ``` ### Download multiple files [#download-multiple-files] Download several files in one request. Each file is read independently, so a missing or unreadable file does not stop the others; it is reported as an error for its path. The SDK methods hold every downloaded file in memory before they return. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.fs.write_many({ "/home/daytona/data/file1.txt": b"Content of file 1", "/home/daytona/data/file2.txt": b"Content of file 2", }) result = sandbox.fs.read_many(["/home/daytona/data/file1.txt", "/home/daytona/data/file2.txt"]) for path, content in result.files.items(): print(f"Downloaded {path} ({len(content)} bytes)") # Partial success is reported in the result, not raised for error in result.errors: print(f"Error downloading {error.path}: {error.message}") ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() await sandbox.fs.writeMany({ '/home/daytona/data/file1.txt': new TextEncoder().encode('Content of file 1'), '/home/daytona/data/file2.txt': new TextEncoder().encode('Content of file 2'), }) const result = await sandbox.fs.readMany(['/home/daytona/data/file1.txt', '/home/daytona/data/file2.txt']) Object.entries(result.files).forEach(([path, content]) => { console.log(`Downloaded ${path} (${content.byteLength} bytes)`) }) // Partial success is reported in the result, not thrown result.errors.forEach(error => console.error(`Error downloading ${error.path}: ${error.message}`)) ``` ```bash curl '{toolboxProxyUrl}/{sandboxId}/files/bulk-download' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "paths": [ "/home/daytona/data/file1.txt", "/home/daytona/data/file2.txt" ] }' ``` The response has the following fields: | **Field** | **Description** | | --------- | --------------- | | `file` | One part per downloaded file. The filename of the part is the requested path. | | `error` | One part per path that cannot be read, with a JSON body that holds `code`, `message`, `source`, and `path`. A path that cannot be read does not fail the request. | - The request requires the `write:sandboxes` permission. - The response is `multipart/form-data` with the fixed boundary `DAYTONA-FILE-BOUNDARY`, not JSON. ### Download large files [#download-large-files] Download large files to local disk. The SDK streams the file in chunks without holding it in memory, and reports progress as it receives. It writes to a temporary file next to the destination and renames it into place only after the whole file arrives, so a failed or cancelled download leaves an existing destination file unchanged. The CLI writes the file to disk as it arrives, over a [presigned URL](#presigned-urls) that it creates for the transfer. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.fs.write_text("/home/daytona/workspace/large-file.bin", "hello") def on_progress(received: int, total: int | None) -> None: print(f"Downloaded {received} of {total} bytes") sandbox.fs.download_file("/home/daytona/workspace/large-file.bin", "local_copy.bin", on_progress=on_progress) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------- | | `remote_path` | str | Sets the file to download from the sandbox. This parameter is required. | | `local_path` | str \| os.PathLike\[str\] | Sets the local destination. A replaced destination file keeps its permission bits. This parameter is required. The parent directory of the destination must exist. | | `on_progress` | TransferProgressCallback | Reports download progress. The callback receives the bytes received so far and the total size in bytes, or `None` when the total is unknown. | | `cancel` | TransferCancelSignal | Stops the download when the event is set. The event is a `threading.Event` or an `asyncio.Event`. | ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() await sandbox.fs.writeText('/home/daytona/workspace/large-file.bin', 'hello') await sandbox.fs.downloadFile('/home/daytona/workspace/large-file.bin', 'local_copy.bin', { onProgress: (received, total) => console.log(`Downloaded ${received} of ${total} bytes`), }) ``` | **Parameter** | **Type** | **Description** | | -------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | `remotePath` | string | Sets the file to download from the sandbox. This parameter is required. | | `localPath` | string | Sets the local destination. The parent directory of the destination must exist. A replaced destination file keeps its permission bits. This parameter is required. | | `options.onProgress` | TransferProgressCallback | Reports download progress. The callback receives the bytes received so far and the total size in bytes, or `undefined` when the total is unknown. | | `options.signal` | AbortSignal | Stops the download when the signal is aborted. | - The request requires the `write:sandboxes` permission. - `downloadFile` works in Node.js only, not in a browser. ```bash daytona sandbox cp {sandboxId}:/home/daytona/workspace/large-file.bin local_copy.bin ``` ```bash curl '{toolboxProxyUrl}/{sandboxId}/files/download?path=/home/daytona/workspace/large-file.bin' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --output local_copy.bin ``` ## Delete files [#delete-files] Delete a file or directory. A directory is deleted, with everything in it, only when the recursive option is set; otherwise it fails. A symbolic link is deleted as a link; its target is kept. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.fs.write_text("/home/daytona/workspace/file.txt", "hello") sandbox.fs.remove("/home/daytona/workspace/file.txt") ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------------------------------------------------------------------------------------------------------- | | `recursive` | bool | Deletes a directory and its contents when `True`. The default is `False`. Without this option, a directory path raises `BadRequestError`. | ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() await sandbox.fs.writeText('/home/daytona/workspace/file.txt', 'hello') await sandbox.fs.remove('/home/daytona/workspace/file.txt') ``` | **Parameter** | **Type** | **Description** | | ------------- | --------- | ----------------------------------------------------------------------------------------------------------- | | `recursive` | boolean | Deletes a directory and its contents when `true`. Without this option, a directory path throws `BadRequestError`. | ```bash curl '{toolboxProxyUrl}/{sandboxId}/files?path=/home/daytona/workspace/file.txt' \ --request DELETE \ --header 'Authorization: Bearer YOUR_API_KEY' ``` | **Field** | **Type** | **Description** | | ----------- | -------- | ------------------------------------------------------------------------------------------------- | | `recursive` | string | Deletes a directory and its contents when set to `true`. Without this field, a directory path returns `400`. | ## File permissions [#file-permissions] Change the permission mode, owner, or group of a file or directory; at least one is required. The mode is an octal string. Owner and group accept a numeric ID or a name, which the sandbox resolves from its user and group lists. Symbolic links are followed. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.fs.write_text("/home/daytona/workspace/file.txt", "hello") sandbox.fs.chmod("/home/daytona/workspace/file.txt", mode="644") ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() await sandbox.fs.writeText('/home/daytona/workspace/file.txt', 'hello') await sandbox.fs.chmod('/home/daytona/workspace/file.txt', { mode: '644' }) ``` ```bash curl '{toolboxProxyUrl}/{sandboxId}/files/permissions?path=/home/daytona/workspace/file.txt&mode=644' \ --request POST \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ## Search files by pattern [#search-files-by-pattern] Search for files by name. The search walks the directory tree without following symbolic links and matches the name of every entry against the pattern, so directories with a matching name are returned as well. Directories the sandbox cannot read are skipped without an error, and a path that does not exist returns an empty result. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.fs.write_text("/home/daytona/workspace/main.py", "print('hello')") # Recursive; the pattern is matched against file names with * and ? wildcards result = sandbox.fs.glob("/home/daytona/workspace", "*.py") for file in result.items: print(file) ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() await sandbox.fs.writeText('/home/daytona/workspace/main.py', "print('hello')") // Recursive; the pattern is matched against file names with * and ? wildcards const result = await sandbox.fs.glob('/home/daytona/workspace', '*.py') result.items.forEach(file => console.log(file)) ``` ```bash curl '{toolboxProxyUrl}/{sandboxId}/files/search?path=/home/daytona/workspace&pattern=*.py' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` Returned paths are prefixed with the path you passed. `skipped` lists up to 1000 paths below the root that the sandbox user cannot read, so their contents were not searched: ```json { "files": [ "/home/daytona/workspace/main.py", "/home/daytona/workspace/lib/util.py" ], "skipped": [] } ``` ## Find and replace text in files [#find-and-replace-text-in-files] Find text in files and replace it. Find checks each file line by line and returns the file, the line number starting at 1, and the full line for every match. Files that are not valid UTF-8 text are skipped, and a path that does not exist returns no matches. Replace takes a list of files, not directories, and rewrites each file in full with every occurrence replaced. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.fs.write_text("/home/daytona/workspace/src/app.py", "text-of-interest") sandbox.fs.write_text("/home/daytona/workspace/file1.txt", "old_text") sandbox.fs.write_text("/home/daytona/workspace/file2.txt", "old_text") # Search for text in files; the pattern is a literal substring, not a regular expression. # If a directory is given, the search is recursive. results = sandbox.fs.grep("/home/daytona/workspace/src", "text-of-interest") for match in results.items: print(f"{match.file}:{match.line}: {match.content}") # Replace every occurrence of a literal substring in each listed file result = sandbox.fs.replace(["/home/daytona/workspace/file1.txt", "/home/daytona/workspace/file2.txt"], "old_text", "new_text") # Per-file failures are reported in the result, not raised for item in result.items: if not item.success: print(f"Failed to update {item.file}: {item.error}") ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() await sandbox.fs.writeText('/home/daytona/workspace/src/app.py', 'text-of-interest') await sandbox.fs.writeText('/home/daytona/workspace/file1.txt', 'old_text') await sandbox.fs.writeText('/home/daytona/workspace/file2.txt', 'old_text') // Search for text in files; the pattern is a literal substring, not a regular expression. // If a directory is given, the search is recursive. const results = await sandbox.fs.grep('/home/daytona/workspace/src', 'text-of-interest') results.items.forEach(match => console.log(`${match.file}:${match.line}: ${match.content}`)) // Replace every occurrence of a literal substring in each listed file const result = await sandbox.fs.replace(['/home/daytona/workspace/file1.txt', '/home/daytona/workspace/file2.txt'], 'old_text', 'new_text') // Per-file failures are reported in the result, not thrown result.items .filter(item => !item.success) .forEach(item => console.error(`Failed to update ${item.file}: ${item.error}`)) ``` Find text in files: ```bash curl '{toolboxProxyUrl}/{sandboxId}/files/find?path=/home/daytona/workspace/src&pattern=text-of-interest' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` `items` holds the matches in walk order. `skipped` lists up to 1000 paths below the root that the sandbox user cannot read, so they were not searched: ```json { "items": [ { "file": "/home/daytona/workspace/src/main.py", "line": 12, "content": "print('text-of-interest')" } ], "skipped": [] } ``` Replace text in files: ```bash curl '{toolboxProxyUrl}/{sandboxId}/files/replace' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "files": [ "/home/daytona/workspace/file1.txt", "/home/daytona/workspace/file2.txt" ], "newValue": "new_text", "pattern": "old_text" }' ``` ```json [ { "file": "/home/daytona/workspace/file1.txt", "success": true }, { "file": "/home/daytona/workspace/file2.txt", "success": false, "error": "No such file or directory (os error 2)" } ] ``` ## Move or rename directory or file [#move-or-rename-directory-or-file] Move or rename a file or directory. A move never replaces or merges into an existing destination entry. Across filesystems, the sandbox copies the entry, keeping each copied entry's owner and mode, and removes the source only after the whole copy succeeds. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.fs.write_text("/home/daytona/workspace/data/file.txt", "hello") # Missing parent directories are created; an existing destination is rejected with ConflictError sandbox.fs.move("/home/daytona/workspace/data/file.txt", "/home/daytona/workspace/archive/file.txt") ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() await sandbox.fs.writeText('/home/daytona/workspace/data/file.txt', 'hello') // Missing parent directories are created; an existing destination is rejected with ConflictError await sandbox.fs.move('/home/daytona/workspace/data/file.txt', '/home/daytona/workspace/archive/file.txt') ``` ```bash curl '{toolboxProxyUrl}/{sandboxId}/files/move?source=/home/daytona/workspace/data/file.txt&destination=/home/daytona/workspace/archive/file.txt' \ --request POST \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ## Watch for file changes [#watch-for-file-changes] Watch a directory for changes. The watch streams create, write, remove, rename, and permission change events as they happen; it does not replay earlier changes. By default, only entries directly inside the directory are watched. A recursive watch also covers subdirectories, including ones created later. Event paths are relative to the watched directory. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.fs.mkdir("/home/daytona/workspace/src") handle = sandbox.fs.watch_dir( "/home/daytona/workspace/src", lambda event: print(f"{event.type}: {event.name}"), ) sandbox.fs.write_text("/home/daytona/workspace/src/new.py", "print('hello')") handle.stop() ``` | **Parameter** | **Type** | **Description** | | ------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------- | | `on_event` | Callable\[\[FilesystemEvent\], None \| Awaitable\[None\]\] | Receives each event. This is the second positional argument and is required. | | `recursive` | bool | Watches subdirectories when `True`. A recursive watch covers at most `4096` directories. A larger tree is refused when the watch starts. Directories created later beyond the limit are reported as an overflow. The default is `False`. | | `on_overflow` | Callable\[\[\], None \| Awaitable\[None\]\] | Runs when events are dropped. If events outpace delivery, the watch drops them and sends an overflow notice. | | `on_exit` | Callable\[\[Exception \| None\], None \| Awaitable\[None\]\] | Runs once when the watch ends, with `None` after `stop()` and otherwise with the error that ended the watch. Exceptions raised inside the callback are ignored. | - The request requires the `write:sandboxes` permission. - The path must be absolute and name an existing directory. ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() await sandbox.fs.mkdir('/home/daytona/workspace/src') const handle = await sandbox.fs.watchDir('/home/daytona/workspace/src', (event) => { console.log(`${event.type}: ${event.name}`) }) await sandbox.fs.writeText('/home/daytona/workspace/src/new.py', "print('hello')") await handle.stop() ``` | **Parameter** | **Type** | **Description** | | ------------- | ------------ | --------------------------------------------------------------------------------- | | `onEvent` | (event: FilesystemEvent) => void \| Promise\ | Receives each event. An async callback is awaited before the next event. This is the second argument and is required. | | `recursive` | boolean | Watches subdirectories when you pass `{ recursive: true }` as the third argument. A recursive watch covers at most `4096` directories. A larger tree is refused when the watch starts. Directories created later beyond the limit are reported as an overflow. | | `onOverflow` | () => void \| Promise\ | Runs when events are dropped. If events outpace delivery, the watch drops them and sends an overflow notice. Pass this callback in the options. | | `onExit` | (error?: Error) => void \| Promise\ | Runs once when the watch ends, with no error after `stop()` and otherwise with the error that ended the watch. Errors thrown inside the callback are ignored. Pass this callback in the options. | - The request requires the `write:sandboxes` permission. - The path must be absolute and name an existing directory. ```bash curl --no-buffer '{toolboxProxyUrl}/{sandboxId}/files/watch?path=/home/daytona/workspace/src' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ```text event: start data: {} event: fs data: {"type":"create","name":"new.py","isDir":false,"timestamp":1789121730123} event: overflow data: {"dropped":true} ``` | **Field** | **Type** | **Description** | | ----------- | --------- | --------------------------------------- | | `recursive` | boolean | Watches subdirectories when set to `true`. A recursive watch covers at most `4096` directories. A larger tree is refused when the watch starts. Directories created later beyond the limit are reported as an overflow. | - The request requires the `write:sandboxes` permission. - The path must be absolute and name an existing directory. ### Wait for the watch to end [#wait-for-the-watch-to-end] ```python import threading from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.fs.mkdir("/home/daytona/workspace/src") handle = sandbox.fs.watch_dir( "/home/daytona/workspace/src", lambda event: print(f"{event.type}: {event.name}"), ) # Nothing ends a healthy watch on its own: stop it from another thread, # or the stream ends when the sandbox stops or is deleted threading.Timer(60, handle.stop).start() # Blocks until the watch is stopped or the stream ends error = handle.wait_for_exit() if error is not None: print(f"Watch ended: {error}") ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() await sandbox.fs.mkdir('/home/daytona/workspace/src') const handle = await sandbox.fs.watchDir('/home/daytona/workspace/src', (event) => { console.log(`${event.type}: ${event.name}`) }) // Nothing ends a healthy watch on its own: stop it from elsewhere, // or the stream ends when the sandbox stops or is deleted setTimeout(() => handle.stop(), 60_000) // Resolves when the watch is stopped or the stream ends const error = await handle.waitForExit() if (error) console.error('Watch ended:', error.message) ``` ## Presigned URLs [#presigned-urls] Create presigned URLs. A presigned URL downloads or uploads one sandbox file without an API key until it expires, so any HTTP client can transfer the file. Daytona signs each URL with the sandbox's signing key; rotating it invalidates all its outstanding URLs within 30 seconds. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() # Download link, valid for 1 hour (default) download_url = sandbox.fs.presigned_download_url("/home/daytona/workspace/report.pdf") # Upload link, valid for 1 hour (default) upload_url = sandbox.fs.presigned_upload_url("/home/daytona/workspace/incoming/data.bin") # Invalidate every outstanding presigned URL for this sandbox; old URLs can still work for up to 30 seconds sandbox.rotate_signing_key() ``` | **Parameter** | **Type** | **Description** | | -------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------- | | `expires_in_seconds` | int | Sets the URL lifetime in seconds, from `1` to `604800`. A URL is valid for at most `7` days. A value outside that range raises `BadRequestError` before any request is sent. The default is `3600`. | - The requests require the `write:sandboxes` permission. - Windows sandboxes cannot have presigned URLs. ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() // Download link, valid for 1 hour (default) const downloadUrl = await sandbox.fs.presignedDownloadUrl('/home/daytona/workspace/report.pdf') // Upload link, valid for 1 hour (default) const uploadUrl = await sandbox.fs.presignedUploadUrl('/home/daytona/workspace/incoming/data.bin') // Invalidate every outstanding presigned URL for this sandbox; old URLs can still work for up to 30 seconds await sandbox.rotateSigningKey() ``` | **Parameter** | **Type** | **Description** | | ------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `expiresInSeconds` | number | Sets the URL lifetime in seconds, as an integer from `1` to `604800`. A URL is valid for at most `7` days. A value outside that range throws `BadRequestError` before any request is sent. The default is `3600`. | - The requests require the `write:sandboxes` permission. - Windows sandboxes cannot have presigned URLs. ```bash # Expiry 1 hour from now (GNU date; on macOS use: date -u -v+1H +%Y-%m-%dT%H:%M:%SZ) EXPIRES_AT=$(date -u -d '+1 hour' +%Y-%m-%dT%H:%M:%SZ) # Sign a download link: {"url": "...", "method": "GET", "path": "...", "expires_at": "...", "signature": "v1_..."} # Use "method": "POST" to sign an upload link curl 'https://api.daytona.com/sandboxes/{sandboxId}/files/sign' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data "{ \"method\": \"GET\", \"path\": \"/home/daytona/workspace/report.pdf\", \"expires_at\": \"$EXPIRES_AT\" }" # Consume a download link: use the returned url as is (no Authorization header) curl --output report.pdf \ '{toolboxProxyUrl}/{sandboxId}/files/download?path=%2Fhome%2Fdaytona%2Fworkspace%2Freport.pdf&expires={expires}&signature={signature}' # Consume an upload link curl --request POST \ --form 'file=@data.bin' \ '{toolboxProxyUrl}/{sandboxId}/files/upload?path=%2Fhome%2Fdaytona%2Fworkspace%2Fincoming%2Fdata.bin&expires={expires}&signature={signature}' # Rotate the signing key to revoke all outstanding links; old links can still work for up to 30 seconds curl 'https://api.daytona.com/sandboxes/{sandboxId}/signing-key/rotate' \ --request POST \ --header 'Authorization: Bearer YOUR_API_KEY' ``` | **Field** | **Type** | **Description** | | ---------- | --------- | -------------------------------------------------------------------------------------------------------- | | `expires_at` | string | Sets the expiry as an RFC 3339 timestamp. The expiry must lie in the future and at most `7` days ahead. This field is required. | | `method` | string | Sets the link type: `GET` for a download link and `POST` for an upload link, in any letter case. Any other method returns `400`. This field is required. | | `path` | string | Sets the absolute sandbox path of the file to download or upload. The `path` query parameter of the returned URL must match it exactly. This field is required. | - The requests require the `write:sandboxes` permission. - Windows sandboxes cannot have presigned URLs. ## Permissions [#permissions] File system access runs through the toolbox of a sandbox. Access is governed by one project permission, which you can grant to an [organization role](/docs/organizations#roles) or an [API key](/docs/api-keys). A [sandbox access token](/docs/sandboxes#create-an-access-token) with the toolbox:fs operation grants the same access to a single sandbox, without an API key. The sandbox read permission alone does not grant toolbox access. | **Permission** | **Grants** | | --------------------- | ---------------------------------------------------- | | **`write:sandboxes`** | List, read, upload, download, move, and delete files | # Git Operations (/docs/git-operations) Git operations are available through the Git module of a sandbox. Operations run through the Daytona API, so your application works with repositories in a sandbox directly, without executing shell commands inside it. The sandbox image must include Git. The Git module covers cloning and initializing repositories, checking status, managing branches and remotes, staging, committing, resetting and restoring changes, pushing and pulling with authentication, inspecting commit history, and reading and writing Git configuration. Private repositories authenticate with personal access tokens passed per operation. Clone, push, and pull accept a per-call timeout; the default is 30 minutes. ## Use cases [#use-cases] Git operations are used when a sandbox works on code that lives in a Git repository. - **Coding agents.** An agent clones a repository, changes code, commits, and pushes a branch for review. Every step runs through the API, with no shell commands in the sandbox. Clone, push, and pull accept a timeout for each call, with a default of 30 minutes. - **Branch checks.** A sandbox checks out a branch and runs its tests in isolation. Each branch gets its own sandbox, so one run does not affect another. A clone can also check out a specific commit, which leaves the repository on a detached HEAD. - **Private repositories.** A username and a personal access token passed with each clone, push, or pull authenticate against private repositories. The credentials are not written to the repository configuration or the remote URL. Without both a username and a password, Git runs without credentials and does not prompt, so the operation fails. - **Change inspection.** Status, branches, and commit history are read without a shell, for example to show an agent's changes before a commit. Status reports the current branch, how far it is ahead of and behind its upstream, and the state of each changed file. History lists every commit reachable from the current commit, newest first, with the author and timestamp of each. - **Rollback of failed attempts.** Reset and restore discard uncommitted changes or unstage files. An agent returns the repository to a known commit and tries again. Restore also accepts a commit, a branch, or a tag as its source. ## Clone repositories [#clone-repositories] Clone a repository into a sandbox directory. A relative destination resolves against the working directory of the sandbox, which depends on the image and the operating system. You can clone a specific branch or a specific commit. A commit takes precedence over a branch and leaves the repository on a detached HEAD at that commit. If a clone times out, Daytona removes the partly cloned destination, unless the destination existed before the call. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.git.clone("https://github.com/user/repo.git", "/home/daytona/workspace/repo") ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------- | | `url` | str | Sets the URL of the repository to clone. This parameter is required. | | `path` | str | Sets the destination directory in the sandbox. A relative path resolves against the daemon working directory: on a Linux sandbox, the image's `WORKDIR`, or the image's `HOME` when the image declares no `WORKDIR` (`/root` when the image sets no `HOME`); on a macOS sandbox, `/Users/lume`. This parameter is required. | | `branch` | str | Sets the branch to check out after the clone. It is ignored when `commit_id` is set. The default is the default branch of the remote. | | `commit_id` | str | Sets the commit to check out after the clone, which leaves the repository on a detached HEAD. | | `depth` | int | Sets the number of commits to fetch for a shallow clone; `1` fetches only the tip commit. A value below `1` raises `BadRequestError`. | | `insecure_skip_tls` | bool | Skips TLS certificate verification for this clone only. The default is `False`. | | `username` | str | Sets the username for a private repository. It is used only together with `password`. See [authenticate credentials](#authenticate-credentials). | | `password` | str | Sets the password or personal access token for a private repository. It is used only together with `username`. | | `timeout` | float | Sets the time limit of the call in seconds. `0` removes this limit, but the sandbox still stops the Git command after 31 minutes and returns `408`. The default is `1800`. | ```typescript import { Daytona } from '@daytona/sdk'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); await sandbox.git.clone('https://github.com/user/repo.git', { path: '/home/daytona/workspace/repo' }); ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------- | | `url` | string | Sets the URL of the repository to clone. This is the first positional argument and is required. | | `path` | string | Sets the destination directory in the sandbox. A relative path resolves against the daemon working directory: on a Linux sandbox, the image's `WORKDIR`, or the image's `HOME` when the image declares no `WORKDIR` (`/root` when the image sets no `HOME`); on a macOS sandbox, `/Users/lume`. This parameter is required. | | `branch` | string | Sets the branch to check out after the clone. It is ignored when `commitId` is set. The default is the default branch of the remote. | | `commitId` | string | Sets the commit to check out after the clone, which leaves the repository on a detached HEAD. | | `depth` | number | Sets the number of commits to fetch for a shallow clone; `1` fetches only the tip commit. | | `insecureSkipTls` | boolean | Skips TLS certificate verification for this clone only. The default is `false`. | | `username` | string | Sets the username for a private repository. It is used only together with `password`. See [authenticate credentials](#authenticate-credentials). | | `password` | string | Sets the password or personal access token for a private repository. It is used only together with `username`. | | `timeoutSeconds` | number | Sets the time limit of the call in seconds. `0` removes this limit, but the sandbox still stops the Git command after 31 minutes and returns `408`. The default is `1800`. | ```bash curl '{toolboxProxyUrl}/{sandboxId}/git/clone' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "url": "https://github.com/user/repo.git", "path": "/home/daytona/workspace/repo" }' ``` | **Field** | **Type** | **Description** | | --------- | -------- | ---------------------------------------- | | `url` | string | Sets the URL of the repository to clone. This field is required. A missing value returns `400`. | | `path` | string | Sets the destination directory in the sandbox. A relative path resolves against the daemon working directory: on a Linux sandbox, the image's `WORKDIR`, or the image's `HOME` when the image declares no `WORKDIR` (`/root` when the image sets no `HOME`); on a macOS sandbox, `/Users/lume`. This field is required. A missing value returns `400`. | | `branch` | string | Sets the branch to check out after the clone. It is ignored when `commit_id` is set. The default is the default branch of the remote. | | `commit_id` | string | Sets the commit to check out after the clone, which leaves the repository on a detached HEAD. | | `depth` | integer | Sets the number of commits to fetch for a shallow clone; `1` fetches only the tip commit. | | `insecureSkipTls` | boolean | Skips TLS certificate verification for this clone only. The default is `false`. | | `username` | string | Sets the username for a private repository. It is used only together with `password`. See [authenticate credentials](#authenticate-credentials). | | `password` | string | Sets the password or personal access token for a private repository. It is used only together with `username`. | - The request requires the `write:sandboxes` permission. - `{toolboxProxyUrl}` is the `toolbox_proxy_url` field of the [sandbox](/docs/sandboxes#get-a-sandbox). ## Get repository status [#get-repository-status] Get the status of a repository. The status reports the current branch, whether it has an upstream branch, how many commits it is ahead of and behind that upstream, and the state of each changed or untracked file in the index and the working tree. The ahead and behind counts are zero when the branch has no upstream. A renamed file also carries its original path. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.git.clone("https://github.com/user/repo.git", "/home/daytona/workspace/repo") status = sandbox.git.status("/home/daytona/workspace/repo") print(f"Current branch: {status.current_branch}") # "HEAD" when detached print(f"Commits ahead: {status.ahead}, behind: {status.behind}") # staging and worktree hold the porcelain status codes # (M, A, D, R, ?, ...) or a space when the file is unchanged there. for file in status.file_status or []: print(f"{file.staging}{file.worktree} {file.name}") ``` ```typescript import { Daytona } from '@daytona/sdk'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); await sandbox.git.clone('https://github.com/user/repo.git', { path: '/home/daytona/workspace/repo' }); const status = await sandbox.git.status('/home/daytona/workspace/repo'); console.log(`Current branch: ${status.currentBranch}`); // "HEAD" when detached console.log(`Commits ahead: ${status.ahead}, behind: ${status.behind}`); // staging and worktree hold the porcelain status codes // (M, A, D, R, ?, ...) or a space when the file is unchanged there. status.fileStatus?.forEach(file => { console.log(`${file.staging}${file.worktree} ${file.name}`); }); ``` ```bash curl '{toolboxProxyUrl}/{sandboxId}/git/status?path=/home/daytona/workspace/repo' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ```json { "currentBranch": "main", "branchPublished": true, "ahead": 1, "behind": 0, "fileStatus": [ { "name": "src/main.py", "extra": "", "staging": "M", "worktree": " " }, { "name": "docs/new.md", "extra": "docs/old.md", "staging": "R", "worktree": " " }, { "name": "notes.txt", "extra": "", "staging": "?", "worktree": "?" } ] } ``` The response has the following fields: | **Field** | **Description** | | --- | --- | | `branchPublished` | The value is `true` when the current branch has an upstream branch. | | `extra` | Holds the original path of a renamed file. The value is empty for other files. | ## Branch operations [#branch-operations] ### List branches [#list-branches] List a repository's local branches, by name only; remote-tracking branches are excluded. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.git.clone("https://github.com/user/repo.git", "/home/daytona/workspace/repo") response = sandbox.git.list_branches("/home/daytona/workspace/repo") for branch in response.items: print(branch) ``` ```typescript import { Daytona } from '@daytona/sdk'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); await sandbox.git.clone('https://github.com/user/repo.git', { path: '/home/daytona/workspace/repo' }); const response = await sandbox.git.listBranches('/home/daytona/workspace/repo'); response.items.forEach(branch => console.log(branch)); ``` ```bash curl '{toolboxProxyUrl}/{sandboxId}/git/branches?path=/home/daytona/workspace/repo' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ```json { "branches": ["main", "new-feature"] } ``` ### Create branches [#create-branches] Create a branch. The new branch starts at the current commit, and the repository stays on the branch it was on. To switch to the new branch, [check it out](#checkout-branches). ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.git.clone("https://github.com/user/repo.git", "/home/daytona/workspace/repo") # Create a new branch sandbox.git.create_branch("/home/daytona/workspace/repo", "new-feature") ``` ```typescript import { Daytona } from '@daytona/sdk'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); await sandbox.git.clone('https://github.com/user/repo.git', { path: '/home/daytona/workspace/repo' }); // Create new branch await sandbox.git.createBranch('/home/daytona/workspace/repo', 'new-feature'); ``` ```bash curl '{toolboxProxyUrl}/{sandboxId}/git/branches' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "path": "/home/daytona/workspace/repo", "name": "new-feature" }' ``` ### Checkout branches [#checkout-branches] Check out a branch. Checkout switches the working tree to the named branch. It does not create a branch from scratch; to start a new branch, [create it](#create-branches) first. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.git.clone("https://github.com/user/repo.git", "/home/daytona/workspace/repo") sandbox.git.create_branch("/home/daytona/workspace/repo", "feature-branch") # Checkout a branch sandbox.git.checkout_branch("/home/daytona/workspace/repo", "feature-branch") ``` ```typescript import { Daytona } from '@daytona/sdk'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); await sandbox.git.clone('https://github.com/user/repo.git', { path: '/home/daytona/workspace/repo' }); await sandbox.git.createBranch('/home/daytona/workspace/repo', 'feature-branch'); // Checkout a branch await sandbox.git.checkoutBranch('/home/daytona/workspace/repo', 'feature-branch'); ``` ```bash # Create a branch curl '{toolboxProxyUrl}/{sandboxId}/git/branches' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "path": "/home/daytona/workspace/repo", "name": "feature-branch" }' # Checkout a branch curl '{toolboxProxyUrl}/{sandboxId}/git/checkout' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "path": "/home/daytona/workspace/repo", "branch": "feature-branch" }' ``` ### Delete branches [#delete-branches] Delete a branch. Deletion is forced, so unmerged commits do not block it. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.git.clone("https://github.com/user/repo.git", "/home/daytona/workspace/repo") sandbox.git.create_branch("/home/daytona/workspace/repo", "old-feature") # Delete a branch sandbox.git.delete_branch("/home/daytona/workspace/repo", "old-feature") ``` ```typescript import { Daytona } from '@daytona/sdk'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); await sandbox.git.clone('https://github.com/user/repo.git', { path: '/home/daytona/workspace/repo' }); await sandbox.git.createBranch('/home/daytona/workspace/repo', 'old-feature'); // Delete a branch await sandbox.git.deleteBranch('/home/daytona/workspace/repo', 'old-feature'); ``` ```bash # Create a branch curl '{toolboxProxyUrl}/{sandboxId}/git/branches' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "path": "/home/daytona/workspace/repo", "name": "old-feature" }' # Delete a branch curl '{toolboxProxyUrl}/{sandboxId}/git/branches' \ --request DELETE \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "path": "/home/daytona/workspace/repo", "name": "old-feature" }' ``` ## Stage changes [#stage-changes] Stage at least one file for the next commit. Paths are relative to the repository root. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.git.clone("https://github.com/user/repo.git", "/home/daytona/workspace/repo") sandbox.fs.write_text("/home/daytona/workspace/repo/README.md", "# Updated\n") sandbox.git.add("/home/daytona/workspace/repo", ["README.md"]) ``` ```typescript import { Daytona } from '@daytona/sdk'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); await sandbox.git.clone('https://github.com/user/repo.git', { path: '/home/daytona/workspace/repo' }); await sandbox.fs.writeText('/home/daytona/workspace/repo/README.md', '# Updated\n'); await sandbox.git.add('/home/daytona/workspace/repo', ['README.md']); ``` ```bash curl '{toolboxProxyUrl}/{sandboxId}/git/add' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "path": "/home/daytona/workspace/repo", "files": ["README.md"] }' ``` ## Commit changes [#commit-changes] Commit the staged changes. Every commit requires an author name and email. They apply to that commit only and are not written to the repository configuration, so the identity from [configure user](#configure-user) does not replace them. By default, a commit with nothing staged fails; allowing empty commits records a commit without staged changes. Repository hooks do not run for commits or for any other operation of the Git module. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.git.clone("https://github.com/user/repo.git", "/home/daytona/workspace/repo") sandbox.fs.write_text("/home/daytona/workspace/repo/README.md", "# Updated\n") # Stage and commit changes sandbox.git.add("/home/daytona/workspace/repo", ["README.md"]) commit = sandbox.git.commit( "/home/daytona/workspace/repo", "Update documentation", author="John Doe", email="john@example.com", ) print(f"Commit hash: {commit.hash}") ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | ----------------------------------------------------------------------------- | | `author` | str | Sets the author name of the commit. This parameter is required. An empty value raises `BadRequestError` before the request is sent. | | `email` | str | Sets the author email of the commit. This parameter is required. An empty value raises `BadRequestError` before the request is sent. | | `allow_empty` | bool | Allows a commit with nothing staged. The default is `False`. | The response has the following fields: | **Field** | **Description** | | --- | --- | | `hash` | Holds the full SHA of the new commit. | ```typescript import { Daytona } from '@daytona/sdk'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); await sandbox.git.clone('https://github.com/user/repo.git', { path: '/home/daytona/workspace/repo' }); await sandbox.fs.writeText('/home/daytona/workspace/repo/README.md', '# Updated\n'); // Stage and commit changes await sandbox.git.add('/home/daytona/workspace/repo', ['README.md']); const commit = await sandbox.git.commit( '/home/daytona/workspace/repo', 'Update documentation', { author: 'John Doe', email: 'john@example.com' } ); console.log(`Commit hash: ${commit.hash}`); ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | ---------------------------------------------------------------------------------------------- | | `author` | string | Sets the author name of the commit. This parameter is required. An empty value throws a `DaytonaError` with status `400` before the request is sent. | | `email` | string | Sets the author email of the commit. This parameter is required. An empty value throws a `DaytonaError` with status `400` before the request is sent. | | `allowEmpty` | boolean | Allows a commit with nothing staged. The default is `false`. | The response has the following fields: | **Field** | **Description** | | --- | --- | | `hash` | Holds the full SHA of the new commit. | ```bash # Stage changes; README.md must have uncommitted changes curl '{toolboxProxyUrl}/{sandboxId}/git/add' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "path": "/home/daytona/workspace/repo", "files": ["README.md"] }' # Commit changes curl '{toolboxProxyUrl}/{sandboxId}/git/commit' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "path": "/home/daytona/workspace/repo", "message": "Update documentation", "author": "John Doe", "email": "john@example.com" }' ``` | **Field** | **Type** | **Description** | | --------- | -------- | --------------------------------------- | | `message` | string | Sets the commit message. This field is required. An empty value returns `400`. | | `author` | string | Sets the author name of the commit. This field is required. An empty value returns `400`. | | `email` | string | Sets the author email of the commit. This field is required. An empty value returns `400`. | | `allow_empty` | boolean | Allows a commit with nothing staged. The default is `false`. | The response has the following fields: | **Field** | **Description** | | --- | --- | | `hash` | Holds the full SHA of the new commit. | ## Remote operations [#remote-operations] ### Push changes [#push-changes] Push the current branch to the remote named origin. The branch is pushed to the branch of the same name on the remote, so a new local branch does not need an upstream configured first. Push fails when the repository is on a detached HEAD, and when the remote branch has commits that the local branch does not have. For private repositories, see [authenticate credentials](#authenticate-credentials). ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.git.clone("https://github.com/user/repo.git", "/home/daytona/workspace/repo") sandbox.fs.write_text("/home/daytona/workspace/repo/README.md", "# Updated\n") sandbox.git.add("/home/daytona/workspace/repo", ["README.md"]) sandbox.git.commit( "/home/daytona/workspace/repo", "Update documentation", author="John Doe", email="john@example.com", ) sandbox.git.push("/home/daytona/workspace/repo") ``` | **Parameter** | **Type** | **Description** | | -------------- | -------- | --------------- | | `branch` | str | Sets the local branch to push to the branch of the same name on the remote. The default is the current branch. | | `remote` | str | Sets the name of a configured remote to push to. A URL, a path, or an unknown name raises `BadRequestError`. The default is `origin`. | | `set_upstream` | bool | Sets the pushed remote branch as the upstream of the local branch. The default is `False`. | | `username` | str | Sets the username for a private repository. It is used only together with `password`. See [authenticate credentials](#authenticate-credentials). | | `password` | str | Sets the password or personal access token for a private repository. It is used only together with `username`. | | `timeout` | float | Sets the time limit of the call in seconds. `0` removes this limit, but the sandbox still stops the Git command after 31 minutes and returns `408`. The default is `1800`. | ```typescript import { Daytona } from '@daytona/sdk'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); await sandbox.git.clone('https://github.com/user/repo.git', { path: '/home/daytona/workspace/repo' }); await sandbox.fs.writeText('/home/daytona/workspace/repo/README.md', '# Updated\n'); await sandbox.git.add('/home/daytona/workspace/repo', ['README.md']); await sandbox.git.commit( '/home/daytona/workspace/repo', 'Update documentation', { author: 'John Doe', email: 'john@example.com' } ); await sandbox.git.push('/home/daytona/workspace/repo'); ``` | **Parameter** | **Type** | **Description** | | ---------------- | -------- | --------------- | | `branch` | string | Sets the local branch to push to the branch of the same name on the remote. The default is the current branch. | | `remote` | string | Sets the name of a configured remote to push to. A URL, a path, or an unknown name throws a `DaytonaError` with status `400`. The default is `'origin'`. | | `setUpstream` | boolean | Sets the pushed remote branch as the upstream of the local branch. The default is `false`. | | `username` | string | Sets the username for a private repository. It is used only together with `password`. See [authenticate credentials](#authenticate-credentials). | | `password` | string | Sets the password or personal access token for a private repository. It is used only together with `username`. | | `timeoutSeconds` | number | Sets the time limit of the call in seconds. `0` removes this limit, but the sandbox still stops the Git command after 31 minutes and returns `408`. The default is `1800`. | ```bash curl '{toolboxProxyUrl}/{sandboxId}/git/push' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "path": "/home/daytona/workspace/repo" }' ``` | **Field** | **Type** | **Description** | | ------------- | -------- | --------------- | | `branch` | string | Sets the local branch to push to the branch of the same name on the remote. The default is the current branch. | | `remote` | string | Sets the name of a configured remote to push to. A URL, a path, or an unknown name returns `400`. The default is `origin`. | | `setUpstream` | boolean | Sets the pushed remote branch as the upstream of the local branch. The default is `false`. | | `username` | string | Sets the username for a private repository. It is used only together with `password`. See [authenticate credentials](#authenticate-credentials). | | `password` | string | Sets the password or personal access token for a private repository. It is used only together with `username`. | ### Pull changes [#pull-changes] Pull changes into the current branch from its upstream branch. Pull only fast-forwards: when the local and remote branches have diverged, pull fails with a conflict instead of creating a merge commit. For private repositories, see [authenticate credentials](#authenticate-credentials). ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.git.clone("https://github.com/user/repo.git", "/home/daytona/workspace/repo") sandbox.git.pull("/home/daytona/workspace/repo") ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------- | | `branch` | str | Sets the branch to pull. It must be the current branch; another branch raises `BadRequestError`. | | `remote` | str | Sets the name of a configured remote to pull from. A URL, a path, or an unknown name raises `BadRequestError`. Without `remote` and `branch`, pull uses the upstream of the current branch; with `branch` only, the default is `origin`. | | `username` | str | Sets the username for a private repository. It is used only together with `password`. See [authenticate credentials](#authenticate-credentials). | | `password` | str | Sets the password or personal access token for a private repository. It is used only together with `username`. | | `timeout` | float | Sets the time limit of the call in seconds. `0` removes this limit, but the sandbox still stops the Git command after 31 minutes and returns `408`. The default is `1800`. | ```typescript import { Daytona } from '@daytona/sdk'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); await sandbox.git.clone('https://github.com/user/repo.git', { path: '/home/daytona/workspace/repo' }); await sandbox.git.pull('/home/daytona/workspace/repo'); ``` | **Parameter** | **Type** | **Description** | | ---------------- | -------- | --------------- | | `branch` | string | Sets the branch to pull. It must be the current branch; another branch throws a `DaytonaError` with status `400`. | | `remote` | string | Sets the name of a configured remote to pull from. A URL, a path, or an unknown name throws a `DaytonaError` with status `400`. Without `remote` and `branch`, pull uses the upstream of the current branch; with `branch` only, the default is `'origin'`. | | `username` | string | Sets the username for a private repository. It is used only together with `password`. See [authenticate credentials](#authenticate-credentials). | | `password` | string | Sets the password or personal access token for a private repository. It is used only together with `username`. | | `timeoutSeconds` | number | Sets the time limit of the call in seconds. `0` removes this limit, but the sandbox still stops the Git command after 31 minutes and returns `408`. The default is `1800`. | ```bash curl '{toolboxProxyUrl}/{sandboxId}/git/pull' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "path": "/home/daytona/workspace/repo" }' ``` | **Field** | **Type** | **Description** | | ---------- | -------- | --------------- | | `branch` | string | Sets the branch to pull. It must be the current branch; another branch returns `400`. | | `remote` | string | Sets the name of a configured remote to pull from. A URL, a path, or an unknown name returns `400`. Without `remote` and `branch`, pull uses the upstream of the current branch; with `branch` only, the default is `origin`. | | `username` | string | Sets the username for a private repository. It is used only together with `password`. See [authenticate credentials](#authenticate-credentials). | | `password` | string | Sets the password or personal access token for a private repository. It is used only together with `username`. | ## Initialize a repository [#initialize-a-repository] Initialize a new repository at a path, optionally bare and with a named initial branch. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.git.init("/home/daytona/workspace/repo") ``` | **Parameter** | **Type** | **Description** | | ---------------- | -------- | --------------- | | `bare` | bool | Creates a bare repository, without a working tree. The default is `False`. | | `initial_branch` | str | Sets the name of the initial branch. The default is `init.defaultBranch` from the Git configuration of the image or the user, or `master` when neither sets it. | ```typescript import { Daytona } from '@daytona/sdk'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); await sandbox.git.init('/home/daytona/workspace/repo'); ``` | **Parameter** | **Type** | **Description** | | --------------- | -------- | --------------- | | `bare` | boolean | Creates a bare repository, without a working tree. The default is `false`. | | `initialBranch` | string | Sets the name of the initial branch. The default is `init.defaultBranch` from the Git configuration of the image or the user, or `master` when neither sets it. | ```bash curl '{toolboxProxyUrl}/{sandboxId}/git/init' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "path": "/home/daytona/workspace/repo" }' ``` | **Field** | **Type** | **Description** | | ---------------- | -------- | --------------- | | `bare` | boolean | Creates a bare repository, without a working tree. The default is `false`. | | `initial_branch` | string | Sets the name of the initial branch. The default is `init.defaultBranch` from the Git configuration of the image or the user, or `master` when neither sets it. | ## Reset changes [#reset-changes] Reset the current branch to a commit. The mode also controls index and working tree resets. The target defaults to the current commit, so resetting only files unstages them. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.git.clone("https://github.com/user/repo.git", "/home/daytona/workspace/repo") # Reset HEAD and the index to the previous commit, keep the working tree sandbox.git.reset("/home/daytona/workspace/repo", target="HEAD~1") ``` | **Parameter** | **Type** | **Description** | | ------------- | --------------- | ------------------------------------------------------------------- | | `mode` | str | Sets the reset mode: `mixed`, `soft`, `hard`, `merge`, or `keep`. The default is `mixed`. | | `target` | str | Sets the commit to reset to. The default is the current commit. | | `files` | Sequence\[str\] | Sets the files to reset. Files are accepted only in `mixed` mode. Other modes reject files with `400`. | ```typescript import { Daytona } from '@daytona/sdk'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); await sandbox.git.clone('https://github.com/user/repo.git', { path: '/home/daytona/workspace/repo' }); // Reset HEAD and the index to the previous commit, keep the working tree await sandbox.git.reset('/home/daytona/workspace/repo', { target: 'HEAD~1' }); ``` | **Parameter** | **Type** | **Description** | | ------------- | ---------- | -------------------------------------------------------------------------- | | `mode` | string | Sets the reset mode: `'mixed'`, `'soft'`, `'hard'`, `'merge'`, or `'keep'`. The default is `'mixed'`. | | `target` | string | Sets the commit to reset to. The default is the current commit. | | `files` | string\[\] | Sets the files to reset. Files are accepted only in `'mixed'` mode. Other modes reject files with `400`. | ```bash curl '{toolboxProxyUrl}/{sandboxId}/git/reset' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "path": "/home/daytona/workspace/repo", "target": "HEAD~1" }' ``` | **Field** | **Type** | **Description** | | --------- | ---------- | ------------------------------------------------------------------- | | `mode` | string | Sets the reset mode: `mixed`, `soft`, `hard`, `merge`, or `keep`. The default is `mixed`. | | `target` | string | Sets the commit to reset to. The default is the current commit. | | `files` | string\[\] | Sets the files to reset. Files are accepted only in `mixed` mode. Other modes reject files with `400`. | ## Restore files [#restore-files] Restore files in the working tree, the index, or both; at least one file is required. Restoring the working tree discards uncommitted changes; restoring the index unstages them. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.git.clone("https://github.com/user/repo.git", "/home/daytona/workspace/repo") sandbox.fs.write_text("/home/daytona/workspace/repo/README.md", "# Updated\n") # Restore a file in the working tree sandbox.git.restore("/home/daytona/workspace/repo", ["README.md"]) ``` | **Parameter** | **Type** | **Description** | | ------------- | --------------- | ------------------------------------------------------------------------------------------------------ | | `files` | Sequence\[str\] | Sets the files to restore. This parameter is required and must list at least one file. | | `staged` | bool | Restores the index entry. | | `worktree` | bool | Restores the working tree file. This is the default when neither `staged` nor `worktree` is set. | | `source` | str | Sets the commit, branch, or tag to restore from. By default, the working tree restores from the index, and the index restores from `HEAD`. | ```typescript import { Daytona } from '@daytona/sdk'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); await sandbox.git.clone('https://github.com/user/repo.git', { path: '/home/daytona/workspace/repo' }); await sandbox.fs.writeText('/home/daytona/workspace/repo/README.md', '# Updated\n'); // Restore a file in the working tree await sandbox.git.restore('/home/daytona/workspace/repo', ['README.md']); ``` | **Parameter** | **Type** | **Description** | | ------------- | ---------- | ------------------------------------------------------------------------------------------------------ | | `files` | string\[\] | Sets the files to restore. This parameter is required and must list at least one file. | | `staged` | boolean | Restores the index entry. | | `worktree` | boolean | Restores the working tree file. This is the default when neither `staged` nor `worktree` is set. | | `source` | string | Sets the commit, branch, or tag to restore from. By default, the working tree restores from the index, and the index restores from `HEAD`. | ```bash curl '{toolboxProxyUrl}/{sandboxId}/git/restore' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "path": "/home/daytona/workspace/repo", "files": ["README.md"] }' ``` | **Field** | **Type** | **Description** | | ---------- | ---------- | ------------------------------------------------------------------------------------------------------ | | `files` | string\[\] | Sets the files to restore. This parameter is required and must list at least one file. | | `staged` | boolean | Restores the index entry. | | `worktree` | boolean | Restores the working tree file. This is the default when neither `staged` nor `worktree` is set. | | `source` | string | Sets the commit, branch, or tag to restore from. By default, the working tree restores from the index, and the index restores from `HEAD`. | ## Get commit history [#get-commit-history] Get the commit history of the current branch: every commit reachable from the current commit, newest first, in one response. Each entry carries the full commit hash, the first line of the message, the author name and email, and the author timestamp in RFC 3339 format. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.git.clone("https://github.com/user/repo.git", "/home/daytona/workspace/repo") # Commits are returned newest first history = sandbox.git.history("/home/daytona/workspace/repo") for commit in history.items: print(f"{commit.hash}: {commit.message}") print(f" {commit.author} <{commit.email}> at {commit.timestamp}") ``` The response has the following fields: | **Field** | **Description** | | --- | --- | | `items` | Holds the commits, newest first. Each commit has `hash`, `message`, `author`, `email`, and `timestamp`. | | `timestamp` | Holds the author time of a commit as a timezone-aware `datetime`. | ```typescript import { Daytona } from '@daytona/sdk'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); await sandbox.git.clone('https://github.com/user/repo.git', { path: '/home/daytona/workspace/repo' }); // Commits are returned newest first const history = await sandbox.git.history('/home/daytona/workspace/repo'); history.items.forEach(commit => { console.log(`${commit.hash}: ${commit.message}`); console.log(` ${commit.author} <${commit.email}> at ${commit.timestamp}`); }); ``` The response has the following fields: | **Field** | **Description** | | --- | --- | | `items` | Holds the commits, newest first. Each commit has `hash`, `message`, `author`, `email`, and `timestamp`. | | `timestamp` | Holds the author time of a commit as an RFC 3339 string. | ```bash curl '{toolboxProxyUrl}/{sandboxId}/git/history?path=/home/daytona/workspace/repo' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ```json [ { "hash": "3f2a9c1e8b7d6a5f4e3d2c1b0a9f8e7d6c5b4a39", "message": "Update documentation", "author": "John Doe", "email": "john@example.com", "timestamp": "2026-09-13T09:41:12+00:00" } ] ``` ## Manage remotes [#manage-remotes] Add a remote to a repository and list the configured remotes. Listed URLs mask embedded credentials with asterisks. [Push](#push-changes) targets the remote named origin unless the call names another remote. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.git.init("/home/daytona/workspace/repo") # Add a remote sandbox.git.add_remote("/home/daytona/workspace/repo", "origin", "https://github.com/user/repo.git") # List remotes remotes = sandbox.git.list_remotes("/home/daytona/workspace/repo") for remote in remotes.items: print(f"{remote.name}: {remote.url}") ``` ```typescript import { Daytona } from '@daytona/sdk'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); await sandbox.git.init('/home/daytona/workspace/repo'); // Add a remote await sandbox.git.addRemote('/home/daytona/workspace/repo', 'origin', 'https://github.com/user/repo.git'); // List remotes const remotes = await sandbox.git.listRemotes('/home/daytona/workspace/repo'); remotes.items.forEach(remote => { console.log(`${remote.name}: ${remote.url}`); }); ``` ```bash # Initialize a repository curl '{toolboxProxyUrl}/{sandboxId}/git/init' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "path": "/home/daytona/workspace/repo" }' # Add a remote curl '{toolboxProxyUrl}/{sandboxId}/git/remotes' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "name": "origin", "path": "/home/daytona/workspace/repo", "url": "https://github.com/user/repo.git" }' # List remotes curl '{toolboxProxyUrl}/{sandboxId}/git/remotes?path=/home/daytona/workspace/repo' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ```json { "remotes": [ { "name": "origin", "url": "https://github.com/user/repo.git" } ] } ``` ## Configure Git [#configure-git] Set and get Git configuration values. Global values apply to every repository for the user that Git runs as in the sandbox: the sandbox default user, or root when no default user is set. Local values apply to one repository. A key must contain a section and a name separated by a dot. Getting a key that is not set returns no value instead of an error. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() # Set a config value at the global scope sandbox.git.set_config("core.editor", "vim") # Get a config value (None when unset) editor = sandbox.git.get_config("core.editor") ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------------------------------------------------- | | `scope` | str | Sets the configuration scope, `global` or `local`. The default is `global`. | | `path` | str | Sets the repository path. This parameter is required when the scope is `local` and ignored for `global`. | ```typescript import { Daytona } from '@daytona/sdk'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); // Set a config value at the global scope await sandbox.git.setConfig('core.editor', 'vim'); // Get a config value (null when unset) const editor = await sandbox.git.getConfig('core.editor'); ``` | **Parameter** | **Type** | **Description** | | ------------- | ---------------- | ------------------------------------------------------------- | | `scope` | GitConfigScope | Sets the configuration scope, `'global'` or `'local'`. The default is `'global'`. | | `path` | string | Sets the repository path. This parameter is required when the scope is `'local'` and ignored for `'global'`. | ```bash # Set a config value curl '{toolboxProxyUrl}/{sandboxId}/git/config' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "key": "core.editor", "value": "vim", "scope": "global" }' # Get a config value curl '{toolboxProxyUrl}/{sandboxId}/git/config?key=core.editor&scope=global' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` | **Field** | **Type** | **Description** | | --------- | -------- | --------------------------------------------------------- | | `scope` | string | Sets the configuration scope, `global` or `local`. The default is `global`. | | `path` | string | Sets the repository path. This field is required when the scope is `local` and ignored for `global`. | The response has the following fields: | **Field** | **Description** | | --- | --- | | `value` | Holds the configuration value that a get returns. The value is `null` when the key is not set. | ## Configure user [#configure-user] Set the user name and email that Git records in commits made with Git commands inside the sandbox, such as commits from processes you run. Commits made through the Git module take the author name and email from each [commit](#commit-changes) call instead. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() # Configure the global Git user sandbox.git.set_config("user.name", "John Doe") sandbox.git.set_config("user.email", "john@example.com") ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------------------------------------------------- | | `scope` | str | Sets the configuration scope, `global` or `local`. The default is `global`. | | `path` | str | Sets the repository path. This parameter is required when the scope is `local` and ignored for `global`. | ```typescript import { Daytona } from '@daytona/sdk'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); // Configure the global Git user await sandbox.git.setConfig('user.name', 'John Doe'); await sandbox.git.setConfig('user.email', 'john@example.com'); ``` | **Parameter** | **Type** | **Description** | | ------------- | ---------------- | ------------------------------------------------------------- | | `scope` | GitConfigScope | Sets the configuration scope, `'global'` or `'local'`. The default is `'global'`. | | `path` | string | Sets the repository path. This parameter is required when the scope is `'local'` and ignored for `'global'`. | ```bash curl '{toolboxProxyUrl}/{sandboxId}/git/config' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "key": "user.name", "value": "John Doe", "scope": "global" }' curl '{toolboxProxyUrl}/{sandboxId}/git/config' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "key": "user.email", "value": "john@example.com", "scope": "global" }' ``` | **Field** | **Type** | **Description** | | --------- | -------- | --------------------------------------------------------- | | `scope` | string | Sets the configuration scope, `global` or `local`. The default is `global`. | | `path` | string | Sets the repository path. This field is required when the scope is `local` and ignored for `global`. | ## Authenticate credentials [#authenticate-credentials] Authenticate clone, push, and pull against private repositories with a username and a personal access token as the password. Credentials apply only to their call; they are not written to the repository configuration or remote URL and do not appear on the Git command line. Credentials are used only when both a username and a password are set. Otherwise, Git runs without credentials and does not prompt, so operations on a private repository fail. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.git.clone( "https://github.com/user/repo.git", "/home/daytona/workspace/repo", username="git", password="personal_access_token", ) sandbox.git.push( "/home/daytona/workspace/repo", username="git", password="personal_access_token" ) ``` ```typescript import { Daytona } from '@daytona/sdk'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); await sandbox.git.clone('https://github.com/user/repo.git', { path: '/home/daytona/workspace/repo', username: 'git', password: 'personal_access_token', }); await sandbox.git.push('/home/daytona/workspace/repo', { username: 'git', password: 'personal_access_token' }); ``` ```bash curl '{toolboxProxyUrl}/{sandboxId}/git/push' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "path": "/home/daytona/workspace/repo", "username": "git", "password": "personal_access_token" }' ``` ## Permissions [#permissions] Git access runs through the toolbox of a sandbox. Access is governed by one project permission, which you can grant to an [organization role](/docs/organizations#roles) or an [API key](/docs/api-keys). A [sandbox access token](/docs/sandboxes#create-an-access-token) with the toolbox:git operation grants the same access to a single sandbox, without an API key. The sandbox read permission alone does not grant toolbox access. | **Permission** | **Grants** | | --------------------- | ---------------------------------------------------------- | | **`write:sandboxes`** | Run every Git operation, including clone, status, commit, push, pull, and branch management | # Language Server Protocol (/docs/language-server-protocol) Language Server Protocol (LSP) support is available through LSP server instances created from a sandbox. A language server runs inside the sandbox and analyzes the project's code, so your application gets IDE-grade code intelligence for code that never leaves the sandbox. An LSP server covers code completions, file open and close notifications, document symbols, and project-wide symbol search. Each server instance is scoped to one language and one project directory. Python and TypeScript are the supported language IDs; the matching server binary (pylsp or typescript-language-server) must be installed in the sandbox image, otherwise starting the server fails with an LSP server unavailable error. ## Use cases [#use-cases] LSP servers are used when an application needs code intelligence for code that stays in a sandbox. - **Coding agents.** An agent searches workspace symbols to find where a function or class is defined before it edits code. Each match carries the file URI and the line range, so the agent opens the right file at the right line. The query goes to the language server as is, so the matching rules are those of the server for the language. - **Browser-based editors.** An editor in a web application shows completions and an outline of the open file. The language server computes both in the sandbox, next to the code. Each file is read once, when it is opened, and later changes on disk are not sent to the server. - **Completions for generated code.** An agent or an editor requests completions at a position to fill in names that exist in the project. A trigger character, such as a dot, tells the server how the completion started. Positions are zero-based, and character offsets count UTF-16 code units within the line. - **Code that stays in the sandbox.** The language server reads files from the sandbox filesystem. Your application gets code intelligence without copying the source code out of the sandbox. Daytona does not install language servers, so the server binary must be in the sandbox image and on its path. - **Projects with several languages.** Each server covers one language and one project directory. A sandbox runs a Python server for one directory and a TypeScript server for another. The TypeScript server also covers JavaScript. ## Workflow [#workflow] Follow this order when using LSP in a sandbox: 1. Start a server for a language ID and a project path 2. Open a file on the server before requesting its completions or symbols 3. Request completions, document symbols, or workspace symbols from the server 4. Close the file when you finish with it 5. Stop the server when it is no longer needed ## Create LSP servers [#create-lsp-servers] Create a sandbox whose image includes the language server, then start the server for a project directory. Daytona does not install language servers: the binary must be in the image and on its path. Create the project directory in the image or before starting the server. ```python from daytona import Daytona from daytona.v2 import ImageBuilder # Create a sandbox from an image that ships pylsp daytona = Daytona() sandbox = daytona.v2.create_from_build( ImageBuilder.from_dockerfile( "FROM python:3.12-slim\n" "RUN pip install --no-cache-dir python-lsp-server\n" "RUN mkdir -p /workspace/project\n" ) ) # Write a file for the examples on this page sandbox.fs.write_text( "/workspace/project/main.py", "class MyClass:\n def method_one(self):\n return 1\n\nMyClass().\n", ) # Start the Python language server for the project server = sandbox.lsp.start("python", "/workspace/project") ``` | **Parameter** | **Type** | **Description** | | ----------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- | | `language_id` | str | Sets the language of the server: `"python"` or `"typescript"`. `"python"` runs `pylsp`. `"typescript"` runs `typescript-language-server` for TypeScript and JavaScript. | | `path_to_project` | str | Sets the project directory. | - The request requires the `write:sandboxes` permission. ```typescript import { Daytona } from '@daytona/sdk' import { ImageBuilder } from '@daytona/sdk/v2' // Create a sandbox from an image that ships typescript-language-server const daytona = new Daytona() const sandbox = await daytona.v2.createFromBuild( ImageBuilder.fromDockerfile( 'FROM node:20\nRUN npm install -g typescript@5 typescript-language-server\nRUN mkdir -p /workspace/project\n', ), ) // Write a file for the examples on this page await sandbox.fs.writeText( '/workspace/project/main.ts', 'class MyClass {\n methodOne(): number {\n return 1\n }\n}\n\nnew MyClass().\n', ) // Start the TypeScript language server for the project const server = await sandbox.lsp.start('typescript', '/workspace/project') ``` | **Parameter** | **Type** | **Description** | | --------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- | | `languageId` | string | Sets the language of the server: `'python'` or `'typescript'`. `'python'` runs `pylsp`. `'typescript'` runs `typescript-language-server` for TypeScript and JavaScript. | | `pathToProject` | string | Sets the project directory. | - The request requires the `write:sandboxes` permission. - The image needs TypeScript 5: `typescript-language-server` does not start with TypeScript 7. ## Start LSP servers [#start-lsp-servers] Start a language server for a language and a project directory. Starting a server for a language and directory that already has a running server reuses that server. The other operations never start a server implicitly; until the server is started, they fail with a not started error. ```python server = sandbox.lsp.start("python", "/workspace/project") # Now ready for LSP operations ``` | **Parameter** | **Type** | **Description** | | ----------------- | -------- | ------------------------------------------------------------------------------------- | | `path_to_project` | str | Sets the absolute path of the project directory. The server uses the path as its workspace root. | ```typescript const server = await sandbox.lsp.start('typescript', '/workspace/project') // Now ready for LSP operations ``` | **Parameter** | **Type** | **Description** | | --------------- | -------- | ------------------------------------------------------------------------------------- | | `pathToProject` | string | Sets the absolute path of the project directory. The server uses the path as its workspace root. | ```bash curl '{toolboxProxyUrl}/{sandboxId}/lsp/start' \ --request POST \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "languageId": "python", "pathToProject": "/workspace/project" }' ``` | **Field** | **Type** | **Description** | | --------------- | -------- | ----------------------------------------------------------------------------------------- | | `languageId` | string | Sets the language of the server: `python` or `typescript`. This field is required. | | `pathToProject` | string | Sets the absolute path of the project directory. The server uses the path as its workspace root. This field is required. | - The request requires the `write:sandboxes` permission. - `{toolboxProxyUrl}` is the `toolbox_proxy_url` field of the [sandbox](/docs/sandboxes#get-a-sandbox). ## Stop LSP servers [#stop-lsp-servers] Stop a language server. Stopping sends the server a shutdown request and ends its process, which frees one of the sandbox's server slots. A sandbox runs at most 16 language servers at once. ```python # When done with LSP features server.stop() ``` ```typescript // When done with LSP features await server.stop() ``` ```bash curl '{toolboxProxyUrl}/{sandboxId}/lsp/stop' \ --request POST \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "languageId": "python", "pathToProject": "/workspace/project" }' ``` ## Code completions [#code-completions] Get completion candidates at a position in an open file, computed from the content sent when the file was opened. Character offsets count UTF-16 code units within the line. ```python completions = server.completions( "file:///workspace/project/main.py", {"line": 4, "character": 10}, ) for item in completions.items: print(f"Completion: {item.label}") ``` - The request requires the `write:sandboxes` permission. - Position values are zero-based, so `line: 0` is the first line. - Call `open_document()` on the file before requesting completions. ```typescript const completions = await server.completions( 'file:///workspace/project/main.ts', { line: 6, character: 14, }, ) completions.items.forEach((item) => { console.log(`Completion: ${item.label}`) }) ``` | **Parameter** | **Type** | **Description** | | ------------- | ------------- | ------------------------------------------------------------------------------------------------------------------- | | `position` | LspPosition | Sets the position in the file. Position values are zero-based, so `line: 0` is the first line. `line` and `character` must be non-negative integers. Other values throw `BadRequestError` before the request is sent. | - The request requires the `write:sandboxes` permission. - Call `openDocument()` on the file before requesting completions. ```bash curl '{toolboxProxyUrl}/{sandboxId}/lsp/completions' \ --request POST \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "languageId": "python", "pathToProject": "/workspace/project", "position": { "character": 10, "line": 4 }, "uri": "file:///workspace/project/main.py" }' ``` - The request requires the `write:sandboxes` permission. - Position values are zero-based, so `line: 0` is the first line. - Call `POST /lsp/did-open` on the file before requesting completions. ### Completion context [#completion-context] Pass a completion context to tell the language server how the completion was triggered. The trigger kind is the completion trigger kind number from the Language Server Protocol specification. Set the trigger character when a typed character, such as a dot, opened the completion. Without a context, the server receives none. ```python from daytona.v2 import LspCompletionContext completions = server.completions( "file:///workspace/project/main.py", {"line": 4, "character": 10}, context=LspCompletionContext(trigger_kind=2, trigger_character="."), ) ``` ```typescript const completions = await server.completions( 'file:///workspace/project/main.ts', { line: 6, character: 14 }, { context: { triggerKind: 2, triggerCharacter: '.' } }, ) ``` ```bash curl '{toolboxProxyUrl}/{sandboxId}/lsp/completions' \ --request POST \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "languageId": "python", "pathToProject": "/workspace/project", "uri": "file:///workspace/project/main.py", "position": { "character": 10, "line": 4 }, "context": { "triggerKind": 2, "triggerCharacter": "." } }' ``` ### Completion item fields [#completion-item-fields] | **Field** | **Description** | | ------------------- | ------------------------------------------------------------------------------------------------------------------------ | | `label` | Text shown for the item. Always present. | | `kind` | LSP `CompletionItemKind` number, for example `3` for a function or `6` for a variable. | | `detail` | Extra information such as a type signature. | | `documentation` | Either a plain string or a `MarkupContent` object with `kind` (`plaintext` or `markdown`) and `value`. | | `sortText` | String to sort by instead of `label`. The Python SDK names it `sort_text`. | | `filterText` | String to filter by instead of `label`. The Python SDK names it `filter_text`. | | `insertText` | Text to insert instead of `label`. The Python SDK names it `insert_text`. | ## File notifications [#file-notifications] ### Open file [#open-file] Open a file on the language server. The file's content is read from the sandbox filesystem and sent to the server, which works from it: later changes on disk are not sent. ```python # Notify server that a file is open server.open_document("file:///workspace/project/main.py") ``` - The request requires the `write:sandboxes` permission. - The file must exist in the sandbox and be at most 1 MiB. ```typescript // Notify server that a file is open await server.openDocument('file:///workspace/project/main.ts') ``` - The request requires the `write:sandboxes` permission. - The file must exist in the sandbox and be at most 1 MiB. ```bash curl '{toolboxProxyUrl}/{sandboxId}/lsp/did-open' \ --request POST \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "languageId": "python", "pathToProject": "/workspace/project", "uri": "file:///workspace/project/main.py" }' ``` - The request requires the `write:sandboxes` permission. - The file must exist in the sandbox and be at most 1 MiB. ### Close file [#close-file] ```python # Notify server that a file is closed server.close_document("file:///workspace/project/main.py") ``` ```typescript // Notify server that a file is closed await server.closeDocument('file:///workspace/project/main.ts') ``` ```bash curl '{toolboxProxyUrl}/{sandboxId}/lsp/did-close' \ --request POST \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "languageId": "python", "pathToProject": "/workspace/project", "uri": "file:///workspace/project/main.py" }' ``` ## Document symbols [#document-symbols] ```python symbols = server.document_symbols("file:///workspace/project/main.py") for symbol in symbols: print(f"Symbol: {symbol.name}, Kind: {symbol.kind}") ``` ```typescript const symbols = await server.documentSymbols('file:///workspace/project/main.ts') symbols.forEach((symbol) => { console.log(`Symbol: ${symbol.name}, Kind: ${symbol.kind}`) }) ``` ```bash curl '{toolboxProxyUrl}/{sandboxId}/lsp/document-symbols?languageId=python&pathToProject=/workspace/project&uri=file:///workspace/project/main.py' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ## Workspace symbols [#workspace-symbols] Search the project for symbols that match a query string. The query is passed to the language server as is, so the matching rules are those of the server for the language. ```python # pylsp does not support workspace symbols: start a typescript server, in a sandbox # whose image ships typescript-language-server as in the TypeScript tab of Create LSP servers ts_server = sandbox.lsp.start("typescript", "/workspace/project") ts_server.open_document("file:///workspace/project/main.ts") symbols = ts_server.workspace_symbols("MyClass") for symbol in symbols: print(f"Found: {symbol.name} in {symbol.location.uri}") ``` - The request requires the `write:sandboxes` permission. - The server must be a `typescript` server: `pylsp` does not support workspace symbols. - Open a file of the project on the server before searching. ```typescript const symbols = await server.workspaceSymbols('MyClass') symbols.forEach((symbol) => { console.log(`Found: ${symbol.name} in ${symbol.location.uri}`) }) ``` - The request requires the `write:sandboxes` permission. - The server must be a `typescript` server: `pylsp` does not support workspace symbols. - Open a file of the project on the server before searching. ```bash curl '{toolboxProxyUrl}/{sandboxId}/lsp/workspacesymbols?query=MyClass&languageId=typescript&pathToProject=/workspace/project' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` - The request requires the `write:sandboxes` permission. - The server must be a `typescript` server: `pylsp` does not support workspace symbols. - Open a file of the project on the server before searching. ## Symbol fields [#symbol-fields] Document symbols and workspace symbols return the same flat symbol shape. Hierarchical document symbol answers from the language server are reduced to the same three fields: nested children are dropped, and a symbol without a location gets an empty URI and a zero range. | **Field** | **Description** | | ---------------------- | ---------------------------------------------------------------------------------------------------------- | | `name` | Symbol name. | | `kind` | LSP `SymbolKind` number, for example `5` for a class, `6` for a method, `12` for a function. | | `location.uri` | `file://` URI of the document that declares the symbol. | | `location.range` | `start` and `end` positions, each with zero-based `line` and `character`. | ## Errors [#errors] The SDKs raise these errors with the codes in the following table, and the Toolbox API returns them in the `code` field. An error that the language server returns for a request reaches you as `BAD_REQUEST`, with the server's message after the name of the LSP method. | **Code** | **Meaning** | **What to do** | | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | **`LSP_SERVER_UNAVAILABLE`** | The image has no binary for the language server, the binary could not run, or 16 language servers already run in the sandbox. | Install the server in the image, or stop a server you no longer need. | | **`LSP_NOT_STARTED`** | No server runs for the language and project directory: it was not started, it was stopped, or it exited. | Start the server. | | **`BAD_REQUEST`** | The language ID is not `python` or `typescript` (a stop request returns `LSP_NOT_STARTED` instead), a required query parameter is missing, the file to open cannot be read or is larger than 1 MiB, or the language server answered with an error. | Check the language ID and the file. For a language server error, read the message: it names the LSP method. | | **`REQUEST_TIMEOUT`** | The language server did not answer within 30 seconds. | Retry the request, or stop and start the server. | | **`UNPROCESSABLE_ENTITY`** | The API request body is missing a required field or has a value of the wrong type, such as a negative position. The SDKs check positions before they send the request. | Fix the request body. | ## Permissions [#permissions] Language server access runs through the toolbox of a sandbox. Access is governed by one project permission, which you can grant to an [organization role](/docs/organizations#roles) or an [API key](/docs/api-keys). A [sandbox access token](/docs/sandboxes#create-an-access-token) with the toolbox:lsp operation grants the same access to a single sandbox, without an API key. The sandbox read permission alone does not grant toolbox access. | **Permission** | **Grants** | | --------------------- | ------------------------------------------------------------------- | | **`write:sandboxes`** | Start and stop language servers and request completions and symbols | # Code Execution (/docs/code-execution) Daytona runs Python, TypeScript, and JavaScript code in sandboxes through language kernels, so untrusted or generated code executes in isolation from your application. Every run is a code process that executes in a session with a language kernel. The kernel keeps state between runs in the same session, so variables, imports, and functions defined in one run are available in the next. Runs use a shared kernel per language by default; isolated runs and interpreter contexts give code its own kernel. To run shell commands and manage long-running processes, see [process execution](/docs/process-execution). To follow a run's output live, see [log streaming](/docs/log-streaming). ## Use cases [#use-cases] Code execution is used when an application runs Python, TypeScript, or JavaScript that it did not write or does not trust. - **AI-generated code.** An agent writes code, runs it in the sandbox, and reads the output and errors to correct its next attempt. The code runs isolated from your application. Each result also holds the exit status of the process. - **Data analysis.** The kernel keeps data, imports, and functions in memory between runs, so each step builds on the previous one, as in a notebook. Runs without a context share one kernel per language, so later runs in that language see the same data. The first run in a language installs the kernel, so that run can take longer than later ones. - **Charts and tables.** Runs that plot or display data return charts and tables as artifacts with the result. Each artifact is keyed by MIME type, so an application renders it in the right format. A flag on each result tells the value of the last expression apart from displayed outputs. - **Code interpreters for users.** Each user or conversation gets its own interpreter context, so state from one does not reach another. A context has its own kernel, working directory, and environment. Its kernel uses memory even while idle, until the application [deletes the context](#delete-a-context). - **One-off runs.** An isolated kernel runs code with no state from earlier runs. The session is deleted after the run, so nothing the code defines reaches other runs. An isolated run cannot be combined with an interpreter context. ## Run code [#run-code] Run code in a sandbox. Runs without a context share one kernel per language, so state from one run is available to later runs in that language. The default language is Python. The result contains the standard output and standard error, rich outputs, the exception if the code raised one, and the exit status of the process. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() response = sandbox.run_code(''' def greet(name): return f"Hello, {name}!" print(greet("Daytona")) ''') print(response.logs.stdout) ``` | **Parameter** | **Type** | **Description** | | ------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------- | | `code` | str | Sets the code to run. This parameter is required. | | `language` | str | Sets the language: `python`, `typescript`, or `javascript`. The default is `python`. | | `context` | InterpreterContext | Runs the code in an [interpreter context](#interpreter-contexts) instead of the shared kernel. | | `isolated` | bool | Runs the code in a [temporary kernel](#run-code-in-an-isolated-kernel). The default is `False`. | | `cwd` | str | Sets the working directory of the shared kernel. Only the run that starts the kernel sets it, and later runs ignore it. To run code in another directory, use an [interpreter context](#interpreter-contexts) or an [isolated run](#run-code-in-an-isolated-kernel). | | `env` | Mapping\[str, str\] | Sets environment variables for the shared kernel. Only the run that starts the kernel sets them. A later run that passes different variables raises an error with code `UNSUPPORTED_OPERATION`. | | `timeout` | float | Sets how many seconds the client waits. On timeout, the kernel is interrupted and the result of the run is returned with exit code `1`; a run still queued behind another run on the same kernel returns reason `timed_out` without an exit code. The kernel keeps its state. `0` means no limit. The default is no limit. | The response has the following fields: | **Field** | **Description** | | --------- | --------------- | | `logs` | Holds the standard output and standard error. | | `results` | Holds the rich outputs. | | `error` | Holds the exception, if the code raised one. | | `process` | Holds the exit status of the process: `0` when the code finished, and `1` when it raised an exception or was interrupted. If the kernel stopped during the run, the reason is `lost` and the next run starts a new kernel without the earlier state. | ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() const response = await sandbox.runCode(` def greet(name): return f"Hello, {name}!" print(greet("Daytona")) `) console.log(response.logs.stdout) ``` | **Parameter** | **Type** | **Description** | | ------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------- | | `code` | string | Sets the code to run. This parameter is required. | | `language` | string | Sets the language: `'python'`, `'typescript'`, or `'javascript'`. The default is `'python'`. | | `context` | InterpreterContextReference \| InterpreterContextJSON | Runs the code in an [interpreter context](#interpreter-contexts) instead of the shared kernel. | | `isolated` | boolean | Runs the code in a [temporary kernel](#run-code-in-an-isolated-kernel). The default is `false`. | | `cwd` | string | Sets the working directory of the shared kernel. Only the run that starts the kernel sets it, and later runs ignore it. To run code in another directory, use an [interpreter context](#interpreter-contexts) or an [isolated run](#run-code-in-an-isolated-kernel). | | `env` | Record\ | Sets environment variables for the shared kernel. Only the run that starts the kernel sets them. A later run that passes different variables raises an error with code `UNSUPPORTED_OPERATION`. | | `timeoutSeconds` | number | Sets how many seconds the client waits. On timeout, the kernel is interrupted and the result of the run is returned with exit code `1`; a run still queued behind another run on the same kernel returns reason `timed_out` without an exit code. The kernel keeps its state. `0` means no limit. The default is no limit. | The response has the following fields: | **Field** | **Description** | | --------- | --------------- | | `logs` | Holds the standard output and standard error. | | `results` | Holds the rich outputs. | | `error` | Holds the exception, if the code raised one. | | `process` | Holds the exit status of the process: `0` when the code finished, and `1` when it raised an exception or was interrupted. If the kernel stopped during the run, the reason is `lost` and the next run starts a new kernel without the earlier state. | ```bash # Without sessionId the code runs on the shared per-language session "code-python" # waitMs holds the response for up to that many milliseconds while the process runs (capped at 600000). logs=text attaches the first log page. curl '{toolboxProxyUrl}/{sandboxId}/processes?waitMs=5000&logs=text' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "kind": "code", "language": "python", "code": "def greet(name):\n return f\"Hello, {name}!\"\n\nprint(greet(\"Daytona\"))" }' ``` | **Field** | **Type** | **Description** | | ----------- | -------- | ---------------------------------------------------------------------------------------------- | | `kind` | string | Sets the process kind. Use `code` for a code run. | | `language` | string | Sets the language: `python`, `typescript`, or `javascript`. With `sessionId`, the language must match the context, otherwise the request returns `BAD_REQUEST`. This field is required without `sessionId`. | | `code` | string | Sets the code to run. | | `sessionId` | string | Runs the code in an [interpreter context](#interpreter-contexts). Without `sessionId`, the code runs on the shared per-language session. | | `cwd` | string | Sets the working directory of the shared kernel. Only the run that starts the kernel sets it, and later runs ignore it. | | `env` | object | Sets environment variables for the shared kernel. Only the run that starts the kernel sets them. A later run that passes different variables returns `UNSUPPORTED_OPERATION`. Cannot be combined with `sessionId`. | The response has the following fields: | **Field** | **Description** | | --------- | --------------- | | `state` | The state of the process: `starting`, `provisioning`, `running`, or `terminal`. The first run in a language installs and starts the kernel. If that takes longer than `waitMs`, the state is not yet `terminal`. Wait with `GET /processes/{processId}/wait`, then read the logs. | - The request requires the `write:sandboxes` permission. - `{toolboxProxyUrl}` is the `toolbox_proxy_url` field of the [sandbox](/docs/sandboxes#get-a-sandbox). ### Artifacts [#artifacts] Rich outputs such as charts and tables are returned with the result, keyed by MIME type. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.process.run("pip install matplotlib numpy") code = ''' import matplotlib.pyplot as plt import numpy as np x = np.linspace(0, 10, 30) plt.plot(x, np.sin(x)) plt.title("Sine wave") plt.show() ''' response = sandbox.run_code(code) if response.error: print(response.error.name, response.error.value) for result in response.results: print(list(result.data)) # MIME types, for example ['image/png', 'text/plain'] ``` The response has the following fields: | **Field** | **Description** | | --------- | --------------- | | `results` | Holds the rich outputs. | | `text`, `html`, `png`, `svg`, `json` | Each of these fields of a result mirrors the matching MIME type in `data`. | | `is_main_result` | Is `True` for the value of the last expression and `False` for displayed outputs. | ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() await sandbox.process.run('pip install matplotlib numpy') const response = await sandbox.runCode(` import matplotlib.pyplot as plt import numpy as np x = np.linspace(0, 10, 30) plt.plot(x, np.sin(x)) plt.title("Sine wave") plt.show() `) if (response.error) { console.log(response.error.name, response.error.value) } for (const result of response.results) { console.log(Object.keys(result.data)) // MIME types, for example ['image/png', 'text/plain'] } ``` The response has the following fields: | **Field** | **Description** | | --------- | --------------- | | `results` | Holds the rich outputs. | | `text`, `html`, `png`, `svg`, `json` | Each of these fields of a result mirrors the matching MIME type in `data`. | | `isMainResult` | Is `true` for the value of the last expression and `false` for displayed outputs. | ```bash # Install the packages the code imports curl '{toolboxProxyUrl}/{sandboxId}/processes?waitMs=60000' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{"kind": "exec", "shellCommand": "pip install matplotlib numpy"}' # When the install is not terminal yet, wait until it exits; timeoutMs=0 waits without a limit curl '{toolboxProxyUrl}/{sandboxId}/processes/{processId}/wait?timeoutMs=0' \ --header 'Authorization: Bearer YOUR_API_KEY' # Rich outputs arrive as log frames on the "display" and "execute_result" channels. # Each frame's data is a JSON MIME bundle, for example {"image/png": "...", "text/plain": "..."}. curl '{toolboxProxyUrl}/{sandboxId}/processes?waitMs=60000&logs=text' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "kind": "code", "language": "python", "code": "import matplotlib.pyplot as plt\nimport numpy as np\n\nx = np.linspace(0, 10, 30)\nplt.plot(x, np.sin(x))\nplt.title(\"Sine wave\")\nplt.show()" }' ``` ## Run code in an isolated kernel [#run-code-in-an-isolated-kernel] Run code in a temporary kernel that starts with no state. Daytona creates a session with a new kernel, runs the code, and deletes the session after the run. Nothing the code defines is visible to other runs, and the code does not see state from the shared kernel or from interpreter contexts. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.run_code("value = 42") # The isolated kernel does not see variables from the shared kernel response = sandbox.run_code("print(value)", isolated=True) if response.error: print(response.error.name) # NameError ``` | **Parameter** | **Type** | **Description** | | ------------- | ----------------- | ------------------------------------------------------- | | `isolated` | bool | Runs the code in a temporary kernel when set to `True`. Each run starts a new kernel, so `timeout` must also cover the kernel start. If `timeout` runs out before the kernel starts, the call raises an error with code `REQUEST_TIMEOUT`. The default is `False`. This parameter cannot be combined with `context`. | | `cwd` | str | Sets the working directory of the temporary kernel. | | `env` | Mapping\[str, str\] | Sets environment variables of the temporary kernel. | ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() await sandbox.runCode('value = 42') // The isolated kernel does not see variables from the shared kernel const response = await sandbox.runCode('print(value)', { isolated: true }) console.log(response.error?.name) // NameError ``` | **Parameter** | **Type** | **Description** | | ------------- | ------------------------ | ------------------------------------------------------------ | | `isolated` | boolean | Runs the code in a temporary kernel when set to `true`. Each run starts a new kernel, so `timeoutSeconds` must also cover the kernel start. If `timeoutSeconds` runs out before the kernel starts, the call raises an error with code `REQUEST_TIMEOUT`. The default is `false`. This parameter cannot be combined with `context`. | | `cwd` | string | Sets the working directory of the temporary kernel. | | `env` | Record\ | Sets environment variables of the temporary kernel. | ```bash # Create a session with a new kernel curl '{toolboxProxyUrl}/{sandboxId}/sessions' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{"id": "isolated-run", "kernel": "python"}' # Run the code in that session curl '{toolboxProxyUrl}/{sandboxId}/processes?waitMs=60000&logs=text' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{"kind": "code", "language": "python", "sessionId": "isolated-run", "code": "print(value)"}' # Delete the session and its kernel curl '{toolboxProxyUrl}/{sandboxId}/sessions/isolated-run' \ --request DELETE \ --header 'Authorization: Bearer YOUR_API_KEY' ``` - The request requires the `write:sandboxes` permission. - Delete the session even when the run fails. ## Interpreter contexts [#interpreter-contexts] An interpreter context is a session with its own language kernel, working directory, and environment. State persists across runs in a context and is not shared with the shared kernel or other contexts. A context lives until deleted, so its kernel uses memory while idle. In the Toolbox API, a context is a [session](/docs/api/toolbox/sessions) that runs a language kernel. Shell sessions are not created through this endpoint; see [sessions](/docs/process-execution#session-operations). ### Create a context [#create-a-context] Create an interpreter context and run code in it. Run code with the context handle, or pass the handle to a run in the sandbox. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() ctx = sandbox.interpreter.create_context(language="python", env={"STAGE": "dev"}) try: ctx.run("value = 'stored in ctx'") result = sandbox.run_code("print(value)", context=ctx) print(result.logs.stdout) finally: ctx.close() ``` | **Parameter** | **Type** | **Description** | | ------------- | ------------------- | ----------------------------------------------------------------------- | | `language` | str | Sets the language: `python`, `typescript`, or `javascript`. This parameter is required. | | `context_id` | str | Sets the context ID for reconnecting later. The ID has at most `128` ASCII letters, digits, `.`, `_`, and `-`, and is unique in the sandbox. An ID that is in use returns `NAME_CONFLICT`. If omitted, an ID is generated. | | `cwd` | str | Sets the working directory of the kernel. | | `env` | Mapping\[str, str\] | Sets the kernel environment variables. Runs in a context do not accept `env`. | ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() const ctx = await sandbox.interpreter.createContext({ language: 'python', env: { STAGE: 'dev' } }) try { await ctx.run(`value = 'stored in ctx'`) const result = await sandbox.runCode(`print(value)`, { context: ctx }) console.log(result.logs.stdout) } finally { await ctx.close() } ``` | **Parameter** | **Type** | **Description** | | ------------- | ------------------------ | ----------------------------------------------------------------------- | | `language` | string | Sets the language: `'python'`, `'typescript'`, or `'javascript'`. This parameter is required. | | `contextId` | string | Sets the context ID for reconnecting later. The ID has at most `128` ASCII letters, digits, `.`, `_`, and `-`, and is unique in the sandbox. An ID that is in use returns `NAME_CONFLICT`. If omitted, an ID is generated. | | `cwd` | string | Sets the working directory of the kernel. | | `env` | Record\ | Sets the kernel environment variables. Runs in a context do not accept `env`. | ```bash # Create a context (session with a language kernel). Omit "id" to get a generated one. curl '{toolboxProxyUrl}/{sandboxId}/sessions' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{"id": "my-context", "kernel": "python", "env": {"STAGE": "dev"}}' # Run code in the context; state persists between runs curl '{toolboxProxyUrl}/{sandboxId}/processes?waitMs=60000&logs=text' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{"kind": "code", "language": "python", "sessionId": "my-context", "code": "value = \"stored in ctx\""}' curl '{toolboxProxyUrl}/{sandboxId}/processes?waitMs=60000&logs=text' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{"kind": "code", "language": "python", "sessionId": "my-context", "code": "print(value)"}' ``` | **Field** | **Type** | **Description** | | --------- | -------- | --------------------------------------------------------------------------------------- | | `id` | string | Sets the context ID for reconnecting later. The ID has at most `128` ASCII letters, digits, `.`, `_`, and `-`, and is unique in the sandbox. An ID that is in use returns `NAME_CONFLICT`. If omitted, an ID is generated. | | `kernel` | string | Sets the context language: `python`, `typescript`, or `javascript`. | | `env` | object | Sets the kernel environment variables. Runs in a context do not accept `env`. | ### List contexts [#list-contexts] List a sandbox's interpreter contexts. The list also includes the shared kernel of each language that has run code, with the ID `code-python`, `code-typescript`, or `code-javascript`. The list does not include shell sessions. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() for ctx in sandbox.interpreter.list_contexts(): print(f"Context: {ctx.context_id}, Language: {ctx.language}") ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() for (const ctx of await sandbox.interpreter.listContexts()) { console.log(`Context: ${ctx.contextId}, Language: ${ctx.language}`) } ``` ```bash curl '{toolboxProxyUrl}/{sandboxId}/sessions' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ### Reconnect to a context [#reconnect-to-a-context] Reconnect to an existing context from another worker or process. Contexts are addressed by ID, so any client with the sandbox ID and the context ID can run code in the context. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() # Worker A: create a context with a known ID ctx = sandbox.interpreter.create_context(language="python", context_id="my-context") ctx.run("x = 42") # Worker B: reconnect to the context by ID context = sandbox.interpreter.connect_context("my-context", language="python") response = context.run("print(x)") print(response.logs.stdout) # 42 # Or persist the context in worker A and reconnect from the saved dict, which carries the language saved = ctx.to_json() # {"sandboxId": "...", "contextId": "my-context", "language": "python"} context = sandbox.interpreter.connect_context(saved) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | ------------------------------------------------------------------------------------------------------ | | `language` | str | Sets the context language. This parameter is required when you pass an ID. Without `language`, `connect_context()` raises `DaytonaError` with code `BAD_REQUEST`. | - Running code in the context requires the `write:sandboxes` permission. - `connect_context()` takes a context ID with `language`, or the saved dict. - `connect_context()` sends no request, so it does not check that the context exists. ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() // Worker A: create a context with a known ID const ctx = await sandbox.interpreter.createContext({ contextId: 'my-context', language: 'python' }) await ctx.run('x = 42') // Worker B: reconnect to the context by ID const context = sandbox.interpreter.connectContext('my-context', 'python') const response = await context.run('print(x)') console.log(response.logs.stdout) // 42 // Or persist the context in worker A and reconnect from the saved object, which carries the language const saved = ctx.toJSON() // { sandboxId: '...', contextId: 'my-context', language: 'python' } const restored = sandbox.interpreter.connectContext(saved) ``` - Running code in the context requires the `write:sandboxes` permission. - `connectContext()` takes a context ID with the language, or the saved object. - `connectContext()` sends no request, so it does not check that the context exists. ```bash # Check that the context exists; an unknown ID returns 404 with SESSION_NOT_FOUND curl '{toolboxProxyUrl}/{sandboxId}/sessions/my-context' \ --header 'Authorization: Bearer YOUR_API_KEY' # Run code in the context from any client curl '{toolboxProxyUrl}/{sandboxId}/processes?waitMs=5000&logs=text' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{"kind": "code", "language": "python", "code": "print(x)", "sessionId": "my-context"}' ``` | **Field** | **Description** | | ----------------- | ---------------------------------------------------------------------------- | | `kernel` | The language kernel of the context. | | `active` | Whether the kernel of the context is running. When it is `false`, the next run starts a new kernel without the earlier state. | | `cwd` | The working directory the kernel started in. A change made by code is not tracked. | | `kernelProcessId` | The ID of the long-lived kernel process. | | `processIds` | The IDs of the runs in the context, in creation order. | ### Delete a context [#delete-a-context] Delete an interpreter context. Deleting a context shuts its kernel down and frees its memory. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() ctx = sandbox.interpreter.create_context(language="python") try: ctx.run("data = list(range(10_000_000))") finally: sandbox.interpreter.delete_context(ctx) ``` - The request requires the `write:sandboxes` permission. - `delete_context()` takes a context handle or a context ID. ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() const ctx = await sandbox.interpreter.createContext({ language: 'python' }) try { await ctx.run('data = list(range(10_000_000))') } finally { await sandbox.interpreter.deleteContext(ctx) } ``` - The request requires the `write:sandboxes` permission. - `deleteContext()` takes a context handle or a context ID. ```bash curl '{toolboxProxyUrl}/{sandboxId}/sessions/my-context' \ --request DELETE \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ## Errors [#errors] The SDKs raise these errors with the codes in the following table, and the Toolbox API returns them in the `code` field. An exception in the code itself is not an error of the request: it is returned in the result. | **Code** | **Meaning** | **What to do** | | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | | **`SESSION_NOT_FOUND`** | The context does not exist, or it was deleted. | Create the context again. Its earlier state is lost. | | **`NAME_CONFLICT`** | A context with this ID already exists in the sandbox. | Use another ID, or reconnect to the existing context. | | **`UNSUPPORTED_OPERATION`** | A run passed environment variables that its kernel does not take: a run on the shared kernel with variables other than those it started with, or an API run with `sessionId` and `env`. | Set the variables when you create an interpreter context. | | **`BAD_REQUEST`** | A context ID without a language, a language that does not match the context, an isolated run with a context, or an SDK run in a context that passes environment variables. | Pass the language of the context, run without `isolated`, or set the variables when you create the context. | | **`REQUEST_TIMEOUT`** | The timeout of an isolated run ran out before its kernel started. | Raise the timeout. | ## Permissions [#permissions] Code execution runs through the toolbox of a sandbox. Access is governed by one project permission, which you can grant to an [organization role](/docs/organizations#roles) or an [API key](/docs/api-keys). A [sandbox access token](/docs/sandboxes#create-an-access-token) with the toolbox:exec operation grants the same access to a single sandbox, without an API key. The sandbox read permission alone does not grant toolbox access. | **Permission** | **Grants** | | --------------------- | ---------------------------------------- | | **`write:sandboxes`** | Run code and manage interpreter contexts | # Process Execution (/docs/process-execution) Daytona runs shell commands and long-running processes in sandboxes. Commands run inside the sandbox, so untrusted or generated commands execute in isolation from your application. Process execution is available through the process module of a sandbox. Every command runs as a process: you can run a command and wait for its result, or start it in the background and control it through a handle. Sessions are shell processes that keep state, such as the working directory and environment variables, across the commands that run in them. To run Python, TypeScript, and JavaScript code, see [code execution](/docs/code-execution). For interactive terminals, see [pseudo terminal (PTY)](/docs/pty). For real-time logs from long-running processes, see [log streaming](/docs/log-streaming). ## Use cases [#use-cases] Process execution is used when the work in a sandbox is a shell command or a program instead of a code snippet. - **Build and test.** Package installs, compilers, and test runners run in the sandbox, and their exit code and output return to the application. When a run times out, the result has no exit code and the command keeps running. The result holds stdout, stderr, and the output of both channels in recorded order. - **Agent tools.** An agent runs shell commands as tools and reads their results. The commands run inside the sandbox, isolated from the application that hosts the agent. Python, TypeScript, and JavaScript snippets run through [code execution](/docs/code-execution) instead. - **Servers and workers.** A web server or worker starts in the background, and the application checks its state, reads its logs, or stops it through its handle. By default, an unnamed process keeps its record and logs for 10 minutes after it exits, and a named process keeps them until it is deleted. A retention option overrides either default. - **Multi-step shell work.** A session keeps the working directory and environment variables, so a sequence of commands runs as it does in one terminal. Commands in a session run one at a time and in order. A session survives pause and resume, but not stop and start. - **Reconnects.** An application reconnects to a process it started earlier and continues to read its output. Any client with the sandbox ID and the process ID can wait for the process, read its logs, or stop it. A process name resolves only while the process runs, and the ID still works after it exits. ## Command execution [#command-execution] ### Execute commands [#execute-commands] Run a command and wait for it to exit. The result holds the exit code and output. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() response = sandbox.process.run("ls -la") print(response.exit_code, response.stdout) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `timeout` | float | Sets how many seconds `run()` waits. When the timeout elapses, `reason` is `"timed_out"`, `exit_code` is `None`, and the command keeps running. Without it, `run()` waits until the command exits. | The response has the following fields: | **Field** | **Description** | | --------- | --------------- | | `stdout` | Holds the output of the stdout channel. | | `stderr` | Holds the output of the stderr channel. | | `output` | Holds the output of both channels in the order it was recorded. Writes to stdout and stderr that happen close together can appear out of order. | ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() const response = await sandbox.process.run('ls -la') console.log(response.exitCode, response.stdout) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `timeoutSeconds` | number | Sets how many seconds `run()` waits. When the timeout elapses, `reason` is `'timed_out'`, `exitCode` is `undefined`, and the command keeps running. Without it, `run()` waits until the command exits. | The response has the following fields: | **Field** | **Description** | | --------- | --------------- | | `stdout` | Holds the output of the stdout channel. | | `stderr` | Holds the output of the stderr channel. | | `output` | Holds the output of both channels in the order it was recorded. Writes to stdout and stderr that happen close together can appear out of order. | ```bash daytona sandbox exec {sandboxId} -- ls -la ``` - The request requires the `write:sandboxes` permission. - Arguments after `--` run without a shell. - To use shell syntax, wrap the command in `bash -c '...'`. - Pass the `--timeout` flag to wait longer than its default of `10m`. - When `--timeout` elapses, the CLI exits with code `8` and the command keeps running. ```bash # waitMs parks the response until the process exits; values above 600000 wait 600000. # logs=text attaches the first log page. curl '{toolboxProxyUrl}/{sandboxId}/processes?waitMs=5000&logs=text' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{"kind": "exec", "shellCommand": "ls -la"}' ``` - The request requires the `write:sandboxes` permission. - `{toolboxProxyUrl}` is the `toolbox_proxy_url` field of the [sandbox](/docs/sandboxes#get-a-sandbox). - When `waitMs` elapses before the process exits, the response has `state` set to `running`. - Wait for the process and read its logs with separate requests. - The attached log page holds up to `1000` frames, and output written in quick succession is recorded as one frame. - Read longer output from `/processes/{processId}/logs`. ### Set the user and shell [#set-the-user-and-shell] Run a command as a specific user or with a specific shell. The user must exist in the image and the shell must be installed. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() response = sandbox.process.run("whoami", user="nobody", shell="bash") print(response.output) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------- | | `user` | str | Sets the user that runs the command. The user must exist in the image. | | `shell` | str | Sets the shell that runs the command. The shell must be installed in the image. The default is `bash`, or `sh` when `bash` is not installed. | ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() const response = await sandbox.process.run('whoami', { user: 'nobody', shell: 'bash' }) console.log(response.output) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------- | | `user` | string | Sets the user that runs the command. The user must exist in the image. | | `shell` | string | Sets the shell that runs the command. The shell must be installed in the image. The default is `bash`, or `sh` when `bash` is not installed. | ```bash daytona sandbox exec {sandboxId} --user nobody -- bash -c whoami ``` - The request requires the `write:sandboxes` permission. - `exec` has no shell flag, so pass the shell as the program. ```bash curl '{toolboxProxyUrl}/{sandboxId}/processes?waitMs=5000&logs=text' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{"kind": "exec", "shellCommand": "whoami", "user": "nobody", "shell": "bash"}' ``` ### Update the environment [#update-the-environment] Set or remove environment variables for every process started in the sandbox after the update, including PTYs, sessions, and the git commands that [git operations](/docs/git-operations) run. Running processes and sessions keep their environment. Removing a variable affects only variables set through an earlier update; variables defined by the image stay. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() # Processes started after this call inherit the change sandbox.update_env({"LOG_LEVEL": "debug"}, unset=["HTTP_PROXY"]) response = sandbox.process.run("echo $LOG_LEVEL") print(response.stdout) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------------------- | ------------------------------------------------------- | | `env` | Mapping\[str, str\] | Adds or replaces variables. Each `KEY=VALUE` entry must be smaller than 128 KiB. The sandbox's added environment, which holds the variables set at creation, by secrets, by the platform, and by all updates, is at most 1 MiB in total, counting one extra byte per variable. An update that would grow it past 1 MiB is rejected; unset variables you no longer need to make room. On Windows, the existing environment plus the update is also capped at 32,767 UTF-16 characters. On macOS, it is capped at 512 KiB, half of `ARG_MAX`, and each variable counts 9 bytes in addition to its `KEY=VALUE` text. | | `unset` | Sequence\[str\] | Removes variables. This parameter is keyword only. | ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() // Processes started after this call inherit the change await sandbox.updateEnv({ LOG_LEVEL: 'debug' }, { unset: ['HTTP_PROXY'] }) const response = await sandbox.process.run('echo $LOG_LEVEL') console.log(response.stdout) ``` | **Parameter** | **Type** | **Description** | | ------------- | ------------------------ | ----------------------------- | | `env` | Record\ | Adds or replaces variables. Each `KEY=VALUE` entry must be smaller than 128 KiB. The sandbox's added environment, which holds the variables set at creation, by secrets, by the platform, and by all updates, is at most 1 MiB in total, counting one extra byte per variable. An update that would grow it past 1 MiB is rejected; unset variables you no longer need to make room. On Windows, the existing environment plus the update is also capped at 32,767 UTF-16 characters. On macOS, it is capped at 512 KiB, half of `ARG_MAX`, and each variable counts 9 bytes in addition to its `KEY=VALUE` text. | | `unset` | string\[\] | Removes variables. | ```bash # Processes started after this call inherit the change curl '{toolboxProxyUrl}/{sandboxId}/env' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{"env": {"LOG_LEVEL": "debug"}, "unset": ["HTTP_PROXY"]}' ``` | **Field** | **Type** | **Description** | | --------- | ---------- | ----------------------------- | | `env` | object | Adds or replaces variables. Each `KEY=VALUE` entry must be smaller than 128 KiB. The sandbox's added environment, which holds the variables set at creation, by secrets, by the platform, and by all updates, is at most 1 MiB in total, counting one extra byte per variable. An update that would grow it past 1 MiB is rejected; unset variables you no longer need to make room. On Windows, the existing environment plus the update is also capped at 32,767 UTF-16 characters. On macOS, it is capped at 512 KiB, half of `ARG_MAX`, and each variable counts 9 bytes in addition to its `KEY=VALUE` text. | | `unset` | string\[\] | Removes variables. | ### Execute interactive commands [#execute-interactive-commands] Run a command that reads input. Start the command with stdin open, write input to it, and close stdin when the command has all its input. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() handle = sandbox.process.start("tr a-z A-Z", stdin="open") # Send input to the command, then end it handle.write_stdin("hello\n") handle.close_stdin() wait = handle.wait() page = handle.logs() for frame in page.items: print(f"[{frame.channel}]: {frame.data}") print(wait.exit_code) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------------- | | `stdin` | str | Sets the stdin of the command to `"open"` or `"closed"`. The default is `"closed"`. | - The request requires the `write:sandboxes` permission. - Write the input and close stdin while the command runs, because a process that has exited does not accept input. ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() const handle = await sandbox.process.start('tr a-z A-Z', { stdin: 'open', }) // Send input to the command, then end it await handle.writeStdin('hello\n') await handle.closeStdin() const wait = await handle.wait() const page = await handle.logs() for (const frame of page.items) { console.log(`[${frame.channel}]:`, frame.data) } console.log(wait.exitCode) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------------- | | `stdin` | string | Sets the stdin of the command to `'open'` or `'closed'`. The default is `'closed'`. | - The request requires the `write:sandboxes` permission. - Write the input and close stdin while the command runs, because a process that has exited does not accept input. ```bash # Piped input is written to the command's stdin, followed by end of input printf 'hello\n' | daytona sandbox exec {sandboxId} -- tr a-z A-Z ``` ```bash # Start a command with stdin open curl '{toolboxProxyUrl}/{sandboxId}/processes' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "kind": "exec", "shellCommand": "tr a-z A-Z", "stdin": "open" }' # Send input to the process and close stdin curl '{toolboxProxyUrl}/{sandboxId}/processes/{processId}/stdin' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "data": "hello\n", "eof": true }' # Get process logs curl '{toolboxProxyUrl}/{sandboxId}/processes/{processId}/logs' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` | **Field** | **Type** | **Description** | | --------- | -------- | ------------------- | | `stdin` | string | Sets the stdin of the command to `open` or `closed`. The default is `closed`. | | **Field** | **Type** | **Description** | | --------- | --------- | ------------------------------------- | | `eof` | boolean | Closes stdin after writing `data` when set to `true`. | - The request requires the `write:sandboxes` permission. - Send the last input with `eof` set to `true` while the command runs, because a process that has exited does not accept input. ## Process control [#process-control] ### Start a background process [#start-a-background-process] Start a process without waiting for it to exit. The SDK returns a handle that you can use to wait for, read logs from, and stop the process. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() handle = sandbox.process.start("python -m http.server 8000", tag="web") print(handle.id) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------- | | `tag` | str | Groups the process with others for [listing](#list-processes) and [stopping processes by tag](#stop-processes-by-tag). The tag is 1 to 128 characters from `A-Z`, `a-z`, `0-9`, `.`, `_`, and `-`, and is not `.` or `..`. | ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() const handle = await sandbox.process.start('python -m http.server 8000', { tag: 'web' }) console.log(handle.id) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------- | | `tag` | string | Groups the process with others for [listing](#list-processes) and [stopping processes by tag](#stop-processes-by-tag). The tag is 1 to 128 characters from `A-Z`, `a-z`, `0-9`, `.`, `_`, and `-`, and is not `.` or `..`. | ```bash # Start a detached process (no waitMs). Returns 201 with the process record. curl '{toolboxProxyUrl}/{sandboxId}/processes' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{"kind": "exec", "shellCommand": "python -m http.server 8000", "tag": "web"}' ``` | **Field** | **Type** | **Description** | | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `keepLogs` | string | Sets how long the record and logs are kept after the process exits. With `on_exit_ttl`, the record and logs are removed 10 minutes after the process exits. The default is `on_exit_ttl` without `name` and `until_cleanup` with `name`. | | `tag` | string | Groups the process with others for [listing](#list-processes) and [stopping processes by tag](#stop-processes-by-tag). The tag is 1 to 128 characters from `A-Z`, `a-z`, `0-9`, `.`, `_`, and `-`, and is not `.` or `..`. It applies to `exec`, `pty`, and `session` processes. A `code` process cannot have a tag, and a command in a session takes the tag of the session. | ### List processes [#list-processes] List the processes in a sandbox. Filter the list by state, kind, session, name, PID, or tag. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() running = sandbox.process.list(state="running") for info in running.items: print(info.id, info.name, info.state, info.pid) # Only the processes started with the tag web = sandbox.process.list(tag="web") ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() const running = await sandbox.process.list({ state: 'running' }) for (const info of running.items) { console.log(info.id, info.name, info.state, info.pid) } // Only the processes started with the tag const web = await sandbox.process.list({ tag: 'web' }) ``` ```bash # Filters: --state running|terminal|all, --kind, --session-id, --name, --pid daytona sandbox process list {sandboxId} --state running ``` ```bash # Filters: state=running|terminal|all, kind, sessionId, name, pid, tag curl '{toolboxProxyUrl}/{sandboxId}/processes?state=running' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ### Process states [#process-states] | **State** | **Meaning** | | ------------------ | ----------------------------------------------------------------------------------------------------- | | **`starting`** | The record exists; the process has not been spawned yet. | | **`provisioning`** | [Code execution](/docs/code-execution) only: the language kernel is being installed or started. Progress is reported on the `setup` log channel. | | **`running`** | The process has a PID and is executing. | | **`terminal`** | The process has finished. `reason`, `exitCode`, and `signal` describe how. | | **Reason** | **Meaning** | | --------------- | ------------------------------------------------------------------------------------------------------------- | | **`exited`** | Exited on its own; `exitCode` is set. A code execution that raised an exception exits with `1`. | | **`signaled`** | Killed by a signal; `signal` is set. `wait` reports bare names (`TERM`, `KILL`), the API reports `SIGTERM`, `SIGKILL`. | | **`timed_out`** | The `timeoutMs` set at start elapsed; the process was killed with `SIGKILL`. Also returned by `wait` itself when its own long-poll window elapses first, with no `exitCode`. | | **`lost`** | The process disappeared without the daemon observing its exit, for example after a sandbox stop and start, or when its session was deleted while it was still running. | | **`failed`** | The process could not be started or ran into a daemon-side error. | ### Log retention [#log-retention] Choose how long a process record and its logs are kept after the process exits. The policy is set when the process starts. Once a record is removed, the process can no longer be waited on or read. See [log streaming](/docs/log-streaming#log-retention) for size caps and eviction. | **Policy** | **Behavior** | | ------------------- | ----------------------------------------------------------------------------------------------- | | **`until_cleanup`** | Kept until the process is deleted (`DELETE /processes/{id}`). Default for API requests that set `name`; the SDK `pty` namespace also uses it. | | **`on_exit_ttl`** | Kept for 10 minutes after exit, then removed. Default for API requests without `name` and for the SDK `start` and `run` methods; `run` does not accept `none`. | | **`none`** | Logs are discarded as soon as the process exits and can no longer be read. The record is kept for 10 minutes, so `wait` still returns the exit result. | ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() # Keep the record and logs until delete() is called handle = sandbox.process.start("pip list", keep_logs="until_cleanup") handle.wait() for frame in handle.logs().items: print(frame.data, end="") handle.delete() ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------- | | `keep_logs` | str | Sets how long the record and logs are kept after the process exits: `"until_cleanup"`, `"on_exit_ttl"`, or `"none"`. The default is `"on_exit_ttl"`. | ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() // Keep the record and logs until delete() is called const handle = await sandbox.process.start('pip list', { keepLogs: 'until_cleanup' }) await handle.wait() for (const frame of (await handle.logs()).items) { process.stdout.write(frame.data) } await handle.delete() ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------- | | `keepLogs` | string | Sets how long the record and logs are kept after the process exits: `'until_cleanup'`, `'on_exit_ttl'`, or `'none'`. The default is `'on_exit_ttl'`. | ```bash # Keep the record and logs until DELETE curl '{toolboxProxyUrl}/{sandboxId}/processes' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{"kind": "exec", "shellCommand": "pip list", "keepLogs": "until_cleanup"}' # Read logs; limit defaults to 1000, and values outside 1 to 5000 are clamped to that range curl '{toolboxProxyUrl}/{sandboxId}/processes/{processId}/logs' \ --header 'Authorization: Bearer YOUR_API_KEY' # Remove the record and logs curl '{toolboxProxyUrl}/{sandboxId}/processes/{processId}' \ --request DELETE \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ### Wait for a process [#wait-for-a-process] Wait for a process to finish, or until a timeout elapses. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() handle = sandbox.process.start("pip install requests") # Wait up to 2 minutes; without timeout, wait() blocks until the process is terminal result = handle.wait(timeout=120) print(result.reason, result.exit_code) ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() const handle = await sandbox.process.start('pip install requests') // Wait up to 2 minutes; without timeout, wait() blocks until the process is terminal const result = await handle.wait({ timeoutSeconds: 120 }) console.log(result.reason, result.exitCode) ``` ```bash # Wait up to 2 minutes; exits with the process exit code, 128 plus the signal number if a # signal stopped it (130 for INT, 143 for TERM, 137 for KILL), or 8 if the timeout elapses # first or the process hit its own timeout daytona sandbox process wait {sandboxId} {processId} --timeout 2m ``` ```bash # Long-poll for the terminal state. Omitting timeoutMs waits 60 s; 0 waits until terminal. curl '{toolboxProxyUrl}/{sandboxId}/processes/{processId}/wait?timeoutMs=120000' \ --header 'Authorization: Bearer YOUR_API_KEY' # Response when the process exits: # {"exitCode": 0, "reason": "exited"} # Response when the wait window elapses first: # {"reason": "timed_out"} ``` ### Stop a process [#stop-a-process] Stop a running process by sending it a signal. The SDKs send the terminate signal. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() handle = sandbox.process.start("python -m http.server 8000") # Sends SIGTERM handle.kill() ``` | **Parameter** | **Type** | **Description** | | ---------------- | ------------ | ---------------------------------------------------------------------------------------------- | | `signal` | SignalName | Sets the signal to send: `TERM`, `KILL`, `INT`, `HUP`, `QUIT`, `USR1`, or `USR2`. The default is `"TERM"`. | | `escalate_after` | float | Sends `escalate_to` if the process is still running after this many seconds. The value is at most `600`. | | `escalate_to` | SignalName | Sets the signal sent after `escalate_after`. The default is `"KILL"`. | ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() const handle = await sandbox.process.start('python -m http.server 8000') // Sends SIGTERM await handle.kill() ``` | **Parameter** | **Type** | **Description** | | --------------- | --------------- | ------------------------------------------------------------------------------------------------------ | | `signal` | ProcessSignal | Sets the signal to send: `'TERM'`, `'KILL'`, `'INT'`, `'HUP'`, `'QUIT'`, `'USR1'`, or `'USR2'`. | | `escalateAfterSeconds` | number | Sends `escalateTo` if the process is still running after this many seconds. The value is at most `600`. | | `escalateTo` | ProcessSignal | Sets the signal sent after `escalateAfterSeconds`. The default is `'KILL'`. | ```bash daytona sandbox process signal {sandboxId} {processId} TERM # Send KILL daytona sandbox process kill {sandboxId} {processId} ``` | **Flag** | **Type** | **Description** | | ------------------ | -------- | --------------------------------------------------------------------------------------------------------------- | | `--escalate-after` | string | Sends `--escalate-to` if the process is still running after this delay. The value is a duration such as `5s`, at most `10m`. | | `--escalate-to` | string | Sets the second signal, sent after `--escalate-after`. The default is `KILL`. This flag works only together with `--escalate-after`. | - The request requires the `write:sandboxes` permission. - Signal names have no `SIG` prefix, and the accepted names are `TERM`, `KILL`, `INT`, `HUP`, `QUIT`, `USR1`, and `USR2`. ```bash curl '{toolboxProxyUrl}/{sandboxId}/processes/{processId}/signals' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{"signal": "SIGTERM"}' ``` | **Field** | **Type** | **Description** | | ----------------- | --------- | -------------------------------------------------------------------------------------- | | `signal` | string | Sets the signal to send, with the `SIG` prefix. An empty value sends `SIGTERM`. | | `escalateAfterMs` | integer | Sends `escalateTo` if the process is still running after this delay. The value is at most `600000`. | | `escalateTo` | string | Sets the signal sent after `escalateAfterMs`. The default is `SIGKILL`. | ### Stop processes by tag [#stop-processes-by-tag] Stop every process started with a tag, and everything those processes started, including descendants that detached and the survivors of tagged processes that already exited. The call returns once none of them is running, with the IDs of the tagged processes it stopped. Processes whose records were deleted or expired are stopped too but not listed, so an empty list does not mean nothing was stopped. The call does not delete records or logs; they are kept for as long as the `keepLogs` setting of each process allows. The tag can be used again right after the call. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.process.start("python -m http.server 8000", tag="web") sandbox.process.start("python -m http.server 8001", tag="web") stopped = sandbox.process.kill_all(tag="web", timeout=30) print(stopped) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------- | | `tag` | str | Sets the tag of the processes to stop. This parameter is required. | | `timeout` | float | Sets how many seconds to wait for the processes to exit, more than `0` and at most `60`. Fractions are allowed. A value outside the range raises `BadRequestError` before any request is sent. The default is `10`. | - The request requires the `write:sandboxes` permission. - macOS sandboxes, and Linux sandboxes without process containment, cannot stop processes by tag. - When processes are still running at the timeout, or another start or stop under the tag is in progress, the call fails. Calling it again is safe. ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() await sandbox.process.start('python -m http.server 8000', { tag: 'web' }) await sandbox.process.start('python -m http.server 8001', { tag: 'web' }) const stopped = await sandbox.process.killAll({ tag: 'web', timeoutSeconds: 30 }) console.log(stopped) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------- | | `tag` | string | Sets the tag of the processes to stop. This parameter is required. | | `timeoutSeconds` | number | Sets how many seconds to wait for the processes to exit, more than `0` and at most `60`. A value outside the range throws `BadRequestError` before any request is sent. The default is `10`. | - The request requires the `write:sandboxes` permission. - macOS sandboxes, and Linux sandboxes without process containment, cannot stop processes by tag. - When processes are still running at the timeout, or another start or stop under the tag is in progress, the call fails. Calling it again is safe. ```bash curl '{toolboxProxyUrl}/{sandboxId}/processes:kill' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{"tag": "web", "timeoutMs": 30000}' ``` | **Field** | **Type** | **Description** | | --------- | -------- | --------------- | | `tag` | string | Sets the tag of the processes to stop. This field is required. | | `timeoutMs` | integer | Sets how many milliseconds to wait for the processes to exit, from `1` to `60000`. The default is `10000`. | The response has the following fields: | **Field** | **Description** | | --------- | --------------- | | `processIds` | The tagged processes that were running when the call started, and exited tagged processes that still had descendants running. | - The request requires the `write:sandboxes` permission. - macOS sandboxes, and Linux sandboxes without process containment, cannot stop processes by tag. - When processes are still running at `timeoutMs`, or another start or stop under the tag is in progress, the request fails. Repeating it is safe. ### Reconnect to a process [#reconnect-to-a-process] Reconnect to a process from another worker or process. Processes are addressed by ID, so any client with the sandbox ID and the process ID can wait for, read logs from, and stop the process. To reconnect to an interpreter context, see [reconnect to a context](/docs/code-execution#reconnect-to-a-context). ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() # Worker A: start the process and persist the handle handle = sandbox.process.start("pip install requests") saved = handle.to_json() # {"sandboxId": "...", "processId": "...", "kind": "exec"} # Worker B: reconnect and wait for the same process handle = sandbox.process.connect(saved) result = handle.wait() ``` - The request requires the `write:sandboxes` permission. - `connect()` takes the saved dict or a process ID. - A process name resolves only while the process runs. - After the process exits, reconnect by ID. ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() // Worker A: start the process and persist the handle const handle = await sandbox.process.start('pip install requests') const saved = handle.toJSON() // { sandboxId: '...', processId: '...', kind: 'exec' } // Worker B: reconnect and wait for the same process const reconnected = sandbox.process.connect(saved) const result = await reconnected.wait() ``` - The request requires the `write:sandboxes` permission. - `connect()` takes the saved object or a process ID. - A process name resolves only while the process runs. - After the process exits, reconnect by ID. ```bash # --timeout defaults to 10m; raise it for long-running processes daytona sandbox process wait {sandboxId} {processId} --timeout 1h # Attach to the live output stream daytona sandbox process attach {sandboxId} {processId} ``` ```bash curl '{toolboxProxyUrl}/{sandboxId}/processes/{processId}/wait' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` | **Field** | **Type** | **Description** | | ----------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `timeoutMs` | integer | Sets how long the request waits for the process to exit. Without it, the request returns after 60 seconds with `{"reason": "timed_out"}` if the process is still running. Repeat the request, or pass `0` to wait until the process exits. | ### Entrypoint process [#entrypoint-process] Get the details and logs of the sandbox entrypoint. It runs as a system process, so you can read it like any other process but not signal, write to, or delete it. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() # Entrypoint process details info = sandbox.process.get("entrypoint") print(f"Command: {info.argv or info.shell_command}") # Entrypoint logs handle = sandbox.process.connect("entrypoint") for frame in handle.logs().items: print(f"[{frame.channel}]: {frame.data}") ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() // Entrypoint process details const info = await sandbox.process.get('entrypoint') console.log('Command:', info.argv ?? info.shellCommand) // Entrypoint logs const handle = sandbox.process.connect('entrypoint') for (const frame of (await handle.logs()).items) { console.log(`[${frame.channel}]:`, frame.data) } ``` ```bash # Get entrypoint process details daytona sandbox process get {sandboxId} entrypoint # Get entrypoint logs daytona sandbox process logs {sandboxId} entrypoint # Control-plane entrypoint logs daytona sandbox logs {sandboxId} --entrypoint ``` ```bash # Get entrypoint process details curl '{toolboxProxyUrl}/{sandboxId}/processes/entrypoint' \ --header 'Authorization: Bearer YOUR_API_KEY' # Get entrypoint logs curl '{toolboxProxyUrl}/{sandboxId}/processes/entrypoint/logs' \ --header 'Authorization: Bearer YOUR_API_KEY' # Control-plane entrypoint logs curl 'https://api.daytona.com/sandboxes/{sandboxId}/logs' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ## Session operations [#session-operations] A session is a long-lived shell that runs the commands you send to it. Commands in a session run one at a time, in order, and share the shell state, such as the working directory, exported variables, and functions. To run commands in parallel, use separate sessions or background processes. A session is a long-running shell process, and each command in it is an ordinary process with its own logs, exit code, timeout, and signals. Interrupting a command stops only that command, and the session keeps running. Sessions survive pause and resume, but not stop and start. [Interpreter contexts](/docs/code-execution#interpreter-contexts) run a language kernel instead of a shell. ### Create a session [#create-a-session] Create a shell session. The working directory and environment variables of the session apply to all of its commands. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() session = sandbox.process.create_session(cwd="/tmp", env={"CI": "1"}, name="build-session") print(session.id) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------- | | `cwd` | str | Sets the working directory of the shell. The default is the image's `WORKDIR`. When the image declares none, the default is the home directory of the `user` set at sandbox creation, or the daemon working directory when no user is set or the home directory does not exist. On macOS, the default is the home directory of that user. | | `env` | Mapping\[str, str\] | Sets environment variables applied when the shell starts. | | `shell` | str | Sets the path or name of the shell. On Linux and macOS, it must be a POSIX shell: `bash`, `sh`, `dash`, `zsh`, or `ksh`. The shell must be installed in the image. | | `login` | bool | Starts a login shell when set to `True`. | | `name` | str | Sets a name that commands can use in place of the session ID while the session is running. Names are unique among running processes. | | `tag` | str | Sets the tag of the session. Every command in the session takes it, for [listing](#list-processes) and [stopping processes by tag](#stop-processes-by-tag). | ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() const session = await sandbox.process.createSession({ cwd: '/tmp', env: { CI: '1' }, name: 'build-session' }) console.log(session.id) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------- | | `cwd` | string | Sets the working directory of the shell. The default is the image's `WORKDIR`. When the image declares none, the default is the home directory of the `user` set at sandbox creation, or the daemon working directory when no user is set or the home directory does not exist. On macOS, the default is the home directory of that user. | | `env` | Record\ | Sets environment variables applied when the shell starts. | | `shell` | string | Sets the path or name of the shell. On Linux and macOS, it must be a POSIX shell: `bash`, `sh`, `dash`, `zsh`, or `ksh`. The shell must be installed in the image. | | `login` | boolean | Starts a login shell when set to `true`. | | `name` | string | Sets a name that commands can use in place of the session ID while the session is running. Names are unique among running processes. | | `tag` | string | Sets the tag of the session. Every command in the session takes it, for [listing](#list-processes) and [stopping processes by tag](#stop-processes-by-tag). | ```bash curl '{toolboxProxyUrl}/{sandboxId}/processes' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{"kind": "session", "cwd": "/tmp", "env": {"CI": "1"}, "name": "build-session"}' ``` | **Field** | **Type** | **Description** | | --------- | --------- | --------------- | | `kind` | string | Sets the kind to `session`. | | `cwd` | string | Sets the working directory of the shell. The default is the image's `WORKDIR`. When the image declares none, the default is the home directory of the `user` set at sandbox creation, or the daemon working directory when no user is set or the home directory does not exist. On macOS, the default is the home directory of that user. | | `env` | object | Sets environment variables applied when the shell starts. | | `shell` | string | Sets the path or name of the shell. On Linux and macOS, it must be a POSIX shell: `bash`, `sh`, `dash`, `zsh`, or `ksh`. The shell must be installed in the image. | | `login` | boolean | Starts a login shell when set to `true`. The default is `false`. | | `user` | string | Sets the user that the shell runs as. | | `name` | string | Sets a name that commands can use in place of the session ID while the session is running. Names are unique among running processes. | | `tag` | string | Sets the tag of the session. Every command in the session takes it, for [listing](#list-processes) and [stopping processes by tag](#stop-processes-by-tag). | The response has the following fields: | **Field** | **Description** | | --------- | ----------------------------------------------------------------------- | | `id` | The session ID. Commands pass it as `sessionId` to run in the session. | | `state` | The lifecycle state: `starting`, `provisioning`, `running`, or `terminal`. | | `cwd` | The current directory of the session shell. | ### Execute session commands [#execute-session-commands] Run commands in a session. Shell state set by one command is available to the next. A command timeout starts when the command starts, after any commands queued ahead of it. When the timeout elapses, Daytona stops the command and the session keeps running. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() with sandbox.process.create_session() as session: # Shell state persists between commands session.run("cd /tmp && export STAGE=dev") result = session.run("pwd && echo $STAGE", execution_timeout=30) print(result.stdout) # Interrupt one command; the session keeps running command = session.start("sleep 600") command.kill(signal="INT") ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------- | | `timeout` | float | Sets how many seconds `run()` waits for the command. | | `execution_timeout` | float | Sets how many seconds the command can run before Daytona stops it. The session keeps running. | | `name` | str | Sets a name for the command process. | ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() await using session = await sandbox.process.createSession() // Shell state persists between commands await session.run('cd /tmp && export STAGE=dev') const result = await session.run('pwd && echo $STAGE', { executionTimeoutSeconds: 30 }) console.log(result.stdout) // Interrupt one command; the session keeps running const command = await session.start('sleep 600') await command.kill({ signal: 'INT' }) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------- | | `timeoutSeconds` | number | Sets how many seconds `run()` waits for the command. | | `executionTimeoutSeconds` | number | Sets how many seconds the command can run before Daytona stops it. The session keeps running. | | `name` | string | Sets a name for the command process. | ```bash # Shell state persists between commands curl '{toolboxProxyUrl}/{sandboxId}/processes?waitMs=60000&logs=text' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{"kind": "exec", "shellCommand": "cd /tmp && export STAGE=dev", "sessionId": "build-session"}' curl '{toolboxProxyUrl}/{sandboxId}/processes?waitMs=60000&logs=text' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{"kind": "exec", "shellCommand": "pwd && echo $STAGE", "sessionId": "build-session", "timeoutMs": 30000}' ``` - The request requires the `write:sandboxes` permission. - A command with `sessionId` must be `kind: "exec"` with `shellCommand`, and `sessionId` takes the session ID or its name. - A command with `sessionId` cannot set `argv`, `cwd`, `env`, `shell`, `login`, or `user`, because the settings of the session apply. ### Reconnect to a session [#reconnect-to-a-session] Reconnect to a session from another worker or process. Sessions are addressed by ID, so any client with the sandbox ID and the session ID can run commands in the session and read its status. Reconnecting sends no request; the next call on the session does. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() # Worker A: create the session and persist it session = sandbox.process.create_session() session.run("cd /tmp") saved = session.to_json() # {"sandboxId": "...", "sessionId": "..."} # Worker B: reconnect and run in the same shell session = sandbox.process.connect_session(saved) result = session.run("pwd") ``` - `connect_session()` takes the saved dict or a session ID. - Reconnect through the process module of the sandbox the session belongs to; a saved session of another sandbox is refused before any request. ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() // Worker A: create the session and persist it const session = await sandbox.process.createSession() await session.run('cd /tmp') const saved = session.toJSON() // { sandboxId: '...', sessionId: '...' } // Worker B: reconnect and run in the same shell const reconnected = sandbox.process.connectSession(saved) const result = await reconnected.run('pwd') ``` - `connectSession()` takes the saved object or a session ID. - Reconnect through the process module of the sandbox the session belongs to; a saved session of another sandbox is refused before any request. ### Get session status [#get-session-status] Get the status of a session, including the current working directory of its shell, and list the commands that ran in it. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() session = sandbox.process.create_session() session.run("cd /tmp") info = session.get() print(info.state, info.cwd) listed = sandbox.process.list(session_id=session.id) for proc in listed.items: print(f"Process: {proc.id}, Command: {proc.shell_command}, Exit Code: {proc.exit_code}") ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() const session = await sandbox.process.createSession() await session.run('cd /tmp') const info = await session.get() console.log(info.state, info.cwd) const listed = await sandbox.process.list({ sessionId: session.id }) for (const proc of listed.items) { console.log(`Process: ${proc.id}, Command: ${proc.shellCommand}, Exit Code: ${proc.exitCode}`) } ``` ```bash # Get the session process daytona sandbox process get {sandboxId} {sessionId} # List processes in a session daytona sandbox process list {sandboxId} --session-id {sessionId} ``` ```bash # Get the session process curl '{toolboxProxyUrl}/{sandboxId}/processes/{sessionId}' \ --header 'Authorization: Bearer YOUR_API_KEY' # List processes in a session curl '{toolboxProxyUrl}/{sandboxId}/processes?sessionId={sessionId}' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ### List sessions [#list-sessions] List the shell sessions in a sandbox. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() session = sandbox.process.create_session() sessions = sandbox.process.list(kind="session") for proc in sessions.items: print(proc.id, proc.state) ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() const session = await sandbox.process.createSession() const sessions = await sandbox.process.list({ kind: 'session' }) for (const proc of sessions.items) { console.log(proc.id, proc.state) } ``` ```bash daytona sandbox process list {sandboxId} --kind session ``` ```bash curl '{toolboxProxyUrl}/{sandboxId}/processes?kind=session' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ### Get session command [#get-session-command] Get a command that ran in a session by its process ID. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() session = sandbox.process.create_session() session.run("echo hello") listed = sandbox.process.list(session_id=session.id) command = sandbox.process.get(listed.items[0].id) print(f"Command: {command.shell_command}, Exit Code: {command.exit_code}") ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() const session = await sandbox.process.createSession() await session.run('echo hello') const listed = await sandbox.process.list({ sessionId: session.id }) const command = await sandbox.process.get(listed.items[0].id) console.log(`Command: ${command.shellCommand}, Exit Code: ${command.exitCode}`) ``` ```bash daytona sandbox process get {sandboxId} {processId} ``` ```bash curl '{toolboxProxyUrl}/{sandboxId}/processes/{processId}' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ### Delete a session [#delete-a-session] Delete a session. This ends its shell, stops its running commands, and removes the records of its commands. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() session = sandbox.process.create_session() session.delete() ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() const session = await sandbox.process.createSession() await session.delete() ``` ```bash curl '{toolboxProxyUrl}/{sandboxId}/processes/{sessionId}' \ --request DELETE \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ## Resource management [#resource-management] A process kept with `until_cleanup` keeps its record and logs until you delete it. The API applies this policy to processes started with a `name`; the SDKs apply it only when you pass it. Delete such a process when you no longer need it; deleting stops the process if it is still running. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() handle = sandbox.process.start("sleep 3600", name="my-process", keep_logs="until_cleanup") try: pass # Do work... finally: handle.delete() # kills the process if it is still running ``` ```typescript import { Daytona } from '@daytona/sdk'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); const handle = await sandbox.process.start("sleep 3600", { name: "my-process", keepLogs: "until_cleanup" }); try { // Do work... } finally { await handle.delete(); // kills the process if it is still running } ``` ```bash # Delete a process record and its logs; a running process is killed first curl '{toolboxProxyUrl}/{sandboxId}/processes/{processId}' \ --request DELETE \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ## Permissions [#permissions] Process execution runs through the toolbox of a sandbox. Access is governed by one project permission, which you can grant to an [organization role](/docs/organizations#roles) or an [API key](/docs/api-keys). A [sandbox access token](/docs/sandboxes#create-an-access-token) with the toolbox:exec operation grants the same access to a single sandbox, without an API key. The sandbox read permission alone does not grant toolbox access. | **Permission** | **Grants** | | --------------------- | ----------------------------------------------------------------- | | **`write:sandboxes`** | Run commands, processes, and sessions, and update the environment | # Pseudo Terminal (PTY) (/docs/pty) Daytona provides pseudo terminal (PTY) capabilities through the process module in sandboxes. A PTY is a process started with the PTY kind: it runs under a virtual terminal so programs behave as if connected to a real terminal, with terminal size, line discipline, and interactive prompts. PTY processes are exposed through a sandbox's PTY namespace and share the handle API of other processes, described in [process execution](/docs/process-execution). ## Use cases [#use-cases] PTY sessions are used when a program expects a real terminal. - **Interactive development.** REPLs, debuggers, and editors that read keystrokes and redraw the screen run in a PTY session. The virtual terminal gives them a terminal size and line discipline, as a real terminal does. The terminal starts at 80 columns by 24 rows unless the start request sets a size. - **Terminals in web applications.** A browser terminal connects to a PTY session, sends keystrokes, and resizes the session with the window. On each resize, the program in the terminal receives a window size change signal and can redraw. Browsers authenticate the WebSocket connection with the daytona_token query parameter. - **Builds and tests.** A PTY session runs compilers, test runners, and deploy tools that show progress or colors only when attached to a terminal. Waiting for the session returns its exit code, and the CLI exits with the same code. If the wait time elapses first, the result reports a timeout with no exit code, and the session keeps running. - **Reconnects.** A client that reconnects replays the output from a cursor and sees what it missed. Every output frame carries a cursor, and a read with a cursor returns only the frames after it. Retention can evict old output, and a cursor into evicted output fails. - **Terminal agents.** An agent works in one interactive shell that keeps its working directory and variables between commands. It reads the output as a terminal shows it, including escape sequences. When a session timeout elapses, the session is killed and reports that it timed out. ## Start PTY session [#start-pty-session] Start a PTY session. Without a command, the session runs an interactive shell: the login shell of the user it runs as, or the first of bash, zsh, and sh found in the image. With a command, the session runs that command in the terminal instead. The terminal starts at 80 columns by 24 rows unless you set a size, and you can [resize](#resize-pty-session) it later. The SDKs and the CLI keep an exited session's record and output until [deleted](#kill-pty-session). ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() # Without a command the PTY runs an interactive shell; the terminal defaults to 80x24 handle = sandbox.pty.start() print(handle.id) ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() // Without a command the PTY runs an interactive shell; the terminal defaults to 80x24 const handle = await sandbox.pty.start() console.log(handle.id) ``` ```bash # The CLI needs a command, so this starts bash; requires a terminal, and the PTY takes its size daytona sandbox exec {sandboxId} --tty -- bash ``` | **Flag** | **Type** | **Description** | | ----------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `--timeout` | duration | Limits how long `exec` stays attached. When the limit elapses, the CLI exits with code `8` and the session keeps running. The default is `10m`. | - The request requires the `write:sandboxes` permission. - The CLI runs the arguments after `--` as a program, without a shell. - Wrap shell syntax in `bash -c '...'`. ```bash # Without shellCommand the PTY runs an interactive shell; terminal defaults to 80x24. # The SDKs set keepLogs to until_cleanup; the API default for unnamed processes is on_exit_ttl. curl '{toolboxProxyUrl}/{sandboxId}/processes' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{"kind": "pty", "stdin": "open", "keepLogs": "until_cleanup"}' ``` - The request requires the `write:sandboxes` permission. - `{toolboxProxyUrl}` is the `toolbox_proxy_url` field of the [sandbox](/docs/sandboxes#get-a-sandbox). ```python from daytona import Daytona from daytona.v2 import TerminalSize daytona = Daytona() sandbox = daytona.v2.create() handle = sandbox.pty.start("python3 -i", terminal=TerminalSize(cols=100, rows=40)) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------- | | `command` | str | Sets the command to run in the PTY. | | `terminal` | TerminalSize | Sets the terminal size. `cols` and `rows` are each from `1` to `65535`. The default is 80 columns by 24 rows. | | `cwd` | str | Sets the working directory of the command. | | `env` | Mapping\[str, str\] | Sets environment variables for the command. | | `name` | str | Sets the session name. See [name PTY session](#name-pty-session). | | `keep_logs` | KeepLogs | Sets the log retention policy. With `"on_exit_ttl"`, the record and output are removed 10 minutes after exit; with `"none"`, the output is discarded at exit. See [log retention](/docs/log-streaming#log-retention). The default is `"until_cleanup"`. | ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() const handle = await sandbox.pty.start('python3 -i', { terminal: { cols: 100, rows: 40 }, }) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `terminal` | TerminalSize | Sets the terminal size. `cols` and `rows` are each from `1` to `65535`. The default is 80 columns by 24 rows. | | `cwd` | string | Sets the working directory of the command. | | `env` | Record\ | Sets environment variables for the command. | | `name` | string | Sets the session name. See [name PTY session](#name-pty-session). | | `keepLogs` | KeepLogs | Sets the log retention policy. With `'on_exit_ttl'`, the record and output are removed 10 minutes after exit; with `'none'`, the output is discarded at exit. See [log retention](/docs/log-streaming#log-retention). The default is `'until_cleanup'`. | ```bash # The PTY takes the size of the local terminal; the CLI cannot set cols and rows daytona sandbox exec {sandboxId} --tty -- python3 -i ``` ```bash curl '{toolboxProxyUrl}/{sandboxId}/processes' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "kind": "pty", "shellCommand": "python3 -i", "stdin": "open", "terminal": {"cols": 100, "rows": 40} }' ``` | **Field** | **Type** | **Description** | | ---------- | -------- | ------------------------------------------------------------ | | `terminal` | object | Sets the terminal size with `cols` and `rows`. Both are required, and each is from `1` to `65535`. The field is accepted only with `kind: "pty"`. | ## Name PTY session [#name-pty-session] Name a PTY session. A name aliases the session ID, so another client can reach the session without knowing its ID. The name belongs to the session only while it runs: when the session exits, the name is released for reuse, and the session stays reachable by its ID only. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() handle = sandbox.pty.start(name="dev-shell") # Names are unique among live processes and resolve wherever an ID is accepted info = sandbox.process.get("dev-shell") ``` - The request requires the `write:sandboxes` permission. - A name has 1 to 128 characters of letters, digits, `.`, `_`, and `-`, and cannot be `.` or `..`. - The names `entrypoint` and `dockerd` are reserved for system processes. ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() const handle = await sandbox.pty.start(undefined, { name: 'dev-shell' }) // Names are unique among live processes and resolve wherever an ID is accepted const info = await sandbox.process.get('dev-shell') ``` - The request requires the `write:sandboxes` permission. - A name has 1 to 128 characters of letters, digits, `.`, `_`, and `-`, and cannot be `.` or `..`. - The names `entrypoint` and `dockerd` are reserved for system processes. ```bash # A second live process with the same name is rejected with 409 NAME_CONFLICT curl '{toolboxProxyUrl}/{sandboxId}/processes' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{"kind": "pty", "name": "dev-shell", "stdin": "open"}' # The name works as an alias for the process ID on every /processes/{id} route curl '{toolboxProxyUrl}/{sandboxId}/processes/dev-shell' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` - The request requires the `write:sandboxes` permission. - A name has 1 to 128 characters of letters, digits, `.`, `_`, and `-`, and cannot be `.` or `..`. - The names `entrypoint` and `dockerd` are reserved for system processes. ## Configure shell, user, and timeout [#configure-shell-user-and-timeout] Configure the shell, the user, and the timeout of a PTY session. A shell that cannot be found or a user that does not exist fails the start. When the timeout elapses, the session is killed and reports that it timed out. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() handle = sandbox.pty.start( shell="/bin/bash", # default: the user's login shell, then bash, zsh, sh user="root", # run as another user execution_timeout=600, # SIGKILL after 10 minutes; wait() reports reason "timed_out" ) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------------------------------------- | | `shell` | str | Sets the shell, as a path or a name looked up on `PATH`. | | `user` | str | Sets the user the session runs as. Without `shell`, the session runs through the user's login shell, so a user whose shell is `nologin` cannot run commands. The user must exist in `/etc/passwd` of the sandbox. | | `execution_timeout` | float | Sets how many seconds the session can run before Daytona kills it. | ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() const handle = await sandbox.pty.start(undefined, { shell: '/bin/bash', // default: the user's login shell, then bash, zsh, sh user: 'root', // run as another user executionTimeoutSeconds: 600, // SIGKILL after 10 minutes; wait() reports reason 'timed_out' }) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------------------------------------- | | `shell` | string | Sets the shell, as a path or a name looked up on `PATH`. | | `user` | string | Sets the user the session runs as. Without `shell`, the session runs through the user's login shell, so a user whose shell is `nologin` cannot run commands. The user must exist in `/etc/passwd` of the sandbox. | | `executionTimeoutSeconds` | number | Sets how many seconds the session can run before Daytona kills it. | ```bash curl '{toolboxProxyUrl}/{sandboxId}/processes' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "kind": "pty", "shell": "/bin/bash", "user": "root", "timeoutMs": 600000, "stdin": "open" }' ``` | **Field** | **Type** | **Description** | | ----------- | --------- | ------------------------------------------------------------------------------------------------------ | | `timeoutMs` | integer | Sets the session timeout in milliseconds. When the timeout elapses, the daemon sends `SIGKILL` and the record reports `reason: timed_out`. | ## Connect to PTY session [#connect-to-pty-session] Connect to an existing PTY session by its ID. Connecting creates a handle without contacting the sandbox; the handle sends input to the session, reads its output, resizes it, and stops it. A live connection streams output produced after it opens; to see earlier output, replay it from a cursor. ```python handle = sandbox.pty.connect(process_id) handle.write_stdin('echo "Reconnected"\n') # The Python SDK has no WebSocket attach. Use write_stdin() and # stream_logs() instead. ``` ```typescript const handle = sandbox.pty.connect(processId) const connection = await handle.attach() const decoder = new TextDecoder() ;(async () => { for await (const chunk of connection.readable) { process.stdout.write(decoder.decode(chunk)) } })() connection.write('echo "Reconnected"\n') ``` - The request requires the `write:sandboxes` permission. - `attach()` opens a WebSocket and needs a global `WebSocket` in the runtime. - Read earlier output with `logs()`. - If the session has already exited, the connection closes without output. ```bash daytona sandbox process attach {sandboxId} {processId} # Replay output from a previous log cursor before the live stream daytona sandbox process attach {sandboxId} {processId} --cursor {cursor} ``` | **Flag** | **Type** | **Description** | | ---------- | -------- | --------------------------------------------------------------- | | `--cursor` | string | Replays output from a previous log cursor before the live stream. Without this flag, the command shows only output produced after the attach. | ```bash # WebSocket endpoint: binary frames carry PTY output, # text or binary client messages are written to stdin. # Authenticate with an Authorization: Bearer header or ?daytona_token= (browsers). {toolboxWebSocketUrl}/{sandboxId}/processes/{processId}/attach # Pass ?cursor= to replay output from a previous log cursor before the live stream. # Close codes: 1008 "cursor expired" | "invalid cursor" | "slow consumer"; # a plain close when the process is already terminal (read scrollback from /logs). {toolboxWebSocketUrl}/{sandboxId}/processes/{processId}/attach?cursor={cursor} ``` - The request requires the `write:sandboxes` permission. - `{toolboxWebSocketUrl}` is the `toolbox_proxy_url` field of the [sandbox](/docs/sandboxes#get-a-sandbox), with `wss://` in place of `https://`. ## List PTY sessions [#list-pty-sessions] List PTY sessions, including retained exited ones; check each session's state. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() processes = sandbox.pty.list() for info in processes.items: print(f"PTY: {info.id} ({info.state})") if info.terminal: print(f" Size: {info.terminal.cols}x{info.terminal.rows}") print(f" Working directory: {info.cwd}") ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() const processes = await sandbox.pty.list() for (const info of processes.items) { console.log(`PTY: ${info.id} (${info.state})`) if (info.terminal) { console.log(` Size: ${info.terminal.cols}x${info.terminal.rows}`) } console.log(` Working directory: ${info.cwd}`) } ``` ```bash daytona sandbox process list {sandboxId} --kind pty ``` ```bash curl '{toolboxProxyUrl}/{sandboxId}/processes?kind=pty' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ## Get PTY session info [#get-pty-session-info] ```python info = handle.get() print(f"PTY: {info.id}") print(f"State: {info.state}") print(f"PID: {info.pid}") if info.terminal: print(f"Size: {info.terminal.cols}x{info.terminal.rows}") print(f"Working directory: {info.cwd}") if info.state == "terminal": print(f"Exit code: {info.exit_code}") ``` ```typescript const info = await handle.get() console.log(`PTY: ${info.id}`) console.log(`State: ${info.state}`) console.log(`PID: ${info.pid}`) console.log(`Size: ${info.terminal?.cols}x${info.terminal?.rows}`) console.log(`Working directory: ${info.cwd}`) if (info.state === 'terminal') { console.log(`Exit code: ${info.exitCode}`) } ``` ```bash daytona sandbox process get {sandboxId} {processId} ``` ```bash curl '{toolboxProxyUrl}/{sandboxId}/processes/{processId}' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ## Kill PTY session [#kill-pty-session] Stop a PTY session and remove it. Stopping sends a signal to the session's processes; removing deletes the session record and its output. An interactive shell ignores the default termination signal, so a session started without a command keeps running unless the signal escalates to a kill. Removing a session that is still running kills it first. ```python # Sends SIGTERM, then SIGKILL after 5 seconds if the session is still running handle.kill(escalate_after=5) # Removes the process record and logs handle.delete() ``` | **Parameter** | **Type** | **Description** | | ---------------- | ------------ | --------------------------------------------------------------------------------------------------- | | `signal` | SignalName | Sets the signal that `kill()` sends: `TERM`, `KILL`, `INT`, `HUP`, `QUIT`, `USR1`, or `USR2`. The default is `"TERM"`. | | `escalate_after` | float | Sends `escalate_to` if the session is still running after this delay. The delay is in seconds, at most `600`. | | `escalate_to` | SignalName | Sets the signal sent after `escalate_after`. The default is `"KILL"`. | ```typescript // Sends SIGTERM, then SIGKILL after 5 seconds if the session is still running await handle.kill({ escalateAfterSeconds: 5 }) // Removes the process record and logs await handle.delete() ``` | **Parameter** | **Type** | **Description** | | --------------- | --------------- | ----------------------------------------------------------------------------------------------------------- | | `signal` | ProcessSignal | Sets the signal that `kill()` sends: `'TERM'`, `'KILL'`, `'INT'`, `'HUP'`, `'QUIT'`, `'USR1'`, or `'USR2'`. | | `escalateAfterSeconds` | number | Sends `escalateTo` if the session is still running after this delay. The delay is in seconds, at most `600`. | | `escalateTo` | ProcessSignal | Sets the signal sent after `escalateAfterSeconds`. The default is `'KILL'`. | ```bash # Send SIGTERM, then SIGKILL after 5 seconds if the session is still running daytona sandbox process signal {sandboxId} {processId} TERM --escalate-after 5s # Or send SIGKILL; the CLI cannot remove the process record and logs daytona sandbox process kill {sandboxId} {processId} ``` | **Flag** | **Type** | **Description** | | ------------------ | -------- | --------------------------------------------------------------------------------------------------- | | `--escalate-after` | duration | Sends `--escalate-to` if the session is still running after this delay. The delay is a duration such as `5s`, at most `10m`. The flag is available only on `process signal`. | | `--escalate-to` | string | Sets the second signal, sent after `--escalate-after`. The default is `KILL`. The flag is available only on `process signal`. | - The request requires the `write:sandboxes` permission. - Signal names have no `SIG` prefix, and the accepted names are `TERM`, `KILL`, `INT`, `HUP`, `QUIT`, `USR1`, and `USR2`. ```bash # Send a signal curl '{toolboxProxyUrl}/{sandboxId}/processes/{processId}/signals' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{"signal": "SIGTERM"}' # Remove the process record and logs curl '{toolboxProxyUrl}/{sandboxId}/processes/{processId}' \ --request DELETE \ --header 'Authorization: Bearer YOUR_API_KEY' ``` | **Field** | **Type** | **Description** | | ----------------- | --------- | ------------------------------------------------------------------------------------------------- | | `signal` | string | Sets the signal to send, with the `SIG` prefix. An empty value sends `SIGTERM`. | | `escalateAfterMs` | integer | Sends `escalateTo` if the session is still running after this delay. The delay is at most `600000`. | | `escalateTo` | string | Sets the signal sent after `escalateAfterMs`, with the `SIG` prefix. The default is `SIGKILL`. | ### Delete a PTY session [#delete-a-pty-session] Delete a PTY session in one step: a running session gets a termination signal, then the session record and its output are removed. Deleting a non-PTY process fails and leaves it running. ```python sandbox.pty.delete(handle.id) ``` ```typescript await sandbox.pty.delete(handle.id) ``` ## Resize PTY session [#resize-pty-session] Resize the terminal of a running PTY session. The program in the terminal receives a window size change signal and can redraw at the new size. The session record reports the new size. ```python handle.resize(150, 40) ``` - The request requires the `write:sandboxes` permission. - `cols` and `rows` must be at least `1`. - You can resize only PTY sessions. ```typescript await handle.resize(150, 40) ``` - The request requires the `write:sandboxes` permission. - `cols` and `rows` must be at least `1`. - You can resize only PTY sessions. ```bash curl '{toolboxProxyUrl}/{sandboxId}/processes/{processId}/resize' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{"cols": 150, "rows": 40}' ``` - The request requires the `write:sandboxes` permission. - `cols` and `rows` must be at least `1`. - You can resize only PTY sessions. ## Send input [#send-input] Send input to a PTY session. Input reaches the terminal as if typed, so end each command with a newline. Control keys are bytes: send Ctrl+C as 0x03 and Ctrl+D as 0x04. A terminal has no separate end of input; to end input, send Ctrl+D. ```python handle.write_stdin("ls -la\n") ``` | **Parameter** | **Type** | **Description** | | ------------- | ------------------- | ------------------------------------------------------- | | `data` | Union\[str, bytes\] | Sets the input to send, as `str` or `bytes`. Bytes are sent base64 encoded. This parameter is required. | ```typescript await handle.writeStdin('ls -la\n') ``` | **Parameter** | **Type** | **Description** | | ------------- | ------------------------- | --------------------------------------------------------------------- | | `data` | string \| Uint8Array | Sets the input to send, as a `string` or a `Uint8Array`. A `Uint8Array` is sent base64 encoded. This parameter is required. | ```bash curl '{toolboxProxyUrl}/{sandboxId}/processes/{processId}/stdin' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{"data": "ls -la\n"}' ``` | **Field** | **Type** | **Description** | | ---------- | -------- | ---------------------------------- | | `encoding` | string | Sets the input encoding, `text` or `base64`. The default is `text`. | ## Read output [#read-output] Read one page of PTY output. A page holds up to 1,000 frames by default. To read past the first page, continue from a cursor as shown in [replay output from a cursor](#replay-output-from-a-cursor). ```python page = handle.logs() for frame in page.items: print(frame.data, end="") ``` | **Parameter** | **Type** | **Description** | | ------------- | ------------- | ------------------------------------------------------------------------------------------------- | | `limit` | int | Sets the page size. The daemon clamps the page size to `1` to `5000`. The default is `1000`. | | `encoding` | LogEncoding | Sets the output encoding. In text encoding, bytes that are not valid UTF-8 are replaced. Pass `"base64"` to get each frame's `data` as a standard base64 string of the raw bytes. The default is `"text"`. | - The request requires the `write:sandboxes` permission. - A read without a cursor starts at the first frame the session wrote, so it fails once retention evicts that frame; read from the oldest available cursor in the error instead. ```typescript const page = await handle.logs() for (const frame of page.items) { process.stdout.write(frame.data) } ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------------------------------------------------------------------------------------------- | | `limit` | number | Sets the page size. The daemon clamps the page size to `1` to `5000`. The default is `1000`. | | `encoding` | string | Sets the output encoding. In text encoding, bytes that are not valid UTF-8 are replaced. Pass `'base64'` to get each frame's `data` as a standard base64 string of the raw bytes. The default is `'text'`. | - The request requires the `write:sandboxes` permission. - A read without a cursor starts at the first frame the session wrote, so it fails once retention evicts that frame; read from the oldest available cursor in the error instead. ```bash daytona sandbox process logs {sandboxId} {processId} ``` - The request requires the `write:sandboxes` permission. - A read without a cursor starts at the first frame the session wrote, so it fails once retention evicts that frame; read from the oldest available cursor in the error instead. ```bash curl '{toolboxProxyUrl}/{sandboxId}/processes/{processId}/logs' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` | **Field** | **Type** | **Description** | | ---------- | --------- | ---------------------------------------------------------------------------------------------------------------- | | `limit` | integer | Sets the page size. The value is clamped to `1` to `5000`. The default is `1000`. | | `encoding` | string | Sets the output encoding, `text` or `base64`. Text replaces bytes that are not valid UTF-8. Base64 output is standard base64 with padding. The default is `text`. | - The request requires the `write:sandboxes` permission. - A read without a cursor starts at the first frame the session wrote, so it fails once retention evicts that frame; read from the `firstAvailableCursor` of the error instead. ## Replay output from a cursor [#replay-output-from-a-cursor] Replay PTY output from a cursor. Every output frame carries a cursor, and a read with a cursor returns the frames after it, so a client that saved the last cursor it processed can resume without gaps or duplicates. Retention can evict old output; a cursor that points into evicted output fails, and the error carries the oldest cursor still available. See [log retention](/docs/log-streaming#log-retention). ```python # Every frame carries a cursor; reading resumes strictly after it. An empty page means the read has caught up cursor = last_cursor while True: page = handle.logs(cursor=cursor) if not page.items: break for frame in page.items: print(frame.data, end="") cursor = frame.cursor ``` ```typescript // Every frame carries a cursor; reading resumes strictly after it. An empty page means the read has caught up let cursor = lastCursor for (;;) { const page = await handle.logs({ cursor }) if (page.items.length === 0) break for (const frame of page.items) { process.stdout.write(frame.data) cursor = frame.cursor } } ``` ```bash daytona sandbox process logs {sandboxId} {processId} --cursor {cursor} ``` ```bash # An evicted cursor returns 409 CURSOR_EXPIRED with firstAvailableCursor curl '{toolboxProxyUrl}/{sandboxId}/processes/{processId}/logs?cursor={cursor}' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ## Wait for completion [#wait-for-completion] Wait for a PTY session to exit. The result holds the exit code, the ending signal if any, and a reason: exited, killed by a signal, timed out, failed to start, or lost. If the wait time elapses first, the result reports a timeout with no exit code, and the session keeps running. ```python result = handle.wait(timeout=30) print(result.reason, result.exit_code) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | ----------------------------------------------------------------- | | `timeout` | float | Sets how long to wait, in seconds. Omit it or pass `0` to wait until the session exits. | ```typescript const result = await handle.wait({ timeoutSeconds: 30 }) console.log(result.reason, result.exitCode) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------------------------------------------------------------- | | `timeoutSeconds` | number | Sets how long to wait, in seconds. Omit it or pass `0` to wait until the session exits. | ```bash daytona sandbox process wait {sandboxId} {processId} --timeout 30s ``` ```bash curl '{toolboxProxyUrl}/{sandboxId}/processes/{processId}/wait?timeoutMs=30000' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` | **Field** | **Type** | **Description** | | ----------- | --------- | ---------------------------------------------------- | | `timeoutMs` | integer | Sets how long to wait, in milliseconds. `0` waits until the session exits. The default is `60000`. | The response has the following fields: | **Field** | **Description** | | ---------- | ---------------------------------------------------------------------------------------------------------------- | | `exitCode` | The exit code of the session. Omitted when the wait time elapses first. | | `reason` | Why the session ended: `exited`, `signaled`, `timed_out`, `lost`, or `failed`. `timed_out` when the wait time elapses first. | | `signal` | The signal name, such as `SIGKILL`. Omitted when none applies. | ## Interactive commands [#interactive-commands] Run several commands in one interactive shell. The shell keeps its state between commands, such as the working directory and variables. Read output while you send input; the output stream ends after the shell exits and all of its output is delivered. ```python import threading from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() handle = sandbox.pty.start() # Print output in the background def pump(): for event in handle.stream_logs(): if event.type == "log": print(event.frame.data, end="") reader = threading.Thread(target=pump, daemon=True) reader.start() for command in [ "pwd", "ls -la", "echo 'Hello from PTY'", "python3 -c 'print(2 + 2)'", "exit", ]: handle.write_stdin(command + "\n") result = handle.wait() reader.join(timeout=5) print(f"\nShell exited with code: {result.exit_code}") handle.delete() ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() const { handle, connection } = await sandbox.pty.attach() const decoder = new TextDecoder() const reader = (async () => { for await (const chunk of connection.readable) { process.stdout.write(decoder.decode(chunk)) } })() for (const command of [ 'pwd', 'ls -la', "echo 'Hello from PTY'", "python3 -c 'print(2 + 2)'", 'exit', ]) { connection.write(command + '\n') } const result = await handle.wait() await reader if (result.reason === 'exited') { console.log(`\nShell exited with code: ${result.exitCode}`) } await handle.delete() ``` - The request requires the `write:sandboxes` permission. - The connection streams output written after it opens, so the shell's first prompt can be missing; read it with `handle.logs()`. ## Long-running processes [#long-running-processes] Interrupt a running command from the terminal. Ctrl+C sent as input goes through the terminal, which interrupts the foreground command; the shell itself keeps running. Signaling the session instead targets the whole session, including the shell. See [kill PTY session](#kill-pty-session). ```python import time from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() handle = sandbox.pty.start() handle.write_stdin("for i in $(seq 1 100); do echo \"Line $i\"; sleep 1; done\n") time.sleep(5) handle.write_stdin("\x03") # Ctrl+C handle.write_stdin("exit\n") result = handle.wait() for frame in handle.logs().items: print(frame.data, end="") print(f"\nExit code: {result.exit_code}") handle.delete() ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() const { handle, connection } = await sandbox.pty.attach() const decoder = new TextDecoder() ;(async () => { for await (const chunk of connection.readable) { process.stdout.write(decoder.decode(chunk)) } })() connection.write('for i in $(seq 1 100); do echo "Line $i"; sleep 1; done\n') await new Promise((resolve) => setTimeout(resolve, 5000)) connection.write('\x03') // Ctrl+C connection.write('exit\n') const result = await handle.wait() if (result.reason === 'exited') { console.log(`\nExit code: ${result.exitCode}`) } await handle.delete() ``` ## Resource management [#resource-management] Remove a PTY session when you no longer need it. The SDKs keep an exited session's record and output until it is deleted, so delete it in a final block to remove it even when a step fails. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() handle = sandbox.pty.start() try: handle.write_stdin("echo hello\n") handle.write_stdin("exit\n") handle.wait(timeout=10) finally: handle.delete() ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() const { handle, connection } = await sandbox.pty.attach() try { connection.write('echo hello\n') connection.write('exit\n') await handle.wait({ timeoutSeconds: 10 }) } finally { connection.close() await handle.delete() } ``` ## Permissions [#permissions] A PTY session runs through the toolbox of a sandbox. Access is governed by one project permission, which you can grant to an [organization role](/docs/organizations#roles) or an [API key](/docs/api-keys). A [sandbox access token](/docs/sandboxes#create-an-access-token) with the toolbox:exec operation grants the same access to a single sandbox, without an API key. The sandbox read permission alone does not grant toolbox access. | **Permission** | **Grants** | | --------------------- | ------------------------------------------------ | | **`write:sandboxes`** | Start, connect to, resize, and kill PTY sessions | # Log Streaming (/docs/log-streaming) Log streaming lets you access and process logs of a running process in real time, or retrieve a snapshot of all logs produced so far. Use streaming for long-running or background commands. Use snapshots when you only need the current output. Every process started through the process module writes its output to a cursor-addressed log ledger. Each log frame carries a channel (stdout and stderr for commands, pty for PTY processes), the data, and a cursor you can use to resume reading from where you left off. See [log frames](#log-frames) for the full list of fields and channels. For entrypoint log streaming, see [entrypoint process](/docs/process-execution#entrypoint-process). To stream logs while sending input to a running command, see [execute interactive commands](/docs/process-execution#execute-interactive-commands). ## Use cases [#use-cases] Log streaming is used when an application needs the output of a process while the process still runs. - **Live output in a UI.** Build, test, or training output appears in a web application as the process writes it. Each frame carries a timestamp, so the UI shows when the output was written. A [PTY process](/docs/pty) sends its merged terminal output on one channel, escape sequences included. - **Agent feedback.** An agent reads the output of a long command as it arrives and stops the command early on an error. A stream sends new output as it is written and ends once the process exits. Its state event reports the exit code, signal, and reason of the process. - **Reconnects.** A client that loses its connection resumes from its last cursor. No frame is delivered twice, and no retained frame is missed. An SSE client sends the ID of the last event it received, and the daemon uses that ID as the cursor. - **Server logs.** The output of a background web server or worker is followed for as long as the process runs. When the server writes nothing, the daemon sends a keepalive every 15 seconds. The CLI follows the logs until the process exits, then exits with the exit code of the process. If the CLI timeout passes first, the CLI stops following and the process keeps running. - **Error handling.** Stdout and stderr arrive on separate channels, so an application handles errors apart from regular output. Order is kept within a channel, not across channels. The CLI writes stdout frames to its standard output and stderr frames to its standard error. ## Stream logs [#stream-logs] Stream the logs of a process. A stream replays the retained output from the beginning or from a cursor, then new output as it is written. It ends once the process exits and all output is delivered. While the process is silent, the daemon sends a keepalive every 15 seconds. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() handle = sandbox.process.start( 'for i in {1..5}; do echo "Step $i"; echo "Error $i" >&2; sleep 1; done' ) for event in handle.stream_logs(): if event.type == "log": print(f"[{event.frame.channel.upper()}]: {event.frame.data}", end="") ``` - The request requires the `write:sandboxes` permission. - `stream_logs()` does not reopen a dropped connection. - [Resume](#resume-a-stream) from the cursor of the last event instead. ```python import asyncio from daytona import AsyncDaytona async def main() -> None: async with AsyncDaytona() as daytona: sandbox = await daytona.v2.create() handle = await sandbox.process.start( 'for i in {1..5}; do echo "Step $i"; echo "Error $i" >&2; sleep 1; done' ) async for event in handle.stream_logs(): if event.type == "log": print(f"[{event.frame.channel.upper()}]: {event.frame.data}", end="") asyncio.run(main()) ``` - The request requires the `write:sandboxes` permission. - `stream_logs()` does not reopen a dropped connection. - [Resume](#resume-a-stream) from the cursor of the last event instead. ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() const handle = await sandbox.process.start( 'for i in {1..5}; do echo "Step $i"; echo "Error $i" >&2; sleep 1; done', ) for await (const event of handle.streamLogs()) { if (event.type === 'log') { process.stdout.write(`[${event.frame.channel.toUpperCase()}]: ${event.frame.data}`) } } ``` - The request requires the `write:sandboxes` permission. - `streamLogs()` does not reopen a dropped connection. - [Resume](#resume-a-stream) from the cursor of the last event instead. ```bash # Run a command and stream its stdout and stderr until it exits daytona sandbox exec {sandboxId} -- bash -c 'for i in {1..5}; do echo "Step $i"; echo "Error $i" >&2; sleep 1; done' # Follow the logs of a running process in real time (SSE) daytona sandbox process logs {sandboxId} {processId} --follow ``` - The request requires the `write:sandboxes` permission. - Pass the global `--timeout` flag to follow longer than its default of `10m`. - `--follow` supports only `table` and `json` output. ```bash # Start a process curl '{toolboxProxyUrl}/{sandboxId}/processes' \ --request POST \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "kind": "exec", "shellCommand": "for i in {1..5}; do echo \"Step $i\"; echo \"Error $i\" >&2; sleep 1; done" }' # Follow process logs in real time (SSE) curl -N '{toolboxProxyUrl}/{sandboxId}/processes/{processId}/logs?follow=true' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` - The request requires the `write:sandboxes` permission. - `{toolboxProxyUrl}` is the `toolbox_proxy_url` field of the [sandbox](/docs/sandboxes#get-a-sandbox). - The `limit` parameter does not apply to a follow stream. ### Stream events [#stream-events] Handle the events of a log stream. Each event carries a cursor, also sent as the event ID, so a client can resume after any event. A stream ends after its end event or its error event. | **Event** | **Payload** | **Meaning** | | ------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ | | **`log`** | A [log frame](#log-frames) | One chunk of process output. | | **`state`** | The process record with `exitCode`, `signal`, `reason`, and `cursor` | The process reached the `terminal` state. Sent once. Frames written before exit can still follow it. | | **`warning`** | `cursor`, `message`, `firstAvailableCursor` | The requested position was evicted by [log retention](#log-retention). The stream resumes from `firstAvailableCursor` on its own. | | **`eof`** | `cursor` | The process is terminal and every frame has been delivered. The stream closes after this event. | | **`error`** | `cursor`, `message` | The daemon failed to read the ledger. The stream closes after this event. The SDKs raise it as an error instead of yielding it. | ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() handle = sandbox.process.start("for i in {1..3}; do echo \"Step $i\"; sleep 1; done") # The generator returns after the eof event; a stream error is raised for event in handle.stream_logs(): if event.type == "log": print(f"[{event.frame.channel.upper()}]: {event.frame.data}", end="") elif event.type == "state": print(f"Exit code: {event.result.exit_code}, reason: {event.result.reason}") elif event.type == "warning": print(f"Older logs were evicted, resuming from {event.first_available_cursor}") elif event.type == "eof": print(f"Stream complete at cursor {event.cursor}") ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() const handle = await sandbox.process.start('for i in {1..3}; do echo "Step $i"; sleep 1; done') // The iterator returns after the eof event; a stream error is thrown for await (const event of handle.streamLogs()) { switch (event.type) { case 'log': process.stdout.write(`[${event.frame.channel.toUpperCase()}]: ${event.frame.data}`) break case 'state': console.log('Process finished:', event.result) break case 'warning': console.warn(`Older logs were evicted, resuming from ${event.firstAvailableCursor}`) break case 'eof': console.log('Stream complete at cursor', event.cursor) break } } ``` ```bash curl -N '{toolboxProxyUrl}/{sandboxId}/processes/{processId}/logs?follow=true' \ --header 'Authorization: Bearer YOUR_API_KEY' # event: log # id: djE6MQ # data: {"cursor":"djE6MQ","channel":"stdout","timestamp":1757756400000,"data":"Step 1\n"} # # : keepalive # # event: state # id: djE6Mw # data: {"id":"p_...","kind":"exec","state":"terminal","exitCode":0,"reason":"exited","cursor":"djE6Mw",...} # # event: eof # id: djE6Mw # data: {"cursor":"djE6Mw"} ``` ### Resume a stream [#resume-a-stream] Resume a stream from a cursor. A stream opened with a cursor starts strictly after that position, so no frame is delivered twice. An SSE client that reconnects sends the ID of the last event it received, and the daemon uses that ID in place of the cursor. If retention evicted the position, the stream warns and continues from the oldest retained frame. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() handle = sandbox.process.start("for i in {1..5}; do echo \"Step $i\"; sleep 1; done") # Stop early, remembering the cursor of the last frame processed last_cursor = None for event in handle.stream_logs(): if event.type != "log": continue print(event.frame.data, end="") last_cursor = event.cursor if event.frame.data.startswith("Step 3"): break # Resume strictly after the last frame seen for event in handle.stream_logs(cursor=last_cursor): if event.type == "log": print(event.frame.data, end="") ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() const handle = await sandbox.process.start('for i in {1..5}; do echo "Step $i"; sleep 1; done') // Stop early, remembering the cursor of the last event processed let lastCursor: string | undefined for await (const event of handle.streamLogs()) { lastCursor = event.cursor ?? lastCursor if (event.type !== 'log') continue process.stdout.write(event.frame.data) if (event.frame.data.startsWith('Step 3')) break } // Resume strictly after the last event seen for await (const event of handle.streamLogs({ cursor: lastCursor })) { if (event.type === 'log') process.stdout.write(event.frame.data) } ``` ```bash # --output json prints one frame per line, each with its cursor daytona sandbox process logs {sandboxId} {processId} --follow --cursor {cursor} --output json ``` ```bash # Resume with the cursor query parameter curl -N '{toolboxProxyUrl}/{sandboxId}/processes/{processId}/logs?follow=true&cursor={cursor}' \ --header 'Authorization: Bearer YOUR_API_KEY' # Resume with the SSE Last-Event-ID header; it takes precedence over cursor curl -N '{toolboxProxyUrl}/{sandboxId}/processes/{processId}/logs?follow=true' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Last-Event-ID: {cursor}' ``` ## Retrieve all existing logs [#retrieve-all-existing-logs] Read the logs a process has produced so far. A read returns one page and does not wait for new output. Output longer than one page needs [pagination](#paginate-logs). ```python # Logs produced up to the current point in time page = handle.logs() for frame in page.items: print(f"[{frame.channel.upper()}]: {frame.data}", end="") ``` - The request requires the `write:sandboxes` permission. - A page holds up to `1000` frames by default. - The daemon clamps the page size to the range `1` to `5000`. ```typescript // Logs produced up to the current point in time const page = await handle.logs() for (const frame of page.items) { process.stdout.write(`[${frame.channel.toUpperCase()}]: ${frame.data}`) } ``` - The request requires the `write:sandboxes` permission. - A page holds up to `1000` frames by default. - The daemon clamps the page size to the range `1` to `5000`. ```bash daytona sandbox process logs {sandboxId} {processId} ``` - The request requires the `write:sandboxes` permission. - A page holds up to `1000` frames by default. - The daemon clamps the page size to the range `1` to `5000`. ```bash curl '{toolboxProxyUrl}/{sandboxId}/processes/{processId}/logs' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` - The request requires the `write:sandboxes` permission. - A page holds up to `1000` frames by default. - The daemon clamps the page size to the range `1` to `5000`. ### Paginate logs [#paginate-logs] Read logs page by page. Pass the next cursor of a page to read the page after it. An empty page means the read has caught up with the output; a process that is still running can produce more. ```python from daytona import Daytona from daytona.v2 import LogFrame daytona = Daytona() sandbox = daytona.v2.create() handle = sandbox.process.start("seq 1 5000") handle.wait() frames: list[LogFrame] = [] cursor = None while True: page = handle.logs(cursor=cursor, limit=500) frames.extend(page.items) if not page.items or page.next_cursor == cursor: break cursor = page.next_cursor stdout = "".join(frame.data for frame in frames if frame.channel == "stdout") print(f"{len(frames)} frames, {len(stdout)} bytes of stdout") ``` - The request requires the `write:sandboxes` permission. - `LogPage` has no end-of-log flag. - Stop reading when a page is empty and the process has exited. ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() const handle = await sandbox.process.start('seq 1 5000') await handle.wait() const frames = [] let cursor: string | undefined for (;;) { const page = await handle.logs({ cursor, limit: 500 }) frames.push(...page.items) if (page.items.length === 0 || page.nextCursor === cursor) break cursor = page.nextCursor } const stdout = frames.filter((frame) => frame.channel === 'stdout').map((frame) => frame.data).join('') console.log(`${frames.length} frames, ${stdout.length} bytes of stdout`) ``` - The request requires the `write:sandboxes` permission. - `LogsPage` has no end-of-log flag. - Stop reading when a page is empty and the process has exited. ```bash # First page, at most 500 frames; JSON output includes nextCursor and eof daytona sandbox process logs {sandboxId} {processId} --limit 500 --output json # Following pages, until eof is true daytona sandbox process logs {sandboxId} {processId} --limit 500 --cursor {nextCursor} --output json ``` ```bash # First page, at most 500 frames curl '{toolboxProxyUrl}/{sandboxId}/processes/{processId}/logs?limit=500' \ --header 'Authorization: Bearer YOUR_API_KEY' # { # "frames": [ # { "cursor": "djE6MQ", "channel": "stdout", "timestamp": 1757756400000, "data": "1\n2\n3\n" } # ], # "nextCursor": "djE6MQ", # "truncatedHead": false, # "eof": false # } # Following pages, until eof is true curl '{toolboxProxyUrl}/{sandboxId}/processes/{processId}/logs?cursor={nextCursor}&limit=500' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ### Binary output [#binary-output] Read binary output without loss. The default text encoding replaces bytes that are not valid UTF-8. Base64 encoding returns the raw bytes of each frame as standard base64 with padding. ```python import base64 from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() handle = sandbox.process.start("head -c 1024 /dev/urandom") handle.wait() page = handle.logs(encoding="base64") raw = b"".join( base64.b64decode(frame.data) for frame in page.items if frame.channel == "stdout" ) print(f"{len(raw)} bytes") ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() const handle = await sandbox.process.start('head -c 1024 /dev/urandom') await handle.wait() const page = await handle.logs({ encoding: 'base64' }) const raw = Buffer.concat( page.items .filter((frame) => frame.channel === 'stdout') .map((frame) => Buffer.from(frame.data, 'base64')), ) console.log(`${raw.length} bytes`) ``` ```bash # Frames carry base64 payloads; table output is not binary-safe, so use JSON daytona sandbox process logs {sandboxId} {processId} --encoding base64 --output json ``` ```bash # Frames carry base64 payloads curl '{toolboxProxyUrl}/{sandboxId}/processes/{processId}/logs?encoding=base64' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ## Log frames [#log-frames] | **Field** | **Description** | | --------------- | ------------------------------------------------------------------------------------------------------------------------ | | `cursor` | Opaque position of this frame. Pass it as `cursor` to read strictly after this frame. `""` and `start` mean the beginning. | | `channel` | Which stream the frame came from. See the channel table below. | | `data` | The payload, as UTF-8 text or as a standard base64 string with padding when `encoding` is `base64`. | | `timestamp` | When the daemon recorded the frame, in Unix milliseconds. | | **Channel** | **Emitted by** | **Content** | | ------------- | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | **`stdout`** | `exec` and `code` processes | Standard output. `exec` processes keep `stdout` and `stderr` on separate pipes, so ordering is preserved within a channel, not across channels. | | **`stderr`** | `exec` and `code` processes | Standard error. | | **`pty`** | [PTY processes](/docs/pty) | The merged terminal byte stream, including escape sequences. | | **`setup`** | The daemon | Progress messages emitted while the daemon provisions something the process needs, for example a language kernel before the first code execution. | | **`display`** | [Code executions](/docs/code-execution) | A kernel side output (`display_data` or `update_display_data`) as a JSON object keyed by media type. | | **`execute_result`** | [Code executions](/docs/code-execution) | The kernel's primary result (`execute_result`) as a JSON object keyed by media type. | | **`error`** | [Code executions](/docs/code-execution) | A kernel exception as JSON: `{"ename", "evalue", "traceback"}`. | ## Log retention [#log-retention] Control how long a process record and its logs are kept. The retention policy is set when the process starts. Independent of the policy, retained output is capped in size; output beyond the cap evicts the oldest frames. A page read from an evicted position fails with an error that names the oldest retained position; a stream warns and continues from that position. | **Policy** | **Default for** | **Behavior** | | ------------------- | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`until_cleanup`** | API requests that set `name`, [PTY processes](/docs/pty) started through the SDKs, and the entrypoint process | The record and logs stay until the process is deleted. A process that fails to start is downgraded to `on_exit_ttl` so failed records do not accumulate. | | **`on_exit_ttl`** | API requests without `name`, and every SDK `process.start()` and `run()` call | The record and logs are removed 10 minutes after the process exits. Reading them afterwards fails with `404 PROCESS_NOT_FOUND`. | | **`none`** | | Logs are discarded the moment the process exits. The record stays for the same 10 minute window, so `wait()` still returns the exit result. `run()` never uses it. | ```python from daytona import Daytona from daytona.v2 import CursorExpiredError daytona = Daytona() sandbox = daytona.v2.create() # Keep the logs of an unnamed process until delete() handle = sandbox.process.start("seq 1 5000", keep_logs="until_cleanup") handle.wait() saved_cursor = "..." # a cursor stored from an earlier read try: page = handle.logs(cursor=saved_cursor) except CursorExpiredError as e: # The position was evicted; restart from the oldest retained frame page = handle.logs(cursor=e.first_available_cursor) handle.delete() ``` ```typescript import { Daytona } from '@daytona/sdk' import { CursorExpiredError } from '@daytona/sdk/v2' const daytona = new Daytona() const sandbox = await daytona.v2.create() // Keep the logs of an unnamed process until delete() const handle = await sandbox.process.start('seq 1 5000', { keepLogs: 'until_cleanup' }) await handle.wait() const savedCursor = '...' // a cursor stored from an earlier read let page try { page = await handle.logs({ cursor: savedCursor }) } catch (error) { if (!(error instanceof CursorExpiredError)) throw error // The position was evicted; restart from the oldest retained frame page = await handle.logs({ cursor: error.firstAvailableCursor }) } await handle.delete() ``` ```bash # Keep the logs until the record is deleted curl '{toolboxProxyUrl}/{sandboxId}/processes' \ --request POST \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "kind": "exec", "shellCommand": "seq 1 5000", "keepLogs": "until_cleanup" }' # Read from an evicted position curl '{toolboxProxyUrl}/{sandboxId}/processes/{processId}/logs?cursor={cursor}' \ --header 'Authorization: Bearer YOUR_API_KEY' # HTTP 409 # { # "code": "CURSOR_EXPIRED", # "message": "the requested position was evicted by log retention", # "firstAvailableCursor": "djE6NDA5Ng", # "source": "DAYTONA_DAEMON" # } # Delete the record and its logs curl '{toolboxProxyUrl}/{sandboxId}/processes/{processId}' \ --request DELETE \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ## Permissions [#permissions] Log streaming runs through the toolbox of a sandbox. Access is governed by one project permission, which you can grant to an [organization role](/docs/organizations#roles) or an [API key](/docs/api-keys). A [sandbox access token](/docs/sandboxes#create-an-access-token) with the toolbox:exec operation grants the same access to a single sandbox, without an API key. The sandbox read permission alone does not grant toolbox access. | **Permission** | **Grants** | | --------------------- | ---------------------------- | | **`write:sandboxes`** | Stream and read process logs | # Daytona MCP Server (/docs/mcp) Daytona's Model Context Protocol (MCP) server connects AI agents to [sandboxes](/docs/sandboxes). ## Install Daytona CLI [#install-daytona-cli] Install the Daytona CLI. ```bash brew install daytonaio/cli/daytona-alpha ``` ```powershell irm https://github.com/daytona/clients/releases/download/v2.0.0-alpha.11/install.ps1 | iex ``` ## Authenticate with Daytona [#authenticate-with-daytona] Authenticate with Daytona. ```bash daytona login ``` ## Available tools [#available-tools] MCP server provides the following tools for interacting with Daytona Sandboxes: - [Sandbox management](/docs/sandboxes) - [File system operations](/docs/file-system-operations) - [Git operations](/docs/git-operations) - [Process execution](/docs/process-execution) - [Code execution](/docs/code-execution) - [Computer use](/docs/computer-use) - [Preview](/docs/preview) # Computer Use (/docs/computer-use) Computer Use enables programmatic control of desktop environments within sandboxes. It provides mouse, keyboard, screenshot, screen recording, accessibility, and display operations for automating GUI interactions and testing desktop applications. Computer Use and [VNC](/docs/vnc-access) work together to enable both manual and automated desktop interactions. VNC provides the visual interface for users to manually interact with the desktop, while Computer Use provides the programmatic API for AI agents to automate operations. The desktop stack (D-Bus, Xvfb, the window manager, and the x11vnc server) ships with the sandbox runtime as a self-contained add-on, so it works on any Linux sandbox image, including images with no desktop packages. The virtual display runs at 1280x720. All Computer Use calls go through the toolbox API and require an API key with the sandbox write permission or a sandbox access token with the desktop or toolbox operation. ## Use cases [#use-cases] Computer Use is used when a task needs a graphical desktop instead of an API or a shell. - **Computer-use agents.** An agent reads screenshots and the accessibility tree, then moves the mouse and types to operate desktop applications. The desktop stack ships with the sandbox runtime, so it works on any Linux sandbox image. All Computer Use calls go through the toolbox API and require an API key with the sandbox write permission or a sandbox access token with the desktop or toolbox operation. - **Desktop application tests.** GUI tests click, type, and take screenshots to check the state of an application. Full-screen and region screenshots return a PNG image as a base64 string. The virtual display has a fixed resolution of 1280x720, with no setting per sandbox. - **Browser automation.** A browser on the sandbox desktop is driven through mouse and keyboard input, for sites that have no API. Typing sends any text, including symbols and non-ASCII characters. A delay between characters slows typing for applications that drop fast input. - **Agents on Windows and macOS.** Windows and macOS sandboxes provide screenshots, mouse and keyboard input, the accessibility tree, and screen recordings through the same API. On Windows, a desktop session must be open. When that session ends or another session replaces it, the desktop fails with a cause that names the reason. - **Human in the loop.** A person watches or takes over the same desktop through [VNC](/docs/vnc-access) while an agent works. Starting Computer Use also starts the x11vnc server. The VNC server runs in shared mode, so several viewers attach to the same desktop at once. ## Start Computer Use [#start-computer-use] Start all computer use processes (D-Bus, Xvfb, the window manager, and the x11vnc server) in the sandbox. The call blocks until the X server and the VNC server accept connections and returns the status of each process. If either does not come up within 5 s, the desktop is marked failed and the call returns an error. Calling start on a desktop that is already ready returns the current status. A start made while another start or a restart is in progress waits for it to finish, then returns the resulting status, or an error if the desktop failed. Calling start on a failed desktop returns an error; call [restart](#restart-computer-use) instead. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() result = sandbox.computer_use.start() print("Computer use processes started:", result.message) for name, process in result.status.items(): print(f"{name}: running={process.running} pid={process.pid}") ``` ```typescript import { Daytona } from '@daytona/sdk'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); const result = await sandbox.computerUse.start(); console.log('Computer use processes started:', result.message); for (const [name, process] of Object.entries(result.status)) { console.log(`${name}: running=${process.running} pid=${process.pid}`); } ``` ```bash curl '{toolboxProxyUrl}/{sandboxId}/computeruse/start' \ --request POST \ --header 'Authorization: Bearer YOUR_API_KEY' ``` - The request requires the `write:sandboxes` permission. - `{toolboxProxyUrl}` is the `toolbox_proxy_url` field of the [sandbox](/docs/sandboxes#get-a-sandbox). ## Stop Computer Use [#stop-computer-use] Stop all computer use processes in the sandbox. Stopping a ready desktop returns it to not started. Stopping a failed desktop kills any remaining processes but keeps the failed state and its cause; only [restart](#restart-computer-use) leaves the failed state. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.computer_use.start() result = sandbox.computer_use.stop() print("Computer use processes stopped:", result.message) ``` ```typescript import { Daytona } from '@daytona/sdk'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); await sandbox.computerUse.start(); const result = await sandbox.computerUse.stop(); console.log('Computer use processes stopped:', result.message); ``` ```bash curl '{toolboxProxyUrl}/{sandboxId}/computeruse/stop' \ --request POST \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ## Restart Computer Use [#restart-computer-use] Tear the desktop down and build a new one. Restart is valid from every state and is the only way out of the failed state. Concurrent restart calls join the same in-flight restart and receive the same result. Application windows do not survive a restart. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.computer_use.start() result = sandbox.computer_use.restart() print(result.message, result.desktop) # computer use restarted ready ``` ```typescript import { Daytona } from '@daytona/sdk'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); await sandbox.computerUse.start(); const result = await sandbox.computerUse.restart(); console.log(result.message, result.desktop); // computer use restarted ready ``` ```bash curl '{toolboxProxyUrl}/{sandboxId}/computeruse/restart' \ --request POST \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ## Get status [#get-status] Get the desktop status. The status field is active only while the desktop field is ready. | **`desktop`** | **`status`** | **Meaning** | | ----------------- | ------------ | --------------------------------------------------------------------------------------------------------- | | `not_started` | `inactive` | No desktop exists. Call [start](#start-computer-use). | | `starting` | `inactive` | Start is in progress. Poll status. | | `ready` | `active` | Actions are accepted. | | `failed` | `inactive` | The desktop is gone. `cause.code` and `cause.message` explain why. Call [restart](#restart-computer-use). | The cause object is present only when the desktop is failed. Possible cause codes: | **Code** | **Meaning** | | ----------------------------- | --------------------------------------------------------------------------------------------- | | **`desktop_exited`** | The X server (`xvfb`) exited. Windows in it are lost. | | **`addon_crashed`** | The add-on that supervises the desktop died while the desktop was ready. | | **`start_failed`** | Creating the desktop or probing its readiness failed, for example a missing binary. | | **`start_interrupted`** | The add-on died while the desktop was being created. | | **`state_corrupt`** | Retained desktop state could not be read or validated. | | **`state_persistence_failed`** | A state transition could not be persisted. | | **`session_ended`** | Windows and macOS only. The interactive desktop session ended or left the console. | | **`session_replaced`** | Windows only. Another interactive desktop session replaced the one the desktop was bound to. | Failure evidence is boot-scoped: a sandbox reboot resets the desktop to not started. The SDKs report a state or cause code they do not recognize as `unknown` and keep the API value in `raw_status`, `raw_desktop`, and `cause.raw_code` (`rawStatus`, `rawDesktop`, and `cause.rawCode` in TypeScript). ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() status = sandbox.computer_use.status() print("Computer use status:", status.status, status.desktop) if status.desktop == "failed": print(f"Failure: {status.cause.code}: {status.cause.message}") ``` ```typescript import { Daytona } from '@daytona/sdk'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); const status = await sandbox.computerUse.status(); console.log('Computer use status:', status.status, status.desktop); if (status.desktop === 'failed') { console.log(`Failure: ${status.cause.code}: ${status.cause.message}`); } ``` ```bash curl '{toolboxProxyUrl}/{sandboxId}/computeruse/status' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ## Get process status [#get-process-status] Get the status of one desktop process: D-Bus, Xvfb, the window manager, or the x11vnc server. Without a name, it returns the [status of every process](#get-all-process-statuses). ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.computer_use.start() xvfb_status = sandbox.computer_use.service.status("xvfb") print(xvfb_status.process_name, xvfb_status.running) ``` - The request requires the `write:sandboxes` permission. - The process names are `dbus`, `xvfb`, `wm`, and `x11vnc`. ```typescript import { Daytona } from '@daytona/sdk'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); await sandbox.computerUse.start(); const xvfbStatus = await sandbox.computerUse.service.status('xvfb'); console.log(xvfbStatus.processName, xvfbStatus.running); ``` - The request requires the `write:sandboxes` permission. - The process names are `dbus`, `xvfb`, `wm`, and `x11vnc`. ```bash curl '{toolboxProxyUrl}/{sandboxId}/computeruse/process/{processName}/status' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` - The request requires the `write:sandboxes` permission. - The process names are `dbus`, `xvfb`, `wm`, and `x11vnc`. ## Get all process statuses [#get-all-process-statuses] Get the status of every desktop process. The response is a map keyed by process name, with one entry each for D-Bus, Xvfb, the window manager, and the x11vnc server while a desktop exists. The map is empty before the first start, after stop, after a failed start, and after the add-on restarts. Each entry reports whether the process is alive, its supervisor restart state, and its startup priority. | **API field** | **Description** | | ---------------------- | ------------------------------------------------------------------- | | **`Running`** | Whether the process is alive. | | **`Pid`** | Process ID while the process is running. | | **`Status`** | `running`, `stopped`, or `failed`. | | **`Failed`** | Whether the supervisor gave up on the process: `xvfb` after it exits, the other processes after their automatic restarts run out. A process restart or a desktop restart clears it. | | **`AutoRestart`** | Whether the supervisor restarts the process automatically. | | **`RestartAttempts`** | Exits in a row within 30 s of starting. It reaches `6` when the supervisor marks the process failed. Resets after a run of 30 s or longer, a process restart, or a desktop start. | | **`RestartBackoffMs`** | Current restart backoff in milliseconds. The SDKs return it in seconds, as `restart_backoff` in Python and `restartBackoffSeconds` in TypeScript. | | **`Priority`** | Relative startup priority within the desktop stack. | ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.computer_use.start() for name, process in sandbox.computer_use.service.status().items(): print(f"{name}: {process.status} pid={process.pid} restarts={process.restart_attempts}") ``` ```typescript import { Daytona } from '@daytona/sdk'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); await sandbox.computerUse.start(); const statuses = await sandbox.computerUse.service.status(); for (const [name, process] of Object.entries(statuses)) { console.log(`${name}: ${process.status} pid=${process.pid} restarts=${process.restartAttempts}`); } ``` ```bash curl '{toolboxProxyUrl}/{sandboxId}/computeruse/process-status' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ## Restart process [#restart-process] Restart a specific desktop process. Per-process restart works only while the desktop is ready. The Xvfb process cannot be restarted on its own because application windows live inside it; use [restart](#restart-computer-use) instead. The D-Bus, window manager, and x11vnc processes are restarted automatically when they exit. A process that exits within 30 s of starting is restarted at most 5 times in a row, after waits of 1, 2, 4, 8, and 16 s. The sixth such exit marks it failed in the status map, while the desktop stays ready. A run that lasts 30 s or longer resets the count. Restarting a failed process resets its count and starts it again. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.computer_use.start() result = sandbox.computer_use.service.restart("wm") print(result.message, result.process_name) ``` ```typescript import { Daytona } from '@daytona/sdk'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); await sandbox.computerUse.start(); const result = await sandbox.computerUse.service.restart('wm'); console.log(result.message, result.processName); ``` ```bash curl '{toolboxProxyUrl}/{sandboxId}/computeruse/process/{processName}/restart' \ --request POST \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ## Get process logs [#get-process-logs] Get logs for a specific desktop process. Each log is checked every 5 s and whenever the process starts; once it exceeds 256 KiB, it is cut to its most recent 128 KiB. Logs accumulate across process and desktop restarts. Logs and errors are readable only while a desktop exists, including after Xvfb exits. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.computer_use.start() logs = sandbox.computer_use.service.logs("x11vnc") print("x11vnc logs:", logs.logs) ``` The response has the following fields: | **Field** | **Description** | | --------- | --------------- | | `logs` | Holds the retained standard output of the process. | ```typescript import { Daytona } from '@daytona/sdk'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); await sandbox.computerUse.start(); const logs = await sandbox.computerUse.service.logs('x11vnc'); console.log('x11vnc logs:', logs.logs); ``` The response has the following fields: | **Field** | **Description** | | --------- | --------------- | | `logs` | Holds the retained standard output of the process. | ```bash curl '{toolboxProxyUrl}/{sandboxId}/computeruse/process/{processName}/logs' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ## Get process errors [#get-process-errors] Get error logs for a specific desktop process. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.computer_use.start() errors = sandbox.computer_use.service.errors("x11vnc") print("x11vnc errors:", errors.errors) ``` The response has the following fields: | **Field** | **Description** | | --------- | --------------- | | `errors` | Holds the retained standard error output of the process, plus lines the supervisor adds when the process cannot be started or runs out of automatic restarts. Trimmed like the logs. The value is an empty string when nothing was written. | ```typescript import { Daytona } from '@daytona/sdk'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); await sandbox.computerUse.start(); const errors = await sandbox.computerUse.service.errors('x11vnc'); console.log('x11vnc errors:', errors.errors); ``` The response has the following fields: | **Field** | **Description** | | --------- | --------------- | | `errors` | Holds the retained standard error output of the process, plus lines the supervisor adds when the process cannot be started or runs out of automatic restarts. Trimmed like the logs. The value is an empty string when nothing was written. | ```bash curl '{toolboxProxyUrl}/{sandboxId}/computeruse/process/{processName}/errors' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ## Mouse operations [#mouse-operations] Every mouse, keyboard, screenshot, display, accessibility, and recording-start call requires the desktop to be ready; otherwise it returns 409 with a desktop not ready error. Coordinates are screen pixels in the range -32768 to 32767; values outside it return 400. ### Click [#click] Click the mouse at the specified coordinates with the left, right, or middle button, as a single or a double click. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.computer_use.start() sandbox.computer_use.mouse.click(x=100, y=200) ``` | **Parameter** | **Type** | **Description** | | ------------- | ------------------------ | -------------------- | | `button` | ComputerUseMouseButton | Sets the mouse button. The default is `"left"`. | | `double` | bool | Makes the click a double click. The default is `False`. | ```typescript import { Daytona } from '@daytona/sdk'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); await sandbox.computerUse.start(); await sandbox.computerUse.mouse.click({ x: 100, y: 200 }); ``` | **Parameter** | **Type** | **Description** | | ------------- | ------------------------ | -------------------- | | `button` | ComputerUseMouseButton | Sets the mouse button. The default is `'left'`. | | `double` | boolean | Makes the click a double click. The default is `false`. | ```bash curl '{toolboxProxyUrl}/{sandboxId}/computeruse/mouse/click' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "x": 100, "y": 200 }' ``` | **Field** | **Type** | **Description** | | --------- | --------- | ------------------- | | `button` | string | Sets the mouse button. The default is `left`. | | `double` | boolean | Makes the click a double click. The default is `false`. | The response has the following fields: | **Field** | **Description** | | --------- | --------------- | | `x` | Holds the x coordinate of the pointer after the click. | | `y` | Holds the y coordinate of the pointer after the click. | ### Move [#move] Move the mouse cursor to the given coordinates. The response holds the final pointer position. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.computer_use.start() result = sandbox.computer_use.mouse.move(x=100, y=200) print(f"Mouse moved to: {result.x}, {result.y}") ``` ```typescript import { Daytona } from '@daytona/sdk'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); await sandbox.computerUse.start(); const result = await sandbox.computerUse.mouse.move({ x: 100, y: 200 }); console.log(`Mouse moved to: ${result.x}, ${result.y}`); ``` ```bash curl '{toolboxProxyUrl}/{sandboxId}/computeruse/mouse/move' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "x": 100, "y": 200 }' ``` ### Drag [#drag] Drag the mouse from start to end coordinates while holding the selected button. The pointer moves in 10 interpolated steps so applications that ignore a teleporting drag still register it. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.computer_use.start() result = sandbox.computer_use.mouse.drag( start_x=50, start_y=50, end_x=150, end_y=150, button="left" ) print(f"Drag ended at {result.x}, {result.y}") ``` | **Parameter** | **Type** | **Description** | | ------------- | ------------------------ | ------------------ | | `button` | ComputerUseMouseButton | Sets the mouse button to hold. The default is `"left"`. | ```typescript import { Daytona } from '@daytona/sdk'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); await sandbox.computerUse.start(); const result = await sandbox.computerUse.mouse.drag({ startX: 50, startY: 50, endX: 150, endY: 150, button: 'left', }); console.log(`Drag ended at ${result.x}, ${result.y}`); ``` | **Parameter** | **Type** | **Description** | | ------------- | ------------------------ | --------------- | | `button` | ComputerUseMouseButton | Sets the mouse button to hold. The default is `'left'`. | ```bash curl '{toolboxProxyUrl}/{sandboxId}/computeruse/mouse/drag' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "button": "left", "endX": 150, "endY": 150, "startX": 50, "startY": 50 }' ``` | **Field** | **Type** | **Description** | | --------- | -------- | ---------------- | | `button` | string | Sets the mouse button to hold. The default is `left`. | ### Scroll [#scroll] Scroll the mouse wheel up or down at the specified coordinates by a number of wheel ticks. One tick is one notch of a physical mouse wheel. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.computer_use.start() result = sandbox.computer_use.mouse.scroll(x=100, y=200, direction="down") print(result.success) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------- | | `amount` | int | Sets the number of wheel ticks. The value must not be negative, and a value above `100` is capped at `100`. The default is `1`. | ```typescript import { Daytona } from '@daytona/sdk'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); await sandbox.computerUse.start(); const result = await sandbox.computerUse.mouse.scroll({ x: 100, y: 200, direction: 'down' }); console.log(result.success); ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------- | | `amount` | number | Sets the number of wheel ticks. The value must not be negative, and a value above `100` is capped at `100`. The default is `1`. | ```bash curl '{toolboxProxyUrl}/{sandboxId}/computeruse/mouse/scroll' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "direction": "down", "x": 100, "y": 200 }' ``` | **Field** | **Type** | **Description** | | --------- | -------- | --------------- | | `amount` | integer | Sets the number of wheel ticks. The value must not be negative, and a value above `100` is capped at `100`. The default is `1`. | ### Get position [#get-position] Get the current mouse cursor position. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.computer_use.start() position = sandbox.computer_use.mouse.position() print(f"Mouse is at: {position.x}, {position.y}") ``` ```typescript import { Daytona } from '@daytona/sdk'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); await sandbox.computerUse.start(); const position = await sandbox.computerUse.mouse.position(); console.log(`Mouse is at: ${position.x}, ${position.y}`); ``` ```bash curl '{toolboxProxyUrl}/{sandboxId}/computeruse/mouse/position' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ## Keyboard operations [#keyboard-operations] Send keyboard input to the desktop. Type a text string, press one key with optional modifiers, or press a hotkey combination. Key names resolve against the keyboard map of the virtual display, and, like mouse calls, keyboard calls require the desktop to be ready. ### Type [#type] Type arbitrary text, including uppercase letters, symbols, and non-ASCII characters. Newlines are sent as Enter and tabs as Tab. Characters with no key in the X11 keymap are typed through a temporary key mapping. Set a delay between characters to slow typing down for applications that drop fast input. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.computer_use.start() sandbox.computer_use.keyboard.type(text="Hello, World!") ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------- | | `delay` | float | Sets the pause between characters in seconds, rounded up to whole milliseconds. A value above `1` is capped at `1`. A negative value raises `BadRequestError`. The default is `0`. | - The request requires the `write:sandboxes` permission. - The call sends `\n` and `\r` as the Enter key, so a `\r\n` pair presses Enter twice. - The text is limited to 4096 Unicode code points. - The number of characters multiplied by the capped delay must not exceed 25 seconds; a longer request returns `400` before any key is typed. ```typescript import { Daytona } from '@daytona/sdk'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); await sandbox.computerUse.start(); await sandbox.computerUse.keyboard.type({ text: 'Hello, World!' }); ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------- | | `delaySeconds` | number | Sets the pause between characters in seconds, rounded up to whole milliseconds. A value above `1` is capped at `1`. A negative value throws `BadRequestError`. The default is `0`. | - The request requires the `write:sandboxes` permission. - The call sends `\n` and `\r` as the Enter key, so a `\r\n` pair presses Enter twice. - The text is limited to 4096 Unicode code points. - The number of characters multiplied by the capped delay must not exceed 25 seconds; a longer request returns `400` before any key is typed. ```bash curl '{toolboxProxyUrl}/{sandboxId}/computeruse/keyboard/type' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "text": "Hello, World!" }' ``` | **Field** | **Type** | **Description** | | --------- | -------- | --------------- | | `delay` | integer | Sets the pause between characters in milliseconds. A value above `1000` is capped at `1000`. The default is `0`. | - The request requires the `write:sandboxes` permission. - The call sends `\n` and `\r` as the Enter key, so a `\r\n` pair presses Enter twice. - The text is limited to 4096 Unicode code points. - The number of characters multiplied by the capped delay must not exceed 25 seconds; a longer request returns `400` before any key is typed. ### Press [#press] Press a key with optional modifiers. Modifiers are held in order, the key is pressed and released, and the modifiers are released in reverse, even if the press fails. See [supported keys](#supported-keys). ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.computer_use.start() sandbox.computer_use.keyboard.key(key="enter") ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------- | | `modifiers` | Sequence[ComputerUseKeyboardModifier] | Sets the modifier keys to hold during the press: `ctrl`, `alt`, `shift`, or `cmd`. | ```typescript import { Daytona } from '@daytona/sdk'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); await sandbox.computerUse.start(); await sandbox.computerUse.keyboard.key({ key: 'enter' }); ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------- | | `modifiers` | ComputerUseKeyboardModifier[] | Sets the modifier keys to hold during the press: `ctrl`, `alt`, `shift`, or `cmd`. | ```bash curl '{toolboxProxyUrl}/{sandboxId}/computeruse/keyboard/key' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "key": "enter" }' ``` | **Field** | **Type** | **Description** | | --------- | -------- | --------------- | | `modifiers` | string[] | Sets the keys to hold during the press, in order. Accepts any name in [supported keys](#supported-keys); a name not in the keymap returns `400`. | ### Hotkey [#hotkey] Press a hotkey combination. The combination is a plus-separated chord string: the last entry is the key, the others are modifiers. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.computer_use.start() sandbox.computer_use.keyboard.hotkey(keys="ctrl+c") ``` ```typescript import { Daytona } from '@daytona/sdk'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); await sandbox.computerUse.start(); await sandbox.computerUse.keyboard.hotkey({ keys: 'ctrl+c' }); ``` ```bash curl '{toolboxProxyUrl}/{sandboxId}/computeruse/keyboard/hotkey' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "keys": "ctrl+c" }' ``` ### Supported keys [#supported-keys] Named keys and aliases are case-insensitive. A single character keeps its case: `A` presses Shift and `a`. The following are supported for the key and modifiers parameters and for the parts of the keys parameter: | Category | Keys | | ------------- | ------------------------------------------------------------------------------------------------------------- | | Modifiers | `ctrl` (alias `control`), `alt`, `shift`, `cmd` (aliases `super`, `meta`, `win`) | | Editing | `enter` (alias `return`), `tab`, `escape` (alias `esc`), `backspace`, `delete` (alias `del`), `space` | | Navigation | `home`, `end`, `pageup` (alias `page_up`), `pagedown` (alias `page_down`), `insert`, `up`, `down`, `left`, `right` | | Function keys | `f1` through `f12` | | Symbols | `minus`, `plus`, `equal` (alias `equals`) | | Characters | Any single character in the keymap of the display, for example `a`, `A`, `5`, `/`, `-`. In press and hotkey, a character outside the keymap returns `400`; use [type](#type) for it. In the keys parameter, write `plus` for `+`. | The SDK modifiers type lists ctrl, alt, shift, and cmd; the API accepts those, their aliases, and any other supported key name. ## Accessibility operations [#accessibility-operations] Use accessibility operations to inspect the AT-SPI tree and interact with UI elements by node ID. Start Computer Use before calling accessibility methods. Each node carries an ID, role, name, bounds (x, y, width, height in screen pixels), and states. The description, actions, and children appear only when not empty, and find matches never include children. A node without the AT-SPI component interface reports zero bounds. The role is the AT-SPI role name, passed through unchanged. Node states outside the list in [find nodes](#find-nodes) appear as `state:`, where `` is the AT-SPI state number. On Linux, the value field is never set. A node ID joins the bus name and the object path of the element with a colon, and is valid only while the owning application keeps the object alive. A malformed ID returns `400`. An unknown ID returns `404` from focus and invoke, and `400` from set value. The scope parameter selects the root of the search: | **Scope** | **Root** | | ------------- | -------------------------------------------------------------------------------------------------- | | **`focused`** | The application whose state includes `active`, else the first registered application. Default. | | **`pid`** | The application owned by process `pid`. Returns `404` if no accessible application has that PID. | | **`all`** | The AT-SPI registry root, covering every application. | Traversal is bounded: 2000 nodes and 2 s for the tree, 5000 nodes and 2 s for find. When a bound is reached, the response is marked as truncated. Cutting the tree at the maximum depth does not mark it as truncated. Accessibility operations read the semantic UI information that applications expose over AT-SPI. Apps or custom widgets that do not expose accessibility objects may return sparse nodes, generic roles, or no actionable nodes; mouse, keyboard, and screenshot operations remain available for those cases. ### Get tree [#get-tree] Read an accessibility tree for the focused app, a specific process, or all apps. The maximum depth parameter limits the depth below the root, and 0 returns only the root. The SDKs return at most 256 levels. The API returns the whole subtree within the traversal budget when the parameter is omitted or -1. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.computer_use.start() tree = sandbox.computer_use.a11y.tree(scope="focused") print(tree.root.role, tree.root.name, tree.truncated) ``` | **Parameter** | **Type** | **Description** | | ------------- | ---------------------- | --------------------------------------------------- | | `scope` | ComputerUseA11yScope | Sets the root of the search: `"focused"`, `"pid"`, or `"all"`. This parameter is required. With `scope="pid"`, also pass `pid`. | | `pid` | int | Selects the application when `scope` is `"pid"`. | | `max_depth` | int | Limits the depth below the root, from `0` to `256`. A value outside the range raises `BadRequestError`. The default is `256`. | ```typescript import { Daytona } from '@daytona/sdk'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); await sandbox.computerUse.start(); const tree = await sandbox.computerUse.a11y.tree({ scope: 'focused' }); console.log(tree.root.role, tree.root.name, tree.truncated); ``` | **Parameter** | **Type** | **Description** | | ------------- | ---------------------- | --------------------------------------------------- | | `scope` | ComputerUseA11yScope | Sets the root of the search: `'focused'`, `'pid'`, or `'all'`. This parameter is required. With `scope: 'pid'`, also pass `pid`. | | `pid` | number | Selects the application when `scope` is `'pid'`. | | `maxDepth` | number | Limits the depth below the root, from `0` to `256`. A value outside the range throws `BadRequestError`. The default is `256`. | ```bash curl '{toolboxProxyUrl}/{sandboxId}/computeruse/a11y/tree?scope=focused' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` | **Field** | **Type** | **Description** | | ---------- | --------- | ------------------------------------------------------- | | `scope` | string | Sets the root of the search. An unknown scope returns `400`. The default is `focused`. | | `pid` | integer | Selects the application when `scope=pid`. | | `maxDepth` | integer | Limits the depth below the root. Omit the parameter or pass `-1` to get the whole subtree. The query parameter name is camelCase. | ### Find nodes [#find-nodes] Search the accessibility tree by role, accessible name, state, and scope. All filters must match. Name matching is case-sensitive. The regex mode uses the syntax of the Rust `regex-lite` crate and matches anywhere in the name unless the pattern is anchored with `^` and `$`; an invalid pattern returns `400`. Find visits nodes depth first, last child first, so the first match is not necessarily the first element on screen. Node states: invalid, active, armed, busy, checked, collapsed, defunct, editable, enabled, expandable, expanded, focusable, focused, has-tooltip, horizontal, iconified, modal, multi-line, multiselectable, opaque, pressed, resizable, selectable, selected, sensitive, showing, single-line, stale, transient, vertical, visible, manages-descendants, indeterminate, required, truncated, and animated. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.computer_use.start() buttons = sandbox.computer_use.a11y.find(scope="focused", role="button", name="Submit") for node in buttons.matches: print(node.id, node.name, node.bounds.x, node.bounds.y) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------------------------- | ---------------------------------------------------------------------------- | | `scope` | ComputerUseA11yScope | Sets the root of the search. This parameter is required. | | `pid` | int | Selects the application when `scope` is `"pid"`. | | `role` | str | Matches the node role exactly, for example `button` or `entry`. | | `name` | str | Matches the accessible name according to `name_match`. | | `name_match` | ComputerUseA11yNameMatch | Sets how `name` is compared: `exact`, `substring`, or `regex`. The default is `exact`. | | `states` | Sequence\[str\] | Requires the node to have every listed state, for example `["enabled", "focusable"]`. | | `limit` | int | Caps the number of matches. A value of `0` or less uses the default. With more matches, `truncated` is `True`. The default is `50`. | - The request requires the `write:sandboxes` permission. - Filters other than `scope` are optional, and an omitted filter matches every node. ```typescript import { Daytona } from '@daytona/sdk'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); await sandbox.computerUse.start(); const buttons = await sandbox.computerUse.a11y.find({ scope: 'focused', role: 'button', name: 'Submit' }); for (const node of buttons.matches) { console.log(node.id, node.name, node.bounds.x, node.bounds.y); } ``` | **Parameter** | **Type** | **Description** | | ------------- | -------------------------- | ---------------------------------------------------------------------------- | | `scope` | ComputerUseA11yScope | Sets the root of the search. This parameter is required. | | `pid` | number | Selects the application when `scope` is `'pid'`. | | `role` | string | Matches the node role exactly, for example `'button'` or `'entry'`. | | `name` | string | Matches the accessible name according to `nameMatch`. | | `nameMatch` | ComputerUseA11yNameMatch | Sets how `name` is compared: `'exact'`, `'substring'`, or `'regex'`. The default is `'exact'`. | | `states` | string\[\] | Requires the node to have every listed state, for example `['enabled', 'focusable']`. | | `limit` | number | Caps the number of matches. A value of `0` or less uses the default. With more matches, `truncated` is `true`. The default is `50`. | - The request requires the `write:sandboxes` permission. - Filters other than `scope` are optional, and an omitted filter matches every node. ```bash curl '{toolboxProxyUrl}/{sandboxId}/computeruse/a11y/find' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "scope": "focused", "role": "button", "name": "Submit" }' ``` | **Field** | **Type** | **Description** | | ----------- | ---------- | -------------------------------------------------------------------------------------------- | | `scope` | string | Sets the root of the search. The default is `focused`. | | `pid` | integer | Selects the application when `scope` is `pid`. | | `role` | string | Matches the node role exactly, for example `button` or `entry`. | | `name` | string | Matches the accessible name according to `nameMatch`. | | `nameMatch` | string | Sets how `name` is compared: `exact`, `substring`, or `regex`. The default is `exact`. | | `states` | string\[\] | Requires the node to have every listed state, for example `["enabled", "focusable"]`. | | `limit` | integer | Caps the number of matches. A value of `0` or less uses the default. With more matches, `truncated` is `true`. The default is `50`. | ### Focus node [#focus-node] Focus a node from [get tree](#get-tree) or [find nodes](#find-nodes). The call asks the application to give the node focus; if the application declines, the call returns `400`. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.computer_use.start() node = sandbox.computer_use.a11y.find(scope="focused", role="button", name="Submit").matches[0] sandbox.computer_use.a11y.focus(id=node.id) ``` ```typescript import { Daytona } from '@daytona/sdk'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); await sandbox.computerUse.start(); const node = (await sandbox.computerUse.a11y.find({ scope: 'focused', role: 'button', name: 'Submit' })).matches[0]; await sandbox.computerUse.a11y.focus({ id: node.id }); ``` ```bash curl '{toolboxProxyUrl}/{sandboxId}/computeruse/a11y/node/focus' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{"id":"node-id"}' ``` ### Invoke node [#invoke-node] Run a node action, such as pressing a button. Without an action name, the node's click action is invoked, falling back to its first action. An action name must appear in the node's actions list and is case-sensitive. A node with an empty actions list, or an action the application rejects, returns `400`. A node without the AT-SPI action interface returns `404`. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.computer_use.start() node = sandbox.computer_use.a11y.find(scope="focused", role="button", name="Submit").matches[0] sandbox.computer_use.a11y.invoke(id=node.id) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------- | | `action` | str | Sets the action to run. The name must appear in the node's `actions` list. The default is the node's click action, or its first action without one. | ```typescript import { Daytona } from '@daytona/sdk'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); await sandbox.computerUse.start(); const node = (await sandbox.computerUse.a11y.find({ scope: 'focused', role: 'button', name: 'Submit' })).matches[0]; await sandbox.computerUse.a11y.invoke({ id: node.id }); ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------- | | `action` | string | Sets the action to run. The name must appear in the node's `actions` list. The default is the node's click action, or its first action without one. | ```bash curl '{toolboxProxyUrl}/{sandboxId}/computeruse/a11y/node/invoke' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{"id":"node-id"}' ``` | **Field** | **Type** | **Description** | | --------- | -------- | --------------- | | `action` | string | Sets the action to run. The name must appear in the node's `actions` list. The default is the node's click action, or its first action without one. | ### Set node value [#set-node-value] Write text content to nodes that implement editable text, such as entries and text areas. The value replaces the current content. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.computer_use.start() node = sandbox.computer_use.a11y.find(scope="focused", role="entry").matches[0] sandbox.computer_use.a11y.set_value(id=node.id, value="hello") ``` ```typescript import { Daytona } from '@daytona/sdk'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); await sandbox.computerUse.start(); const node = (await sandbox.computerUse.a11y.find({ scope: 'focused', role: 'entry' })).matches[0]; await sandbox.computerUse.a11y.setValue({ id: node.id, value: 'hello' }); ``` ```bash curl '{toolboxProxyUrl}/{sandboxId}/computeruse/a11y/node/value' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{"id":"node-id","value":"hello"}' ``` | **Field** | **Type** | **Description** | | --------- | -------- | --------------- | | `value` | string | Sets the new text, which replaces the current content. An omitted value clears the field. | ## Screenshot operations [#screenshot-operations] Screenshots return the image as a base64 string, its encoded size in bytes, and, when the cursor is requested, the pointer coordinates. The cursor is never drawn. Full-screen and region screenshots are PNG; compressed variants accept format, quality, and scale parameters. The SDKs take every variant with one screenshot method: a region selects the region variant, and setting the format, quality, or scale selects the compressed variant. The show cursor parameter works with every variant and does not select compression. ### Take full screen [#take-full-screen] Take a screenshot of the entire screen. ```python import base64 from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.computer_use.start() screenshot = sandbox.computer_use.screen.screenshot() print(f"Screenshot size: {screenshot.size_bytes} bytes") with open("screen.png", "wb") as f: f.write(base64.b64decode(screenshot.screenshot)) ``` ```typescript import { writeFile } from 'node:fs/promises'; import { Daytona } from '@daytona/sdk'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); await sandbox.computerUse.start(); const screenshot = await sandbox.computerUse.screen.screenshot(); console.log(`Screenshot size: ${screenshot.sizeBytes} bytes`); await writeFile('screen.png', Buffer.from(screenshot.screenshot, 'base64')); ``` ```bash curl '{toolboxProxyUrl}/{sandboxId}/computeruse/screenshot' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ### Take region [#take-region] Take a screenshot of a specific region. The width and height must be positive, and the region must lie within the screen. ```python from daytona import Daytona from daytona.v2 import ComputerUseRegion daytona = Daytona() sandbox = daytona.v2.create() sandbox.computer_use.start() screenshot = sandbox.computer_use.screen.screenshot( region=ComputerUseRegion(x=100, y=100, width=300, height=200) ) print(f"Captured region: {screenshot.size_bytes} bytes") ``` ```typescript import { Daytona } from '@daytona/sdk'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); await sandbox.computerUse.start(); const screenshot = await sandbox.computerUse.screen.screenshot({ region: { x: 100, y: 100, width: 300, height: 200 }, }); console.log(`Captured region: ${screenshot.sizeBytes} bytes`); ``` ```bash curl '{toolboxProxyUrl}/{sandboxId}/computeruse/screenshot/region?x=100&y=100&width=300&height=200' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ### Take compressed [#take-compressed] Take a compressed screenshot of the entire screen. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.computer_use.start() screenshot = sandbox.computer_use.screen.screenshot(format="jpeg", quality=80) print(f"Compressed size: {screenshot.size_bytes} bytes") ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------------------------------------------------------- | | `format` | str | Sets the image format, `png` or `jpeg`. The default is `png`. | | `quality` | int | Sets the image quality, from `1` to `100`. The default is `85`. The quality applies to `jpeg`. | | `scale` | float | Resizes the captured image by a factor from `0.1` to `1.0`. The default is `1.0`. | | `show_cursor` | bool | Returns the pointer coordinates with the screenshot. The cursor is never drawn. The default is `False`. | ```typescript import { Daytona } from '@daytona/sdk'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); await sandbox.computerUse.start(); const screenshot = await sandbox.computerUse.screen.screenshot({ format: 'jpeg', quality: 80 }); console.log(`Compressed size: ${screenshot.sizeBytes} bytes`); ``` | **Parameter** | **Type** | **Description** | | ------------- | --------- | ----------------------------------------------------------- | | `format` | string | Sets the image format, `'png'` or `'jpeg'`. The default is `'png'`. | | `quality` | number | Sets the image quality, from `1` to `100`. The default is `85`. The quality applies to `'jpeg'`. | | `scale` | number | Resizes the captured image by a factor from `0.1` to `1.0`. The default is `1.0`. | | `showCursor` | boolean | Returns the pointer coordinates with the screenshot. The cursor is never drawn. The default is `false`. | ```bash curl '{toolboxProxyUrl}/{sandboxId}/computeruse/screenshot/compressed?format=jpeg&quality=80' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` | **Field** | **Type** | **Description** | | ------------- | --------- | ----------------------------------------------------------- | | `format` | string | Sets the image format, `png` or `jpeg`. The default is `png`. | | `quality` | integer | Sets the image quality, from `1` to `100`. The quality applies to `jpeg`. The default is `85`. | | `scale` | number | Resizes the captured image by a factor from `0.1` to `1.0`. The default is `1.0`. | | `show_cursor` | boolean | Returns the pointer coordinates with the screenshot. The cursor is never drawn. The default is `false`. | ### Take compressed region [#take-compressed-region] Take a compressed screenshot of a specific region. Accepts the region parameters of [take region](#take-region) and the compression parameters of [take compressed](#take-compressed). ```python from daytona import Daytona from daytona.v2 import ComputerUseRegion daytona = Daytona() sandbox = daytona.v2.create() sandbox.computer_use.start() screenshot = sandbox.computer_use.screen.screenshot( region=ComputerUseRegion(x=0, y=0, width=800, height=600), format="jpeg", quality=80 ) print(f"Compressed size: {screenshot.size_bytes} bytes") ``` ```typescript import { Daytona } from '@daytona/sdk'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); await sandbox.computerUse.start(); const screenshot = await sandbox.computerUse.screen.screenshot({ region: { x: 0, y: 0, width: 800, height: 600 }, format: 'jpeg', quality: 80, }); console.log(`Compressed size: ${screenshot.sizeBytes} bytes`); ``` ```bash curl '{toolboxProxyUrl}/{sandboxId}/computeruse/screenshot/region/compressed?x=0&y=0&width=800&height=600&format=jpeg&quality=80' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ## Screen Recording [#screen-recording] Computer Use records desktop sessions for debugging, documentation, or automation workflows. Recordings are MP4 files captured at 10 frames per second and stored inside the sandbox; the file path field in every recording response reports the location. Video is encoded with MPEG-4 Part 2, not H.264, so some browsers cannot play it inline. Each recording has the following fields. TypeScript and the API use the camelCase names; Python uses the snake_case names. | **Field** | **Description** | | ---------------------- | --------------------------------------------------------------------------------------------------------- | | `id` | Recording ID, prefixed `rec_`. Used for stop, get, download, and delete. | | `fileName`, `file_name` | `-.mp4`. Label characters other than letters, digits, and `-` are replaced with `_`. The label defaults to `recording`. | | `filePath`, `file_path` | Path of the file inside the sandbox. | | `startTime`, `start_time` | Start time: an RFC 3339 string in TypeScript and the API, a `datetime` in Python. | | `endTime`, `end_time` | End time, in the same type as the start time. Absent until the recording is finalized. | | `status` | See the status table below. | | `durationSeconds`, `duration_seconds` | Elapsed seconds while active, or the final duration. | | `sizeBytes`, `size_bytes` | Current file size while active, or the final size. | | **Status** | **Meaning** | | ---------------------------- | ------------------------------------------------------------------------------------ | | `recording` | Capturing. | | `stopping` | Stop was requested and the encoder is finalizing the file. | | `duration_limit_reached` | The 15 minute cap was hit. The recording keeps this status once the file is finalized. | | `size_limit_reached` | The 512 MiB cap was hit. The recording keeps this status once the file is finalized. | | `completed` | Terminal. The file is ready to download. | | `interrupted` | Terminal. The encoder did not exit after a stop or a cap and was killed; the file may be incomplete. | | `failed` | Terminal. The encoder exited on its own with an error, or the file is smaller than 1 KiB. The file is deleted, so download returns `404`. | Limits: - At most 2 recordings can be in progress at once, counting recordings that are recording, stopping, or finishing after the 15-minute or 512 MiB cap; a third start returns `400`. - A recording stops on its own after 15 minutes or 512 MiB, whichever comes first. - Up to 20 finished recordings are kept, including failed and interrupted ones; when a stop or list call finds more, the oldest are deleted with their files. - Labels longer than 120 characters are truncated to 120. ### Start Recording [#start-recording] Start a screen recording with an optional label. The desktop must be ready. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.computer_use.start() recording = sandbox.computer_use.recording.start() print(f"Recording started: {recording.id}") ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------- | | `label` | str | Sets the prefix of the file name. Characters other than letters, digits, and `-` are replaced with `_`, and the result is truncated to 120 characters. The default is `recording`. | ```typescript import { Daytona } from '@daytona/sdk'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); await sandbox.computerUse.start(); const recording = await sandbox.computerUse.recording.start(); console.log(`Recording started: ${recording.id}`); ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------- | | `label` | string | Sets the prefix of the file name. Characters other than letters, digits, and `-` are replaced with `_`, and the result is truncated to 120 characters. The default is `'recording'`. | ```bash curl '{toolboxProxyUrl}/{sandboxId}/computeruse/recordings/start' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{}' ``` | **Field** | **Type** | **Description** | | --------- | -------- | --------------- | | `label` | string | Sets the prefix of the file name. Characters other than letters, digits, and `-` are replaced with `_`, and the result is truncated to 120 characters. The default is `recording`. | ### Stop Recording [#stop-recording] Stop an active recording session by providing the recording ID. The call returns once the file is finalized, with the terminal recording. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.computer_use.start() recording = sandbox.computer_use.recording.start() stopped_recording = sandbox.computer_use.recording.stop(id=recording.id) print(f"Recording stopped: {stopped_recording.duration_seconds} seconds") print(f"Saved to: {stopped_recording.file_path}") ``` ```typescript import { Daytona } from '@daytona/sdk'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); await sandbox.computerUse.start(); const recording = await sandbox.computerUse.recording.start(); const stoppedRecording = await sandbox.computerUse.recording.stop({ id: recording.id }); console.log(`Recording stopped: ${stoppedRecording.durationSeconds} seconds`); console.log(`Saved to: ${stoppedRecording.filePath}`); ``` ```bash curl '{toolboxProxyUrl}/{sandboxId}/computeruse/recordings/stop' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "id": "recording-id" }' ``` ### List Recordings [#list-recordings] Get a list of all recordings in the sandbox, active and finished: ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.computer_use.start() recordings_list = sandbox.computer_use.recording.list() print(f"Total recordings: {len(recordings_list.recordings)}") for rec in recordings_list.recordings: print(f"- {rec.file_name}: {rec.status} {rec.duration_seconds}s ({rec.size_bytes} bytes)") ``` ```typescript import { Daytona } from '@daytona/sdk'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); await sandbox.computerUse.start(); const recordingsList = await sandbox.computerUse.recording.list(); console.log(`Total recordings: ${recordingsList.recordings.length}`); for (const rec of recordingsList.recordings) { console.log(`- ${rec.fileName}: ${rec.status} ${rec.durationSeconds}s (${rec.sizeBytes} bytes)`); } ``` ```bash curl '{toolboxProxyUrl}/{sandboxId}/computeruse/recordings' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ### Get Recording [#get-recording] Get details about a specific recording. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.computer_use.start() recording = sandbox.computer_use.recording.start() recording_detail = sandbox.computer_use.recording.get(recording.id) print(f"Recording: {recording_detail.file_name}") print(f"Status: {recording_detail.status}") print(f"Duration: {recording_detail.duration_seconds}s") ``` ```typescript import { Daytona } from '@daytona/sdk'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); await sandbox.computerUse.start(); const recording = await sandbox.computerUse.recording.start(); const recordingDetail = await sandbox.computerUse.recording.get(recording.id); console.log(`Recording: ${recordingDetail.fileName}`); console.log(`Status: ${recordingDetail.status}`); console.log(`Duration: ${recordingDetail.durationSeconds}s`); ``` ```bash curl '{toolboxProxyUrl}/{sandboxId}/computeruse/recordings/{id}' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ### Delete Recording [#delete-recording] Delete a recording by ID. Deleting an active recording stops it first and then removes the file. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.computer_use.start() recording = sandbox.computer_use.recording.start() sandbox.computer_use.recording.delete(recording.id) print("Recording deleted successfully") ``` ```typescript import { Daytona } from '@daytona/sdk'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); await sandbox.computerUse.start(); const recording = await sandbox.computerUse.recording.start(); await sandbox.computerUse.recording.delete(recording.id); console.log('Recording deleted successfully'); ``` ```bash curl '{toolboxProxyUrl}/{sandboxId}/computeruse/recordings/{id}' \ --request DELETE \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ### Download Recording [#download-recording] Download a recording file from the sandbox. The daemon streams the file. The SDKs hold the whole file in memory and return it as bytes; write it to disk yourself. An active recording can be downloaded, and the response holds the file written so far. ```python from pathlib import Path from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.computer_use.start() recording = sandbox.computer_use.recording.start() sandbox.computer_use.recording.stop(id=recording.id) data = sandbox.computer_use.recording.download(recording.id) Path("local_recording.mp4").write_bytes(data) print(f"Downloaded {len(data)} bytes") ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------- | | `max_response_bytes` | int | Replaces the client's response size cap for this call. A larger recording raises `PayloadTooLargeError`. The default is the client's cap, 1 GiB unless configured. | ```typescript import { writeFile } from 'node:fs/promises'; import { Daytona } from '@daytona/sdk'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); await sandbox.computerUse.start(); const recording = await sandbox.computerUse.recording.start(); await sandbox.computerUse.recording.stop({ id: recording.id }); const data = await sandbox.computerUse.recording.download(recording.id); await writeFile('local_recording.mp4', data); console.log(`Downloaded ${data.byteLength} bytes`); ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------- | | `maxResponseBytes` | number | Replaces the client's response size cap for this call. A larger recording throws `PayloadTooLargeError`. The default is the client's cap, 1 GiB unless configured. | ```bash curl '{toolboxProxyUrl}/{sandboxId}/computeruse/recordings/{id}/download' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --output local_recording.mp4 ``` The response is an MP4 video with the following headers: | **Header** | **Description** | | -------------------------------- | ---------------------------------------- | | `Content-Type` | Reports `video/mp4`. | | `Content-Disposition` | Marks the response as an attachment with the file name. | | `x-daytona-recording-status` | Reports the recording status. | | `x-daytona-recording-incomplete` | Reports `true` when the status is anything other than `completed`, including an active recording and the cap statuses. Absent for completed recordings. | ## Display operations [#display-operations] The virtual display is created when Computer Use starts and runs at 1280x720 with 24-bit color. The resolution is fixed, with no per-sandbox setting. Verify the live geometry with [get info](#get-info). ### Get info [#get-info] Get information about the displays. The response lists every X screen with its ID, position, size, and active flag. The virtual desktop has one screen. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.computer_use.start() info = sandbox.computer_use.display.info() print(f"Total displays: {len(info.displays)}") for display in info.displays: print(f"Display {display.id}: {display.width}x{display.height} at {display.x},{display.y}") ``` ```typescript import { Daytona } from '@daytona/sdk'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); await sandbox.computerUse.start(); const info = await sandbox.computerUse.display.info(); console.log(`Total displays: ${info.displays.length}`); for (const display of info.displays) { console.log(`Display ${display.id}: ${display.width}x${display.height} at ${display.x},${display.y}`); } ``` ```bash curl '{toolboxProxyUrl}/{sandboxId}/computeruse/display/info' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ### Get windows [#get-windows] Get the list of open windows. Each window carries its ID, title, position, size, and active flag. The list is read from the client list property that the window manager maintains, which is why start refuses to run without a window manager. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.computer_use.start() windows = sandbox.computer_use.display.windows() print(f"Found {len(windows.windows)} open windows:") for window in windows.windows: print(f"- {window.title} (ID: {window.id}, active: {window.is_active})") ``` ```typescript import { Daytona } from '@daytona/sdk'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); await sandbox.computerUse.start(); const windows = await sandbox.computerUse.display.windows(); console.log(`Found ${windows.windows.length} open windows:`); for (const window of windows.windows) { console.log(`- ${window.title} (ID: ${window.id}, active: ${window.isActive})`); } ``` ```bash curl '{toolboxProxyUrl}/{sandboxId}/computeruse/display/windows' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ## Errors [#errors] The SDKs raise these errors with the codes in the following table. | **Code** | **Meaning** | **What to do** | | ----------------------- | ----------------------------------------------------------------------------------------------------------- | -------------------------------------- | | **`ADDON_UNAVAILABLE`** | Returned with `503`. The desktop add-on is not in the sandbox, a start or restart did not bring the desktop up, a process restart did not bring the process back within 5 s, or the X server or the accessibility bus cannot be reached. The SDKs raise `AddonUnavailableError`. | Read the [status](#get-status). If the desktop is failed, call [restart](#restart-computer-use). If the add-on is missing, contact us with the sandbox ID. | | **`DESKTOP_NOT_READY`** | Returned with `409`. The desktop is not ready: not started, starting, restarting, or failed. The SDKs raise `DesktopNotReadyError`. | Call [start](#start-computer-use) on a desktop that is not started, or [restart](#restart-computer-use) on a failed one. | ## Permissions [#permissions] Computer Use runs through the toolbox of a sandbox. Access is governed by one project permission, which you can grant to an [organization role](/docs/organizations#roles) or an [API key](/docs/api-keys). A [sandbox access token](/docs/sandboxes#create-an-access-token) with the desktop or toolbox operation grants the same access to a single sandbox, without an API key. The sandbox read permission alone does not grant toolbox access. | **Permission** | **Grants** | | --------------------- | ----------------------------------------------------------------- | | **`write:sandboxes`** | Control the desktop, mouse, keyboard, screenshots, and recordings | # Docker (/docs/docker) Docker runs inside a sandbox as a full Docker Engine, so workloads can build images and run containers the same way they do on a regular Linux machine. Daytona does not install Docker. When the sandbox image ships Docker Engine, the sandbox starts it automatically on every boot; when the image does not, nothing starts. Every Linux sandbox has storage prepared for Docker, with no create-time option. The standard Docker data directories are backed by the sandbox disk, so Docker images, containers, and volumes are stored with the rest of the sandbox filesystem and are kept by [captured images](/docs/images#capture-images) and [snapshots](/docs/snapshots). Docker startup never blocks the sandbox: the sandbox reports as running as soon as the toolbox is reachable, and Docker reports its own readiness through the Docker status. A Docker failure leaves the sandbox usable, so you can read the logs, fix the configuration, and retry. ## Use cases [#use-cases] Docker is used when a workload already runs in containers or builds container images. - **Multi-container applications.** An application with a database, a cache, and its services runs in one sandbox. Docker Engine runs inside the sandbox as on a regular Linux machine. Every Linux sandbox has storage prepared for Docker, with no create-time option. - **Image builds.** CI jobs and agents build container images and test them before a push. Image layers are stored on the sandbox disk, with no separate Docker allowance. A larger disk size at create time stores more images. - **Integration tests.** Tests start databases and other dependencies as containers and remove them after the run. Docker starts after the sandbox is running, so a test [waits for Docker](#wait-for-docker) before it starts containers. The wait fails at once when Docker is failed, not present, disabled, unmanaged, or unsupported. - **Agents that run containers.** An agent pulls and runs containers inside the sandbox, with no access to a Docker daemon on your machines. The sandbox image must ship Docker Engine, because Daytona does not install it. When the image has only the Docker CLI, the Docker status reports not present. - **Prepared environments.** Images and containers pulled once are kept by a captured image or a snapshot. The next sandbox does not pull them again. Each sandbox created from the captured image or snapshot gets its own copy of the Docker images, containers, and volumes. ## Start Docker [#start-docker] Start Docker by creating a sandbox from an image that ships Docker Engine. Docker starts in the background after the sandbox is running, so wait for Docker to become ready before you run Docker commands; a command sent earlier can fail because Docker is not answering yet. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create("docker-dind") # Block until Docker Engine answers, up to 120 seconds sandbox.docker.wait_until_ready(timeout=120) response = sandbox.process.run("docker run --rm hello-world") print(response.stdout) ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create('docker-dind') // Block until Docker Engine answers, up to 120 seconds await sandbox.docker.waitUntilReady({ timeoutSeconds: 120 }) const response = await sandbox.process.run('docker run --rm hello-world') console.log(response.stdout) ``` ```bash daytona sandbox create --image docker-dind # Block until Docker Engine answers, up to 120 seconds daytona sandbox docker status {sandboxId} --wait --timeout 120s ``` ```bash curl 'https://api.daytona.com/sandboxes' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{"image": "docker-dind"}' ``` - The request requires the `write:sandboxes` permission. - Poll `GET /docker/status` on the toolbox until `state` is `ready`. ### Start modes [#start-modes] Choose how Docker starts with a sandbox environment variable, set when you create the sandbox. The sandbox reads it once per boot. The value is case-insensitive, and an unset, empty, or unknown value selects the default automatic mode. In automatic mode, the sandbox first checks the image entrypoint. A recognized Docker entrypoint, which is the Docker Engine daemon itself or the official Docker-in-Docker entrypoint script when it runs the daemon, starts Docker, and the sandbox only waits for it. Otherwise, if the image has the Docker Engine daemon in a standard binary directory, the sandbox starts it as root, waits for it, and then starts the image entrypoint. Recognition is narrow: an entrypoint that starts the daemon another way, such as through a shell command or a process supervisor, is not recognized. The sandbox then starts its own daemon first, and the one the entrypoint starts typically fails against it. Use the entrypoint mode for such images. - **Recognized entrypoints**: `dockerd` with any arguments; `dockerd-entrypoint.sh` with no arguments, a flag as the first argument, or `dockerd` as the first argument; `docker-entrypoint.sh` with `dockerd` or `dockerd-entrypoint.sh` as the first argument. - **Daemon search path**: `/usr/local/bin`, `/usr/bin`, `/usr/sbin`, `/bin`, and `/sbin`. - **Sandbox `PATH`**: not searched for the daemon. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create( "my-dind-image", env={"DAYTONA_DOCKER_START": "entrypoint"}, ) ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create('my-dind-image', { env: { DAYTONA_DOCKER_START: 'entrypoint' }, }) ``` ```bash daytona sandbox create \ --image my-dind-image \ --env DAYTONA_DOCKER_START=entrypoint ``` ```bash curl 'https://api.daytona.com/sandboxes' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "image": "my-dind-image", "env": { "DAYTONA_DOCKER_START": "entrypoint" } }' ``` | **Value** | **Behavior** | | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `auto` (default) | | | `entrypoint` | The image entrypoint starts Docker. The sandbox only waits for the socket and never starts `dockerd` itself. | | `off` | The sandbox neither starts nor waits for Docker, and the state is `disabled`. The image entrypoint still runs, so a recognized Docker entrypoint still starts Docker; the state is then `unmanaged` with owner `entrypoint`. | ## Get Docker status [#get-docker-status] Get the Docker status. The status describes Docker in the current boot and is returned immediately. Reading it never starts or restarts Docker. | **Field** | **Description** | | ---------------------------------------- | ------------------------------------------------------------------------------------------- | | `state` | Where Docker is in its startup. See the table below. | | `owner` | Who starts Docker: `daemon` (the sandbox), `entrypoint` (the image), or `none`. | | `reason` | Why the state is what it is, such as a failure cause; `null` when there is nothing to add. | | `processId` (`process_id` in Python) | The process with Docker's output, or `null`. | | **State** | **Meaning** | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **`ready`** | The Docker socket answers. Docker commands work. | | **`starting`** | Docker is being started or waited for. | | **`deferred`** | Docker startup has not run yet in this boot (reason `gate-closed`), or it is skipped for the whole boot (reason `function-ready-template`). | | **`failed`** | Docker did not come up (start failure, early exit, or the 30-second timeout), or it exited later (reason `exited`). The sandbox stays usable. | | **`not_present`** | The image has no `dockerd`. The reason is `cli-only` when the image has only the `docker` CLI. | | **`disabled`** | `DAYTONA_DOCKER_START` is `off`. | | **`unmanaged`** | `DOCKER_HOST` points to a non-local engine, or `DAYTONA_DOCKER_START` is `off` and a recognized Docker entrypoint starts Docker. The sandbox does not check that engine. | | **`unsupported`** | Docker storage could not be prepared, for example because the image ships a non-empty `/var/lib/docker`, or the sandbox type has no Docker support. | ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create("docker-dind") status = sandbox.docker.status() print(status.state, status.owner, status.reason, status.process_id) ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create('docker-dind') const status = await sandbox.docker.status() console.log(status.state, status.owner, status.reason, status.processId) ``` ```bash daytona sandbox docker status {sandboxId} ``` ```bash curl '{toolboxProxyUrl}/{sandboxId}/docker/status' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` - The request requires the `write:sandboxes` permission. - `{toolboxProxyUrl}` is the `toolbox_proxy_url` field of the [sandbox](/docs/sandboxes#get-a-sandbox). ## Wait for Docker [#wait-for-docker] Wait for Docker to become ready. The wait polls the Docker status and returns as soon as Docker is ready. It fails at once when Docker is failed, not present, disabled, unmanaged, or unsupported, and fails with a timeout when Docker is still not ready at the end of the time budget. ```python from daytona import Daytona from daytona.v2 import DockerNotReadyError, DockerWaitTimeoutError daytona = Daytona() sandbox = daytona.v2.create("docker-dind") try: status = sandbox.docker.wait_until_ready(timeout=120) except DockerNotReadyError as e: print("Docker cannot start:", e.status.state, e.status.reason) except DockerWaitTimeoutError as e: print("Docker is still starting:", e.status) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | ---------------------------------------------------- | | `timeout` | float | Sets how many seconds the wait lasts. `0` waits without a deadline. The default is `60`. Do not pass `0` when Docker is deferred with reason `function-ready-template`, which stays deferred for the whole boot. | ```typescript import { Daytona } from '@daytona/sdk' import { DockerNotReadyError, DockerWaitTimeoutError } from '@daytona/sdk/v2' const daytona = new Daytona() const sandbox = await daytona.v2.create('docker-dind') try { const status = await sandbox.docker.waitUntilReady({ timeoutSeconds: 120 }) } catch (error) { if (error instanceof DockerNotReadyError) { console.log('Docker cannot start:', error.status.state, error.status.reason) } else if (error instanceof DockerWaitTimeoutError) { console.log('Docker is still starting:', error.status) } else { throw error } } ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | ------------------------------------------------------------ | | `timeoutSeconds` | number | Sets how many seconds the wait lasts. `0` waits without a deadline. The default is `60`. Do not pass `0` when Docker is deferred with reason `function-ready-template`, which stays deferred for the whole boot. | ```bash daytona sandbox docker status {sandboxId} --wait --timeout 120s ``` | **Flag** | **Type** | **Description** | | ----------- | -------- | ---------------------------------------------------------------------------- | | `--timeout` | string | Sets how long `--wait` waits, as a duration such as `120s` or `2m`. The default is `60s`. | ```bash # Hold the response for up to 1000 ms while Docker is starting; repeat until state changes curl '{toolboxProxyUrl}/{sandboxId}/docker/status?waitMs=1000' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` | **Field** | **Type** | **Description** | | ---------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `waitMs` | integer | Sets how many milliseconds the response is held. The response is held only while `state` is `starting`. Any other state, including `deferred`, is returned immediately, so space repeated requests yourself. The value is capped at `1000`. | - The request requires the `write:sandboxes` permission. - Stop polling at `ready`, and treat `failed`, `not_present`, `disabled`, `unmanaged`, `unsupported`, and `deferred` with reason `function-ready-template` as final. - The endpoint has no overall time budget, so set a deadline in your client and stop polling when it passes. ## Docker logs [#docker-logs] Read Docker's output. Docker's output is kept in the logs of the process that runs Docker, and the Docker status names that process. When the sandbox starts Docker itself, the process has the fixed name used in the examples below, and its logs stay readable after Docker exits. When the image entrypoint starts Docker, Docker's output is in the entrypoint's logs. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create("docker-dind") status = sandbox.docker.status() if status.process_id: handle = sandbox.process.connect(status.process_id) for frame in handle.logs().items: print(f"[{frame.channel}]: {frame.data}") ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create('docker-dind') const status = await sandbox.docker.status() if (status.processId) { const handle = sandbox.process.connect(status.processId) for (const frame of (await handle.logs()).items) { console.log(`[${frame.channel}]:`, frame.data) } } ``` ```bash daytona sandbox process logs {sandboxId} dockerd ``` - The request requires the `write:sandboxes` permission. - `dockerd` addresses Docker only when the Docker status owner is `daemon`. - When the owner is `entrypoint`, pass the process ID from `daytona sandbox docker status` instead. ```bash curl '{toolboxProxyUrl}/{sandboxId}/processes/dockerd/logs' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` - The request requires the `write:sandboxes` permission. - `dockerd` addresses Docker only when the Docker status `owner` is `daemon`. - When the owner is `entrypoint`, use the `processId` from `GET /docker/status` instead. ## Docker storage [#docker-storage] Docker data lives on the sandbox disk, at the standard paths for rootful Docker: | **Path** | **Contents** | | ------------------------- | --------------------------------------------------------------- | | **`/var/lib/docker`** | Docker's image layers, containers, and local volumes. | | **`/var/lib/containerd`** | containerd's image content, used by Docker Engine 29 and later. | Docker shares the sandbox disk with everything else in the sandbox; there is no separate Docker allowance. To store more images or containers, raise the sandbox disk size at create time. If either of these paths is not empty in the image, or is a symbolic link, the contents are left untouched, Docker storage is not prepared, and the Docker storage state reports it as unsupported. Images that preload Docker data this way are not supported. ### Persistence [#persistence] Because Docker data is part of the sandbox disk, it follows the sandbox's [persistence](/docs/persistence): | **Operation** | **Docker data** | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Images and snapshots** | Each sandbox created from a [captured image](/docs/images#capture-images) or a [snapshot](/docs/snapshots#restore-snapshots) gets its own copy of the source's Docker images, containers, and volumes, and can create new ones. | A boot from a captured image is a reboot: running containers come back stopped and restart per their Docker restart policy. To resume running containers with their processes intact, use a snapshot. ## Permissions [#permissions] Docker access runs through the toolbox of a sandbox. Access is governed by one project permission, which you can grant to an [organization role](/docs/organizations#roles) or an [API key](/docs/api-keys). A [sandbox access token](/docs/sandboxes#create-an-access-token) with the toolbox operation grants the same access to a single sandbox, without an API key. The sandbox read permission alone does not grant toolbox access. | **Permission** | **Grants** | | --------------------- | ----------------------------------------------- | | **`write:sandboxes`** | Start Docker, get its status, and read its logs | # Web Terminal (/docs/web-terminal) Daytona provides a browser-based web terminal for your sandboxes. Run commands, view files, and debug from your browser without installing local tools. ## Use cases [#use-cases] The web terminal is used when a person needs a shell in a sandbox from the browser, with no local tools. - **Command execution.** A person runs shell commands in the sandbox from the sandbox details page. On a Linux sandbox whose desktop is neither starting nor ready, the **Terminal** tab opens by default, so opening the sandbox lands in a shell. The shell is the login shell of the sandbox user, or the first of bash, zsh, and sh found on the PATH. - **File management.** A person moves through the file system and views and edits files. **Open terminal here** in the **Files** tab starts a shell in the selected folder. Members without the sandbox write permission do not see the **Files** tab. - **Full-screen programs.** Programs such as `top`, `vim`, and `htop` work as in a local terminal. Resizing the browser window resizes the terminal in the sandbox. Each session starts at 80x24 and is resized to fit the browser viewport right away. - **Debugging.** A person reads logs, checks processes, and finds the cause of a problem in a running sandbox. The terminal works only while the sandbox is running, so start a stopped sandbox first. Stopping or restarting the sandbox ends every shell, and the **Terminal** tab starts a fresh session once the sandbox runs again. - **Shells shared with code.** Each session is a PTY process, so the SDK, the CLI, or the API can attach to the same shell. The browser and the attached client share keystrokes and output. A client finds a session by its name, `web-term-` followed by a number. ## Access from Dashboard [#access-from-dashboard] The web terminal is built into the sandbox details page of the [Daytona Dashboard ↗](https://app.daytona.com/dashboard/sandboxes). 1. Go to [Daytona Sandboxes ↗](https://app.daytona.com/dashboard/sandboxes) 2. Locate the running sandbox you want to access 3. Click **Open terminal** in the sandbox row, or the sandbox's **Terminal** tab The **Terminal** tab is the default tab of the sandbox details page for Linux sandboxes whose desktop is not starting or ready, so opening such a sandbox lands you directly in a shell. macOS and Windows sandboxes, and Linux sandboxes with a starting or ready desktop, open on the **Desktop** tab. The tab also opens directly from a sandbox details URL whose tab query parameter is set to terminal. The web terminal is available only for sandboxes in the running state. If your sandbox is stopped, start it before attempting to access the terminal. ### Multiple sessions [#multiple-sessions] Each terminal tab is an interactive shell running as a [PTY process](/docs/pty) inside the sandbox. Opening the **Terminal** tab on a sandbox with no sessions creates the first one automatically. You can: - Open additional sessions with the **+** button and switch between them - Drag tabs to reorder them, or right-click a tab to close, close others, or pin it - Close a session to stop its shell process Pinned tabs stay fixed on the left of the tab strip, cannot be dragged, and are skipped by **Close others**. Tab order, pinned tabs, and the active tab are remembered in your browser per sandbox, so reopening the sandbox restores the same layout. Sessions stay alive while the sandbox runs, so reloading the page reconnects to your existing shells. A shell that exits on its own, for example after the exit command, closes its tab within seconds. ### Open a terminal in a directory [#open-a-terminal-in-a-directory] From the **Files** tab, open the actions menu (**⋯**) of a folder and choose **Open terminal here** to start a new terminal session with that directory as its working directory. ## Shell [#shell] Each session starts an interactive shell with an initial size of 80x24 that is immediately resized to fit the browser viewport. The shell is the login shell of the sandbox user, falling back to bash, zsh, then sh from the PATH. Full-screen programs such as top, vim, or htop work as in a local terminal. Resizing the browser window or the side panel resizes the remote PTY. ## Sessions and scrollback [#sessions-and-scrollback] Web terminal sessions are regular PTY processes on the sandbox, named with a web-term prefix and a number that sets the tab title. Only web-term processes appear as tabs; the web terminal neither shows nor touches PTY sessions started through the SDK or API. Sessions are ordinary processes, so you can list and attach to them programmatically. SDK and browser clients attached at once share one shell, including keystrokes and output. ```python processes = sandbox.process.list(kind="pty", state="running") session = next((info for info in processes.items if info.name and info.name.startswith("web-term-")), None) if session is None: raise RuntimeError("no web terminal session") print(f"{session.name}: {session.id} (cwd {session.cwd})") # Attach to the web terminal session by its process id handle = sandbox.pty.connect(session.id) handle.write_stdin('echo "Hello from the SDK"\n') ``` ```typescript const processes = await sandbox.process.list({ kind: 'pty', state: 'running' }) const session = processes.items.find((info) => info.name?.startsWith('web-term-')) if (!session) throw new Error('no web terminal session') console.log(`${session.name}: ${session.id} (cwd ${session.cwd})`) // Attach to the web terminal session by its process id const handle = sandbox.pty.connect(session.id) const connection = await handle.attach() connection.write('echo "Hello from the SDK"\n') ``` - The request requires the `write:sandboxes` permission. - `attach` needs a global `WebSocket` class. ```bash # List running PTY processes; web terminal sessions are named web-term- daytona sandbox process list {sandboxId} --kind pty --state running # A live session can also be fetched by name daytona sandbox process get {sandboxId} web-term-1 # Attach to a web terminal session daytona sandbox process attach {sandboxId} web-term-1 ``` ```bash # List running PTY processes; web terminal sessions are named web-term- curl '{toolboxProxyUrl}/{sandboxId}/processes?kind=pty&state=running' \ --header 'Authorization: Bearer ' # A live session can also be fetched by name curl '{toolboxProxyUrl}/{sandboxId}/processes/web-term-1' \ --header 'Authorization: Bearer ' ``` - The request requires the `write:sandboxes` permission. - `{toolboxProxyUrl}` is the `toolbox_proxy_url` field of the [sandbox](/docs/sandboxes#get-a-sandbox). ## Security [#security] Terminal access is restricted to authenticated members of your [organization](/docs/organizations) whose [project API key](/docs/api-keys) holds the sandbox write permission. Members without this permission do not see the Terminal, Files, Desktop, or SSH tabs, and the terminal icon is hidden in the sandbox list. The terminal is served through the toolbox proxy, which authenticates every request with a short-lived access token scoped to that sandbox; making a [preview endpoint](/docs/preview) public does not expose the terminal. The web terminal provides full shell access to your sandbox. Grant the sandbox write permission only to members who should be able to run arbitrary commands in your sandboxes. # SSH Access (/docs/ssh-access) Daytona provides SSH access to sandboxes through an SSH gateway, so you can connect from local terminals, IDEs, and development tools without installing software in the sandbox. SSH has no equivalent of a bearer header, so the credential travels in the SSH username: the sandbox ID and the credential, joined by a hash character. The credential is a sandbox access token that allows SSH, or a project API key. Connect to the SSH gateway of the sandbox's region: ```bash ssh -p 2222 '#'@ ``` The gateway splits the username on the first hash character, validates the credential for that sandbox, and proxies the session to the SSH server inside the sandbox. The sandbox ID part accepts either the region-tagged ID that the API returns or the bare UUID. The gateway accepts the SSH handshake without client authentication and authorizes afterwards, so a rejected connection is closed right after the handshake instead of failing with a password prompt. Connections are rejected when: - The credential is invalid or expired, belongs to another project, or does not allow SSH to the sandbox - The sandbox ID is unknown, or the sandbox lives in a different region than the gateway - The sandbox is not `running` - The username has no `#` separator, or either part is empty The sandbox reports running once its toolbox port answers. The in-sandbox SSH server can lag behind by a few seconds after a create, so a connection opened immediately after the sandbox becomes running may be closed. Retry the connection. The SSH gateway host is region-specific, and the examples on this page use `` in its place. Use the host shown in the Dashboard's **SSH** tab, or read `ssh_gateway_host` and `ssh_gateway_port` from the [sandbox details](#access-via-api). ## Use cases [#use-cases] SSH access is used when a local tool needs a shell or a TCP connection inside a sandbox. - **Remote development in an IDE.** VS Code and JetBrains IDEs connect over SSH, then edit and run code in the sandbox. JetBrains Gateway installs the selected IDE in the sandbox. Each IDE takes the SSH command from the Dashboard as its connection URL. - **Local terminals.** A developer opens a shell in the sandbox from their own terminal, with no software installed in the sandbox. Resizing the local window resizes the remote shell. The session has no idle timeout of its own and stays open while the sandbox runs. - **File transfer.** `scp` and `sftp` copy files between your machine and the sandbox with the standard OpenSSH clients. Relative paths resolve against the working directory, which is the image's `WORKDIR` or the home directory. A sandbox created with a default user uses that user's home directory instead. - **Scripts and pipelines.** A one-shot command returns the exit code of the remote command, with stdout and stderr on separate streams. Input piped into `ssh` reaches the remote command. Closing stdin on the client half-closes the remote stdin, so piped commands end once they consume the input. - **Sandbox services on your machine.** Local port forwarding connects a local port to a database or web server in the sandbox, without exposing it to the internet. The target address resolves inside the sandbox, so `localhost:8080` reaches a service bound there. Remote forwarding with `-R` is not supported. ## Access from Dashboard [#access-from-dashboard] The [Daytona Dashboard ↗](https://app.daytona.com/dashboard/sandboxes) builds the SSH command for you. 1. Go to [Sandboxes ↗](https://app.daytona.com/dashboard/sandboxes) 2. Locate the sandbox you want to connect to 3. Select **SSH access** in the options menu (**⋮**), or the sandbox's **SSH** tab 4. Copy the **SSH command** and run it in your terminal The command carries a sandbox access token that allows only SSH to this sandbox and expires after 15 minutes. The Dashboard creates a new token each time the SSH tab opens. The token is masked in the panel; use **Reveal token** to show it. Copying always yields the full command. Only members whose project API key has sandbox write permission see the SSH tab. ## Access via CLI [#access-via-cli] The Daytona CLI resolves the SSH gateway of the sandbox's region and runs the system SSH client with your credential in the username. ```bash # Interactive shell daytona sandbox ssh {sandboxId} # One-shot command daytona sandbox ssh {sandboxId} uname -a # Forward a sandbox port to your machine daytona sandbox ssh {sandboxId} -L 8080:localhost:8080 ``` - The request requires the `write:sandboxes` permission. - The CLI requires OpenSSH `ssh` on your `PATH`. - SSH flags after the sandbox ID go to `ssh` before the destination. - SSH flags end at the first argument that does not start with `-` and is not the value of a flag such as `-L` or `-p`. - Use `--` to end the SSH flags explicitly when the remote command itself starts with `-`. - Any remaining arguments become the remote command. ## Access via API [#access-via-api] The sandbox details include the SSH gateway endpoint for the sandbox's region: ```bash curl 'https://api.daytona.com/sandboxes/{sandboxId}' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` Build the SSH command from the SSH gateway host and port fields in the response, the sandbox ID, and a [sandbox access token](#create-an-ssh-token) or your API key. Both fields are absent when the region's gateway cannot be resolved. Each region configures its own gateway host; a region without one uses the host of its toolbox proxy URL. The port defaults to 2222. ### Create an SSH token [#create-an-ssh-token] Create a sandbox access token that allows only SSH to one sandbox. A token expires after its lifetime and cannot be renewed, so create a new one when it expires. Use a token instead of a project API key when you hand SSH access to a person, a CI job, or another tool. ```python token = sandbox.create_access_token(operations=["ssh"], ttl_seconds=3600) print(f"ssh -p 2222 '{sandbox.id}#{token.access_token}'@") ``` | **Parameter** | **Type** | **Description** | | ------------- | --------- | ---------------------------------------------------------------------------------------------- | | `operations` | list\[str\] | Sets the operations the token allows. `["ssh"]` limits it to SSH. | | `ttl_seconds` | int | Sets the token lifetime in seconds, at most `86400`. The default is `3600`. | ```typescript const token = await sandbox.createAccessToken({ operations: ['ssh'], ttlSeconds: 3600 }) console.log(`ssh -p 2222 '${sandbox.id}#${token.accessToken}'@`) ``` | **Parameter** | **Type** | **Description** | | ------------- | --------- | ---------------------------------------------------------------------------------------------- | | `operations` | string\[\] | Sets the operations the token allows. `['ssh']` limits it to SSH. | | `ttlSeconds` | number | Sets the token lifetime in seconds, at most `86400`. The default is `3600`. | ```bash curl 'https://api.daytona.com/sandboxes/{sandboxId}/access-token' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{"operations": ["ssh"], "ttl_seconds": 3600}' ``` | **Field** | **Type** | **Description** | | ------------- | --------- | ---------------------------------------------------------------------------------------------- | | `operations` | string\[\] | Sets the operations the token allows. `["ssh"]` limits it to SSH. | | `ttl_seconds` | integer | Sets the token lifetime in seconds. Defaults to 3600, and the maximum is 86400. | - The request requires the `write:sandboxes` permission. - Put the `access_token` field of the response after the hash character in the SSH username. ## Usage examples [#usage-examples] The gateway forwards every SSH channel and channel request, so interactive shells, one-shot commands, scp, sftp, and local port forwarding work with the standard OpenSSH clients. ```bash # Interactive shell ssh -p 2222 '#'@ # One-shot command ssh -p 2222 '#'@ uname -a # Pipe stdin into a remote command cat ./input.txt | ssh -p 2222 '#'@ wc -l # Copy a file into the sandbox scp -P 2222 ./file.txt '#'@:/work/ # Interactive file transfer sftp -P 2222 '#'@ # Forward a sandbox port to your machine ssh -p 2222 -L 8080:localhost:8080 '#'@ ``` Exit codes are preserved, so one-shot SSH commands can be used in scripts and pipelines. Standard output and standard error arrive as separate streams, so redirecting standard error on the client side works as with any SSH host. Closing stdin on the client half-closes the remote command's stdin, so piped commands terminate once the input is consumed. ## Session environment [#session-environment] An SSH session on a Linux sandbox lands in the SSH server run by the Daytona daemon: | **Property** | **Behavior** | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Shell** | The first of `bash`, then `zsh`, listed in the sandbox's `/etc/shells`; `sh` when neither is listed. A sandbox created with a default `user` uses that user's login shell instead. Interactive sessions and one-shot commands use the same shell. | | **Working directory** | The daemon's, which is the image's `WORKDIR` or, if none, the home directory. A sandbox created with a default `user` uses that user's home directory instead. One-shot commands run there, and relative `scp` and `sftp` paths resolve against it. | | **Terminal** | Honors `pty-req` and `window-change`, so resizes reach the shell. | | **Idle timeout** | None; the sandbox lifecycle, not the SSH server, ends idle sessions. | ## Port forwarding [#port-forwarding] Local forwarding opens a TCP connection inside the sandbox for every connection to the local port. The target address is resolved inside the sandbox, so a target on localhost reaches a service in the sandbox, not on your machine. - Local forwarding uses the `-L` flag. `-L 8080:localhost:8080` reaches a service bound to `localhost:8080` in the sandbox. - A target port with nothing listening is refused with `open failed: connect failed`. - An unresponsive target times out after 10 seconds. ```bash # Reach a sandbox web server on http://localhost:8080 ssh -p 2222 -N -L 8080:localhost:8080 '#'@ ``` The following are not supported through the gateway: - **Remote forwarding (`-R`)**: rejected, with `remote port forwarding failed`. - **Unix socket forwarding** (`-L`/`-R` with socket paths) - **Agent forwarding (`-A`)** To expose a sandbox port to the internet rather than to your machine, use [sandbox previews](/docs/preview). ## Connection lifetime [#connection-lifetime] An SSH session stays open for as long as the sandbox is running. The gateway closes the client connection promptly when the sandbox stops running or is deleted. Reconnecting with the same command attaches to the sandbox again. For long interactive sessions, wrap ssh in a reconnect loop or use autossh; set the ServerAliveInterval option so the client notices a dead connection quickly: ```bash ssh -p 2222 -o ServerAliveInterval=3 -o ServerAliveCountMax=2 '#'@ ``` SSH traffic counts toward the sandbox's [idle timeout](/docs/linux-sandboxes#idle-timeout). The gateway records activity once the in-sandbox SSH server has answered, and then whenever bytes flow from the client into the sandbox. A one-shot command run without a terminal keeps the sandbox active for as long as it runs. Otherwise an open session with no input does not keep the sandbox alive: a shell left idle at the prompt, or a command in a terminal session that produces output without further input, does not reset the idle clock. Type into the session or reconnect to reset it. ## Connect with VS Code [#connect-with-vs-code] You can connect VS Code directly to your sandbox using the Remote SSH extension. 1. Install the [Remote Explorer extension ↗](https://marketplace.visualstudio.com/items?itemName=ms-vscode.remote-explorer) 2. Add a new SSH connection 3. When prompted for the SSH connection URL, paste the SSH command from above For more information, see the [VS Code Remote SSH documentation ↗](https://code.visualstudio.com/docs/remote/ssh). ## Connect with JetBrains IDEs [#connect-with-jetbrains-ides] JetBrains Gateway provides remote development support for connecting to your sandbox. 1. Download [JetBrains Gateway ↗](https://www.jetbrains.com/remote-development/gateway/) 2. Add a new connection 3. When prompted for the SSH connection URL, paste the SSH command from above 4. Select the IDE to install in your sandbox ## Security [#security] SSH access is stateless, with no per-sandbox access list. A sandbox access token reaches only its sandbox and only the operations it allows, until it expires. A project API key reaches every sandbox in the project and the API, so prefer a token for SSH. Anyone with the SSH command can access the sandbox while its credential is valid. Treat it like a secret. A sandbox access token stays valid until it expires and cannot be revoked. To cut off access through an API key, revoke or rotate the key on the [API keys](/docs/api-keys) page. ### Host keys [#host-keys] The host key your client sees is the gateway's, not the sandbox's. Each region's gateway presents one stable ed25519 host key, so the known hosts file holds one entry per gateway host and stays valid across sandboxes and gateway restarts. A host key change warning for a gateway host you have connected to before should be treated as suspicious. The gateway-to-sandbox hop runs inside the private overlay network. The in-sandbox SSH server is reachable only from the gateway, not from other sandboxes or the internet. ## Permissions [#permissions] SSH access uses the sandbox permissions of the project, which you can grant to an [organization role](/docs/organizations#roles) or an [API key](/docs/api-keys). A [sandbox access token](/docs/sandboxes#create-an-access-token) with the ssh operation grants SSH access to a single sandbox, without an API key. | **Permission** | **Grants** | | --------------------- | -------------------------------------------------------------- | | **`write:sandboxes`** | Connect over SSH with an API key, and create SSH access tokens | # VNC Access (/docs/vnc-access) VNC (Virtual Network Computing) access provides a graphical desktop environment for your Daytona Sandbox directly in the browser. This allows you to interact with GUI applications, desktop tools, and visual interfaces running inside your sandbox. VNC and [computer use](/docs/computer-use) work together for manual and automated desktop interactions. VNC is the visual interface for users, while computer use is the programmatic API for AI agents to automate mouse, keyboard, and screenshot operations. Through VNC, you can watch agents perform computer use tasks in real time. The desktop stack (D-Bus, Xvfb, the XFCE window manager, and the x11vnc server) ships with the sandbox runtime as a self-contained add-on, so it works on any Linux sandbox image, including custom images that carry no desktop packages. The virtual display runs at 1280x720. The desktop is available for Linux sandboxes. ## Use cases [#use-cases] VNC access is used when a person needs to see or operate the desktop of a sandbox. - **Computer-use agents.** A person follows what an agent does on the desktop as it happens, from the browser. The agent drives the mouse and keyboard through Computer Use, and VNC shows the same desktop. Desktop interaction calls, such as screenshots and mouse and keyboard input, fail with a desktop-not-ready error until the desktop is ready. - **Takeover from an agent.** A person operates the desktop directly when an agent cannot continue, for example at a login screen. The **Desktop** tab in the Dashboard gives mouse and keyboard control over the same desktop. Only members whose project API key has the sandbox write permission see that tab. - **GUI applications.** Desktop applications with no web or command-line interface run in the sandbox and are used from the browser. The desktop stack ships with the sandbox runtime, so it works on any Linux image, including custom images without desktop packages. The virtual display runs at 1280x720. - **Desktop test debugging.** A person watches GUI tests run and inspects the desktop after a failure. A desktop restart clears all application windows, so inspect the desktop before you restart it. When the desktop itself fails, its status carries a cause with a code and a message. - **Your own VNC client.** Any VNC client that supports WebSocket, such as noVNC, connects to the desktop through the Daytona proxy. An application embeds the desktop in its own interface. Browser clients that cannot set headers pass the API key as a query parameter. ## Access VNC from Dashboard [#access-vnc-from-dashboard] Open the sandbox desktop directly from the [Daytona Dashboard ↗](https://app.daytona.com/dashboard/sandboxes). 1. Go to [Daytona Sandboxes ↗](https://app.daytona.com/dashboard/sandboxes) 2. Open the sandbox you want to access. The sandbox must be in the `running` state. 3. Select the **Desktop** tab (also reachable via `?tab=desktop` in the URL) 4. If the desktop is not started yet, click The Dashboard polls the desktop status while it starts and then connects a VNC viewer in your browser, providing mouse and keyboard control over the sandbox's graphical interface. Click into the frame to interact, and use for a larger view or if the connection drops. If the desktop fails to start, the tab shows the failure cause and offers . The Desktop tab is shown only to members whose project API key has the sandbox write permission, alongside the Terminal, Files, and SSH tabs. ## Programmatic VNC management [#programmatic-vnc-management] Daytona provides methods to [start](#start-vnc), [stop](#stop-vnc), [monitor](#get-vnc-status), and [restart](#restart-vnc) the desktop processes programmatically using the [computer use](/docs/computer-use) references as part of automated workflows. ### Start VNC [#start-vnc] Start the desktop processes: D-Bus, Xvfb, the window manager, and the x11vnc server. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() result = sandbox.computer_use.start() print("VNC processes started:", result.message) ``` ```typescript import { Daytona } from '@daytona/sdk'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); const result = await sandbox.computerUse.start(); console.log('VNC processes started:', result.message); ``` ```bash curl '{toolboxProxyUrl}/{sandboxId}/computeruse/start' \ --request POST \ --header 'Authorization: Bearer YOUR_API_KEY' ``` - The request requires the `write:sandboxes` permission. - `{toolboxProxyUrl}` is the `toolbox_proxy_url` field of the [sandbox](/docs/sandboxes#get-a-sandbox). ### Stop VNC [#stop-vnc] Stop all desktop processes in the sandbox. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.computer_use.start() result = sandbox.computer_use.stop() print("VNC processes stopped:", result.message) ``` ```typescript import { Daytona } from '@daytona/sdk'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); await sandbox.computerUse.start(); const result = await sandbox.computerUse.stop(); console.log('VNC processes stopped:', result.message); ``` ```bash curl '{toolboxProxyUrl}/{sandboxId}/computeruse/stop' \ --request POST \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ### Get VNC status [#get-vnc-status] Check whether the desktop is running. The status field is active or inactive, and the desktop field reports the lifecycle stage: not started, starting, ready, or failed. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() status = sandbox.computer_use.status() print("VNC status:", status.status, status.desktop) ``` ```typescript import { Daytona } from '@daytona/sdk'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); const status = await sandbox.computerUse.status(); console.log('VNC status:', status.status, status.desktop); ``` ```bash curl '{toolboxProxyUrl}/{sandboxId}/computeruse/status' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ### Restart VNC [#restart-vnc] Tear down the desktop processes and start a fresh desktop. Restart is valid from every state and is the only way out of the failed state. Application windows live inside the X server, so a restart returns an empty desktop. The response reports an active status and a ready desktop. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.computer_use.start() result = sandbox.computer_use.restart() print("VNC restarted:", result.message, result.desktop) ``` ```typescript import { Daytona } from '@daytona/sdk'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); await sandbox.computerUse.start(); const result = await sandbox.computerUse.restart(); console.log('VNC restarted:', result.message, result.desktop); ``` ```bash curl '{toolboxProxyUrl}/{sandboxId}/computeruse/restart' \ --request POST \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ### Desktop states [#desktop-states] The desktop field of the [status](#get-vnc-status) response is the desktop lifecycle state. The status field is derived from it: active when the desktop is ready, inactive otherwise. | **`desktop`** | Meaning | Next step | | ------------- | -------------------------------------------------------------------- | -------------------------------------------------- | | `not_started` | No desktop is running. Also the state after a sandbox stop or start. | Call [start](#start-vnc). | | `starting` | The desktop stack is coming up. | Poll status until `ready`. | | `ready` | The desktop is running and the VNC server accepts connections. | Connect a viewer or run Computer Use operations. | | `failed` | The desktop stopped working. `cause` carries `code` and `message`. | Call [restart](#restart-vnc). | Only a failed desktop has a cause object, with the platform detail in its message. Its code names what was lost: | **`cause.code`** | Meaning | | -------------------------- | --------------------------------------------------------------------------- | | `desktop_exited` | The X server (`xvfb`) exited. Windows live inside it, so the desktop is gone. | | `addon_crashed` | The desktop supervisor died while a desktop existed. | | `start_failed` | Starting the stack or probing its readiness failed. | | `start_interrupted` | The supervisor died while the desktop was starting. | | `state_corrupt` | The retained desktop state could not be read or validated. | | `state_persistence_failed` | A desktop state transition could not be persisted. | Treat unknown codes as failures as well; the list grows additively. Lifecycle rules: - Every Computer Use operation (mouse, keyboard, screenshot, display, accessibility, recording start) requires `ready`; otherwise it returns `409` `DESKTOP_NOT_READY`, raised by the SDKs as `DesktopNotReadyError`. Nothing retries it; a failed desktop cannot heal by retry. - On a `ready` desktop, `start` returns the process status; on `starting` or `failed`, `409 DESKTOP_NOT_READY`. Retrying `start` cannot wipe a failed desktop. - `stop` kills a `failed` desktop's processes, but only `restart` leaves `failed`. - `dbus`, `wm`, and `x11vnc` restart automatically with backoff if they exit; the desktop stays `ready`. `xvfb` never does, and restarting it per process returns `400`; use [restart](#restart-vnc). - Without the desktop add-on, `computeruse` endpoints return `503` `ADDON_UNAVAILABLE`. ```python from daytona import Daytona from daytona.v2 import DesktopNotReadyError daytona = Daytona() sandbox = daytona.v2.create() status = sandbox.computer_use.status() if status.desktop == "failed": print("Desktop failed:", status.cause.code, status.cause.message) sandbox.computer_use.restart() try: sandbox.computer_use.screen.screenshot() except DesktopNotReadyError as e: print("Desktop not ready:", e) ``` ```typescript import { Daytona } from '@daytona/sdk'; import { DesktopNotReadyError } from '@daytona/sdk/v2'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); const status = await sandbox.computerUse.status(); if (status.desktop === 'failed') { console.log('Desktop failed:', status.cause.code, status.cause.message); await sandbox.computerUse.restart(); } try { await sandbox.computerUse.screen.screenshot(); } catch (e) { if (e instanceof DesktopNotReadyError) console.log('Desktop not ready:', e.message); } ``` ```bash # Failed desktop curl '{toolboxProxyUrl}/{sandboxId}/computeruse/status' \ --header 'Authorization: Bearer YOUR_API_KEY' # {"status":"inactive","desktop":"failed", # "cause":{"code":"desktop_exited","message":"Xvfb (:99) exited unexpectedly (signal 11)"}} # Any action while not ready curl '{toolboxProxyUrl}/{sandboxId}/computeruse/screenshot' \ --header 'Authorization: Bearer YOUR_API_KEY' # HTTP 409 {"statusCode":409,"code":"DESKTOP_NOT_READY", # "message":"desktop failed: Xvfb (:99) exited unexpectedly (signal 11); call POST /computeruse/restart", ...} ``` For additional process management operations including restarting individual processes and viewing logs, see the [computer use](/docs/computer-use) reference. ## Connect with your own VNC client [#connect-with-your-own-vnc-client] The sandbox's VNC server is bridged through the Daytona proxy as a WebSocket that speaks the standard RFB protocol. Any WebSocket-capable VNC client, such as noVNC, can connect to it and authenticate with your API key. - The WebSocket address is `wss://toolbox.daytona.com/vnc/{sandboxId}`. - The API key goes in an `Authorization: Bearer ` header, or, for browser clients that cannot set headers, in the `daytona_token` query parameter: ```text wss://toolbox.daytona.com/vnc/{sandboxId}?daytona_token= ``` The desktop processes must be [started](#start-vnc) and the sandbox running. Before the WebSocket handshake completes, the proxy returns 401 for a missing or invalid credential, 404 for an unknown sandbox, 409 if it is not running, and 502 if the VNC server is unreachable. The VNC server itself runs without a VNC password and in shared mode: the API key is the only credential, a viewer that prompts for a VNC password is not talking to the sandbox desktop, and several viewers can be attached to the same desktop at once. The bridge carries raw RFB in binary WebSocket frames and echoes the binary subprotocol when the client requests it. ## VNC sessions and the idle timer [#vnc-sessions-and-the-idle-timer] A connected VNC session counts as sandbox activity for the [idle timeout](/docs/linux-sandboxes#idle-timeout). The proxy records activity when the session connects and whenever the viewer sends bytes. VNC viewers send protocol traffic while the user is idle, so an open session keeps the sandbox alive until it closes. Close the viewer, or the Dashboard's Desktop tab, to let the idle timer run. ## Automating desktop interactions [#automating-desktop-interactions] Once VNC is running, automate desktop interactions with Computer Use: AI agents can control the mouse and keyboard and capture screenshots within the VNC session. **Available operations:** - **Mouse**: click, move, drag, scroll, and get cursor position - **Keyboard**: type text, press keys, and execute hotkey combinations - **Screenshot**: capture full screen, regions, or compressed images - **Display**: get display information and list open windows For complete documentation on automating desktop interactions, see [computer use](/docs/computer-use). > **Example**: Automated browser interaction ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() # Start VNC processes sandbox.computer_use.start() # Click to open browser sandbox.computer_use.mouse.click(x=50, y=50, button="left") # Type a URL sandbox.computer_use.keyboard.type(text="https://www.daytona.io/docs/") sandbox.computer_use.keyboard.key(key="enter") # Take a screenshot screenshot = sandbox.computer_use.screen.screenshot() ``` - The request requires the `write:sandboxes` permission. - `start()` returns once the X server and the VNC server accept connections. - Later calls do not need to poll the status. - On a failed desktop, call `restart()` instead of `start()`. ```typescript import { Daytona } from '@daytona/sdk'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); // Start VNC processes await sandbox.computerUse.start(); // Click to open browser await sandbox.computerUse.mouse.click({ x: 50, y: 50, button: 'left' }); // Type a URL await sandbox.computerUse.keyboard.type({ text: 'https://www.daytona.io/docs/' }); await sandbox.computerUse.keyboard.key({ key: 'enter' }); // Take a screenshot const screenshot = await sandbox.computerUse.screen.screenshot(); ``` - The request requires the `write:sandboxes` permission. - `start()` resolves once the X server and the VNC server accept connections. - Later calls do not need to poll the status. - On a failed desktop, call `restart()` instead of `start()`. ## Permissions [#permissions] VNC access runs through the toolbox of a sandbox. Access is governed by one project permission, which you can grant to an [organization role](/docs/organizations#roles) or an [API key](/docs/api-keys). A [sandbox access token](/docs/sandboxes#create-an-access-token) with the desktop operation grants the same access to a single sandbox, without an API key. The sandbox read permission alone does not grant toolbox access. | **Permission** | **Grants** | | --------------------- | --------------------------------------- | | **`write:sandboxes`** | Start, stop, and connect to the desktop | # VPN Connections (/docs/vpn-connections) VPN connections are a way to connect your Daytona sandboxes to private networks. By establishing a VPN connection, your sandbox can access network resources using private IP addresses and can be accessed by other devices on the same VPN network. This integration enables communication between your development environment and existing infrastructure, allowing you to test applications against services within the private network, access shared development resources, and collaborate with team members. Daytona supports the following VPN network providers: - [Tailscale](#tailscale) - [OpenVPN](#openvpn) - [Netbird](#netbird) For connecting to a VPN network, you need to [create or access your Daytona sandbox](/docs/sandboxes), **have access to your VPN network provider credentials**, and be on [**Tier 3** or higher](/docs/limits). ## Tailscale [#tailscale] Daytona provides multiple ways to connect to a Daytona sandbox with a Tailscale network: - [Connect with browser login](#tailscale-browser-login) - [Connect with auth key](#tailscale-auth-key) - [Connect with web terminal](#tailscale-web-terminal) When you connect a Daytona sandbox to a Tailscale network, the sandbox becomes part of your private Tailscale network, allowing you to access resources that are available within the network and enabling other devices on the network to access the sandbox. This integration makes your sandbox appear as a device within your Tailscale network, with its own Tailscale IP address and access to other devices and services on the network. ### Tailscale browser login [#tailscale-browser-login] The browser login method initiates an interactive authentication flow where Tailscale generates a unique login URL that you visit in your web browser to authenticate the Daytona sandbox. The process involves installing Tailscale, starting the daemon, initiating the login process, and then polling for the authentication status until the connection is established. The following snippet demonstrates connecting to a Tailscale network using a browser login. ```python from daytona import Daytona, DaytonaConfig import time import re # Configuration DAYTONA_API_KEY = "YOUR_API_KEY" # Replace with your API key # Initialize the Daytona client config = DaytonaConfig(api_key=DAYTONA_API_KEY) daytona = Daytona(config) def setup_tailscale_vpn_interactive(): """ Connect a Daytona sandbox to a Tailscale network using the Python SDK. Uses interactive login via browser URL (no auth key required). """ # Create the sandbox print("Creating sandbox...") sandbox = daytona.v2.create("ubuntu-24.04") print(f"Sandbox created: {sandbox.id}") # Step 1: Install Tailscale print("\nInstalling Tailscale (this may take a few minutes)...") response = sandbox.process.run( "curl -fsSL https://tailscale.com/install.sh | sh", timeout=300 ) if response.exit_code != 0: print(f"Error installing Tailscale: {response.output}") return sandbox print("Tailscale installed successfully.") # Step 2: Start tailscaled daemon in background print("\nStarting tailscaled daemon...") sandbox.process.run("nohup sudo tailscaled > /dev/null 2>&1 &", timeout=10) # Wait for daemon to initialize time.sleep(3) # Step 3: Run tailscale up in background and capture output to a file print("\nInitiating Tailscale login...") sandbox.process.run( "sudo tailscale up > /tmp/tailscale-login.txt 2>&1 &", timeout=10 ) # Wait for the login URL to be written to the file time.sleep(3) # Read the login URL from the output file response = sandbox.process.run("cat /tmp/tailscale-login.txt", timeout=10) output = response.output url_match = re.search(r'https://login\.tailscale\.com/a/[^\s]+', output) if url_match: login_url = url_match.group(0) print(f"\n{'='*60}") print("To authenticate, visit this URL in your browser:") print(f"\n {login_url}") print(f"\n{'='*60}") print("\nWaiting for authentication...") # Poll for connection status max_wait = 300 poll_interval = 5 waited = 0 while waited < max_wait: time.sleep(poll_interval) waited += poll_interval status_response = sandbox.process.run("tailscale status 2>&1", timeout=30) status_output = status_response.output # Check if connected if status_response.exit_code == 0 and "logged out" not in status_output.lower(): # Verify IP is assigned ip_response = sandbox.process.run("tailscale ip -4 2>&1", timeout=10) if ip_response.exit_code == 0 and ip_response.output.strip(): print(f"\nConnected to Tailscale network!") print(f"Tailscale IP: {ip_response.output.strip()}") break print(f" Still waiting... ({waited}s)") else: print("\nTimeout waiting for authentication. Please try again.") return sandbox else: # Already connected or different output print(f"Output from tailscale up:\n{output}") # Check if already connected status_response = sandbox.process.run("tailscale status", timeout=30) if status_response.exit_code == 0: print("\nTailscale status:") print(status_response.output) # Final status check print("\nFinal Tailscale status:") response = sandbox.process.run("tailscale status", timeout=30) print(response.output) return sandbox if __name__ == "__main__": sandbox = setup_tailscale_vpn_interactive() ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `timeout` | float | Sets how many seconds the SDK waits for the command in `process.run`. When it elapses, `run` returns without raising, `reason` is `"timed_out"`, and `exit_code` is `None`. The timeout does not stop the command. | ```typescript import { Daytona } from '@daytona/sdk' // Configuration const DAYTONA_API_KEY = 'YOUR_API_KEY' // Replace with your API key // Initialize the Daytona client const daytona = new Daytona({ apiKey: DAYTONA_API_KEY, }) function sleep(ms: number): Promise { return new Promise(resolve => setTimeout(resolve, ms)) } async function setupTailscaleVpnInteractive(): Promise { /** * Connect a Daytona sandbox to a Tailscale network using the TypeScript SDK. * Uses interactive login via browser URL (no auth key required). */ // Create the sandbox console.log('Creating sandbox...') const sandbox = await daytona.v2.create('ubuntu-24.04') console.log(`Sandbox created: ${sandbox.id}`) // Step 1: Install Tailscale console.log('\nInstalling Tailscale (this may take a few minutes)...') let response = await sandbox.process.run('curl -fsSL https://tailscale.com/install.sh | sh', { timeoutSeconds: 300 }) if (response.exitCode !== 0) { console.log(`Error installing Tailscale: ${response.output}`) return } console.log('Tailscale installed successfully.') // Step 2: Start tailscaled daemon in background console.log('\nStarting tailscaled daemon...') await sandbox.process.run('nohup sudo tailscaled > /dev/null 2>&1 &', { timeoutSeconds: 10 }) // Wait for daemon to initialize await sleep(3000) // Step 3: Run tailscale up in background and capture output to a file console.log('\nInitiating Tailscale login...') await sandbox.process.run('sudo tailscale up > /tmp/tailscale-login.txt 2>&1 &', { timeoutSeconds: 10 }) // Wait for the login URL to be written to the file await sleep(3000) // Read the login URL from the output file response = await sandbox.process.run('cat /tmp/tailscale-login.txt', { timeoutSeconds: 10 }) const output = response.output || '' const urlMatch = output.match(/https:\/\/login\.tailscale\.com\/a\/[^\s]+/) if (urlMatch) { const loginUrl = urlMatch[0] console.log('\n' + '='.repeat(60)) console.log('To authenticate, visit this URL in your browser:') console.log(`\n ${loginUrl}`) console.log('\n' + '='.repeat(60)) console.log('\nWaiting for authentication...') // Poll for connection status const maxWait = 300 // 5 minutes max wait const pollInterval = 5 let waited = 0 while (waited < maxWait) { await sleep(pollInterval * 1000) waited += pollInterval const statusResponse = await sandbox.process.run('tailscale status 2>&1', { timeoutSeconds: 30 }) const statusOutput = statusResponse.output || '' // Check if we're connected (status shows our machine without login prompt) if ( statusResponse.exitCode === 0 && !statusOutput.toLowerCase().includes('logged out') ) { // Verify we have an IP assigned const ipResponse = await sandbox.process.run('tailscale ip -4 2>&1', { timeoutSeconds: 10 }) if (ipResponse.exitCode === 0 && ipResponse.output?.trim()) { console.log('\nConnected to Tailscale network!') console.log(`Tailscale IP: ${ipResponse.output.trim()}`) break } } console.log(` Still waiting... (${waited}s)`) } if (waited >= maxWait) { console.log('\nTimeout waiting for authentication. Please try again.') return } } else { // Maybe already connected or different output console.log(`Output from tailscale up:\n${output}`) // Check if already connected const statusResponse = await sandbox.process.run('tailscale status', { timeoutSeconds: 30 }) if (statusResponse.exitCode === 0) { console.log('\nTailscale status:') console.log(statusResponse.output) } } // Final status check console.log('\nFinal Tailscale status:') response = await sandbox.process.run('tailscale status', { timeoutSeconds: 30 }) console.log(response.output) } // Run the main function setupTailscaleVpnInteractive().catch(console.error) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `timeoutSeconds` | number | Sets how many seconds the SDK waits for the command in `process.run`. When it elapses, `run` resolves without throwing, `reason` is `'timed_out'`, and `exitCode` is undefined. The timeout does not stop the command. | Once the connection is established and authentication is complete, the sandbox will maintain its connection as long as the service is running. ### Tailscale auth key [#tailscale-auth-key] An auth key connects your Daytona sandbox to Tailscale non-interactively, which suits automated scripts, CI/CD pipelines, and any scenario without manual browser interaction. 1. Access your [Tailscale admin console ↗](https://login.tailscale.com/admin/machines) 2. Click and select 3. Apply the configuration and click This generates a script that installs Tailscale and connects to the Tailscale network. ```bash curl -fsSL https://tailscale.com/install.sh | sh && sudo tailscale up --auth-key=tskey-auth- ``` Copy the auth key from the generated script and connect your sandbox to Tailscale: ```python from daytona import Daytona, DaytonaConfig import time # Configuration DAYTONA_API_KEY = "YOUR_API_KEY" # Replace with your API key TAILSCALE_AUTH_KEY = "YOUR_AUTH_KEY" # Replace with your auth key # Initialize the Daytona client config = DaytonaConfig(api_key=DAYTONA_API_KEY) daytona = Daytona(config) def setup_tailscale_vpn(auth_key: str): """ Connect a Daytona sandbox to a Tailscale network using the Python SDK. Uses auth-key for non-interactive authentication. """ # Create the sandbox print("Creating sandbox...") sandbox = daytona.v2.create("ubuntu-24.04") print(f"Sandbox created: {sandbox.id}") # Step 1: Install Tailscale print("\nInstalling Tailscale (this may take a few minutes)...") response = sandbox.process.run( "curl -fsSL https://tailscale.com/install.sh | sh", timeout=300 ) if response.exit_code != 0: print(f"Error installing Tailscale: {response.output}") return sandbox print("Tailscale installed successfully.") # Step 2: Start tailscaled daemon manually (systemd doesn't auto-start in sandboxes) print("\nStarting tailscaled daemon...") sandbox.process.run("nohup sudo tailscaled > /dev/null 2>&1 &", timeout=10) # Wait for daemon to initialize time.sleep(3) # Step 3: Connect with auth key print("\nConnecting to Tailscale network...") response = sandbox.process.run( f"sudo tailscale up --auth-key={auth_key}", timeout=60 ) if response.exit_code != 0: print(f"Error connecting: {response.output}") return sandbox print("Connected to Tailscale network.") # Verify connection status print("\nChecking Tailscale status...") response = sandbox.process.run("tailscale status", timeout=30) print(f"Status:\n{response.output}") return sandbox if __name__ == "__main__": sandbox = setup_tailscale_vpn(TAILSCALE_AUTH_KEY) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `timeout` | float | Sets how many seconds the SDK waits for the command in `process.run`. When it elapses, `run` returns without raising, `reason` is `"timed_out"`, and `exit_code` is `None`. The timeout does not stop the command. | ```typescript import { Daytona } from '@daytona/sdk' // Configuration const DAYTONA_API_KEY = 'YOUR_API_KEY' // Replace with your API key const TAILSCALE_AUTH_KEY = 'YOUR_AUTH_KEY' // Replace with your auth key // Initialize the Daytona client const daytona = new Daytona({ apiKey: DAYTONA_API_KEY, }) function sleep(ms: number): Promise { return new Promise(resolve => setTimeout(resolve, ms)) } async function setupTailscaleVpn(authKey: string): Promise { /** * Connect a Daytona sandbox to a Tailscale network using the TypeScript SDK. * Uses auth-key for non-interactive authentication. */ // Create the sandbox console.log('Creating sandbox...') const sandbox = await daytona.v2.create('ubuntu-24.04') console.log(`Sandbox created: ${sandbox.id}`) // Step 1: Install Tailscale console.log('\nInstalling Tailscale (this may take a few minutes)...') let response = await sandbox.process.run('curl -fsSL https://tailscale.com/install.sh | sh', { timeoutSeconds: 300 }) if (response.exitCode !== 0) { console.log(`Error installing Tailscale: ${response.output}`) return } console.log('Tailscale installed successfully.') // Step 2: Start tailscaled daemon manually (systemd doesn't auto-start in sandboxes) console.log('\nStarting tailscaled daemon...') await sandbox.process.run('nohup sudo tailscaled > /dev/null 2>&1 &', { timeoutSeconds: 10 }) // Wait for daemon to initialize await sleep(3000) // Step 3: Connect with auth key console.log('\nConnecting to Tailscale network...') response = await sandbox.process.run(`sudo tailscale up --auth-key=${authKey}`, { timeoutSeconds: 60 }) if (response.exitCode !== 0) { console.log(`Error connecting: ${response.output}`) return } console.log('Connected to Tailscale network.') // Verify connection status console.log('\nChecking Tailscale status...') response = await sandbox.process.run('tailscale status', { timeoutSeconds: 30 }) console.log(`Status:\n${response.output}`) } // Run the main function setupTailscaleVpn(TAILSCALE_AUTH_KEY).catch(console.error) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `timeoutSeconds` | number | Sets how many seconds the SDK waits for the command in `process.run`. When it elapses, `run` resolves without throwing, `reason` is `'timed_out'`, and `exitCode` is undefined. The timeout does not stop the command. | Once the connection is established and authentication is complete, the sandbox will maintain its connection as long as the service is running. ### Tailscale web terminal [#tailscale-web-terminal] For working directly in the terminal or for more control over the Tailscale connection process, you can set up Tailscale manually through the Daytona [web terminal](/docs/web-terminal) or [SSH](/docs/ssh-access). This approach provides visibility into each step of the installation and connection process, and lets you customize the setup. The process involves installing Tailscale, starting the daemon in a persistent session using tmux, and then authenticating through the interactive login flow. 1. Navigate to your sandbox [web terminal](/docs/web-terminal) in [Daytona Dashboard ↗](https://app.daytona.com), or [access it via SSH](/docs/ssh-access) 2. Install Tailscale using the official installation script: ```bash curl -fsSL https://tailscale.com/install.sh | sh ``` This installs Tailscale and initializes the Tailscale CLI inside the sandbox. Daytona requires the Tailscale daemon running in the background to join the Tailscale network. Run it in a detached tmux (or similar) session so the daemon runs in the background: 3. Install tmux ```bash sudo apt install tmux ``` 4. Start the Tailscale daemon in a detached tmux session ```bash tmux new -d -s tailscale 'sudo tailscaled' ``` 5. Connect and authenticate your sandbox with the Tailscale network ```bash sudo tailscale up ``` 6. Visit the authentication URL in the web browser and follow the instructions to authenticate ```txt To authenticate, visit: https://login.tailscale.com/a/ ``` Once authenticated, you will see the following confirmation message: ```txt Your device is logged in to the

tailnet. ``` You've now successfully connected your Daytona sandbox to your Tailscale network. The sandbox should appear in your [Tailscale dashboard](https://login.tailscale.com/admin/machines). ## OpenVPN [#openvpn] Daytona provides multiple ways to connect to a Daytona sandbox with an OpenVPN network: - [OpenVPN client configuration](#openvpn-client-configuration) - [Connect with web terminal](#openvpn-web-terminal) OpenVPN uses a client-server model where your Daytona sandbox acts as a client connecting to an OpenVPN server. Use it to connect to existing corporate VPNs, access resources behind firewalls, or integrate with infrastructure that already uses OpenVPN. Connecting a Daytona sandbox to OpenVPN network requires a [client configuration file](#openvpn-client-configuration-file). ### OpenVPN client configuration file [#openvpn-client-configuration-file] Client configuration file contains the connection parameters, certificates, and keys required to establish a secure connection to your OpenVPN server. This file is typically provided by your network administrator or generated from your OpenVPN server setup. The configuration file must contain all the required connection settings, including server address, port, protocol, encryption settings, and authentication credentials. To create this file, you can use a text editor such as nano or vim, or upload it to your sandbox if you have it prepared elsewhere. The following snippet is an example of a client configuration file. Replace the placeholders with the actual values provided by your OpenVPN server. ```bash client proto udp explicit-exit-notify remote dev tun resolv-retry infinite nobind persist-key persist-tun remote-cert-tls server verify-x509-name name auth SHA256 auth-nocache cipher AES-128-GCM ignore-unknown-option data-ciphers data-ciphers AES-128-GCM ncp-ciphers AES-128-GCM tls-client tls-version-min 1.2 tls-cipher TLS-ECDHE-ECDSA-WITH-AES-128-GCM-SHA256 tls-ciphersuites TLS_AES_256_GCM_SHA384:TLS_AES_128_GCM_SHA256:TLS_CHACHA20_POLY1305_SHA256 ignore-unknown-option block-outside-dns setenv opt block-outside-dns # Prevent Windows 10 DNS leak verb 3 -----BEGIN CERTIFICATE----- -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- -----END CERTIFICATE----- -----BEGIN PRIVATE KEY----- -----END PRIVATE KEY----- -----BEGIN OpenVPN tls-crypt-v2 client key----- -----END OpenVPN tls-crypt-v2 client key----- ``` ### OpenVPN client configuration [#openvpn-client-configuration] The following snippets connect to OpenVPN with a client configuration file. ```python from daytona import Daytona, DaytonaConfig import time # Configuration DAYTONA_API_KEY = "YOUR_API_KEY" # Replace with your API key # OpenVPN client configuration (paste your .ovpn config here) OPENVPN_CONFIG = """ """.strip() # Initialize the Daytona client config = DaytonaConfig(api_key=DAYTONA_API_KEY) daytona = Daytona(config) def setup_openvpn(ovpn_config: str): """ Connect a Daytona sandbox to an OpenVPN network using the Python SDK. """ # Create the sandbox print("Creating sandbox...") sandbox = daytona.v2.create("ubuntu-24.04") print(f"Sandbox created: {sandbox.id}") # Step 1: Install OpenVPN print("\nInstalling OpenVPN...") response = sandbox.process.run( "sudo apt update && sudo apt install -y openvpn", timeout=120 ) if response.exit_code != 0: print(f"Error installing OpenVPN: {response.output}") return sandbox print("OpenVPN installed successfully.") # Step 2: Write the OpenVPN config file print("\nWriting OpenVPN configuration...") sandbox.fs.write_text("/home/daytona/client.ovpn", ovpn_config) print("Configuration written to /home/daytona/client.ovpn") # Step 3: Start OpenVPN in background print("\nStarting OpenVPN tunnel...") sandbox.process.run( "nohup sudo openvpn /home/daytona/client.ovpn > /tmp/openvpn.log 2>&1 &", timeout=10 ) # Wait for connection to establish print("Waiting for VPN connection to establish...") time.sleep(10) # Step 4: Verify connection print("\nVerifying OpenVPN connection...") # Check if tun interface exists response = sandbox.process.run("ip addr show tun0", timeout=10) if response.exit_code == 0: print("VPN tunnel interface (tun0) is up:") print(response.output) else: print("Warning: tun0 interface not found. Checking OpenVPN logs...") log_response = sandbox.process.run("cat /tmp/openvpn.log", timeout=10) print(f"OpenVPN log:\n{log_response.output}") return sandbox # Get public IP through VPN print("\nChecking public IP (should be VPN server IP)...") response = sandbox.process.run("curl -s ifconfig.me", timeout=30) if response.exit_code == 0: print(f"Public IP: {response.output}") else: print(f"Could not determine public IP: {response.output}") print("\nOpenVPN connection established successfully.") return sandbox if __name__ == "__main__": sandbox = setup_openvpn(OPENVPN_CONFIG) ``` ```typescript import { Daytona } from '@daytona/sdk'; import { Image } from '@daytona/sdk/v2'; // Configuration const DAYTONA_API_KEY = "YOUR_API_KEY"; // Replace with your API key // OpenVPN client configuration (paste your .ovpn config here) const OPENVPN_CONFIG = ` `.trim(); // Initialize the Daytona client const daytona = new Daytona({ apiKey: DAYTONA_API_KEY, }); function sleep(ms: number): Promise { return new Promise(resolve => setTimeout(resolve, ms)); } async function setupOpenvpn(ovpnConfig: string): Promise { /** * Connect a Daytona sandbox to an OpenVPN network using the TypeScript SDK. */ // Create the sandbox console.log("Creating sandbox..."); const sandbox = await daytona.v2.create('ubuntu-24.04'); console.log(`Sandbox created: ${sandbox.id}`); // Step 1: Install OpenVPN console.log("\nInstalling OpenVPN..."); let response = await sandbox.process.run("sudo apt update && sudo apt install -y openvpn", { timeoutSeconds: 120 }); if (response.exitCode !== 0) { console.log(`Error installing OpenVPN: ${response.output}`); return; } console.log("OpenVPN installed successfully."); // Step 2: Write the OpenVPN config file console.log("\nWriting OpenVPN configuration..."); // Use heredoc to write the config file await sandbox.process.run(`cat << 'OVPNEOF' > /home/daytona/client.ovpn ${ovpnConfig} OVPNEOF`, { timeoutSeconds: 30 }); console.log("Configuration written to /home/daytona/client.ovpn"); // Step 3: Start OpenVPN in background console.log("\nStarting OpenVPN tunnel..."); await sandbox.process.run("nohup sudo openvpn /home/daytona/client.ovpn > /tmp/openvpn.log 2>&1 &", { timeoutSeconds: 10 }); // Wait for connection to establish console.log("Waiting for VPN connection to establish..."); await sleep(10000); // Step 4: Verify connection console.log("\nVerifying OpenVPN connection..."); // Check if tun interface exists response = await sandbox.process.run("ip addr show tun0", { timeoutSeconds: 10 }); if (response.exitCode === 0) { console.log("VPN tunnel interface (tun0) is up:"); console.log(response.output); } else { console.log("Warning: tun0 interface not found. Checking OpenVPN logs..."); const logResponse = await sandbox.process.run("cat /tmp/openvpn.log", { timeoutSeconds: 10 }); console.log(`OpenVPN log:\n${logResponse.output}`); return; } // Get public IP through VPN console.log("\nChecking public IP (should be VPN server IP)..."); response = await sandbox.process.run("curl -s ifconfig.me", { timeoutSeconds: 30 }); if (response.exitCode === 0) { console.log(`Public IP: ${response.output}`); } else { console.log(`Could not determine public IP: ${response.output}`); } console.log("\nOpenVPN connection established successfully."); } // Run the main function setupOpenvpn(OPENVPN_CONFIG).catch(console.error); ``` ### OpenVPN web terminal [#openvpn-web-terminal] Daytona provides a [web terminal](/docs/web-terminal) for interacting with your sandboxes, allowing you to install OpenVPN and connect to your OpenVPN network. 1. In [Daytona Dashboard ↗](https://app.daytona.com), open the sandbox [web terminal](/docs/web-terminal) (`>_`), or use [SSH](/docs/ssh-access) 2. Install OpenVPN and tmux ```bash sudo apt update && sudo apt install -y openvpn tmux ``` 3. Create the OpenVPN [client configuration file](#openvpn-client-configuration-file) for your Daytona sandbox ```bash sudo nano client.ovpn ``` 4. Save the file by pressing `Ctrl+O`, then `Enter`, and exit by pressing `Ctrl+X` The OpenVPN tunnel must run in the background to connect the sandbox to the OpenVPN network. Run it in a detached tmux (or similar) session: 5. Start OpenVPN tunnel in a background tmux session ```bash tmux new -d -s openvpn 'sudo openvpn client.ovpn' ``` This starts the OpenVPN tunnel in a background tmux session that survives disconnects. 6. Verify the OpenVPN connection by running the following command ```bash curl ifconfig.me ``` This will return the IP address of the sandbox connected to the OpenVPN network. You've now successfully connected your Daytona sandbox to your OpenVPN network. ## Netbird [#netbird] Daytona provides multiple ways to connect to a Daytona sandbox with a Netbird network: - [Connect with setup key](#netbird-setup-key) - [Connect with browser login](#netbird-browser-login) When you connect a Daytona sandbox to a Netbird network, the sandbox becomes part of your private Netbird network, allowing you to access resources that are available within the network and enabling other devices on the network to access the sandbox. This integration makes your sandbox appear as a device within your Netbird network, with its own Netbird IP address and access to other devices and services on the network. ### Netbird setup key [#netbird-setup-key] A Netbird setup key connects your Daytona sandbox to Netbird non-interactively, which suits automated scripts, CI/CD pipelines, and any scenario without manual browser interaction. 1. Access your [Netbird dashboard ↗](https://app.netbird.io/) 2. Click 3. Create a new setup key or use an existing one The following snippets connect to Netbird with a setup key. ```python from daytona import Daytona, DaytonaConfig # Configuration DAYTONA_API_KEY = "YOUR_API_KEY" NETBIRD_SETUP_KEY = "YOUR_SETUP_KEY" # Initialize the Daytona client config = DaytonaConfig(api_key=DAYTONA_API_KEY) daytona = Daytona(config) def setup_netbird(): """ Connect a Daytona sandbox to a NetBird network using the Python SDK. Uses the official NetBird install script and a Setup Key for non-interactive auth. See: https://docs.netbird.io/manage/peers/access-infrastructure/setup-keys-add-servers-to-network """ if NETBIRD_SETUP_KEY == "YOUR_SETUP_KEY": print("Error: please set NETBIRD_SETUP_KEY to a valid setup key.") return None # Create the sandbox print("Creating sandbox...") sandbox = daytona.v2.create("ubuntu-24.04") print(f"Sandbox created: {sandbox.id}") print("\nInstalling NetBird via the official install script...") install_cmd = ( "sudo rm -f /etc/apt/sources.list.d/yarn.list && " "curl -fsSL https://pkgs.netbird.io/install.sh | sudo sh" ) response = sandbox.process.run(install_cmd, timeout=300) if response.exit_code != 0: print(f"Error installing NetBird: {response.output}") return sandbox print("NetBird installed successfully.") # Connect to the NetBird network using the setup key print("\nConnecting to NetBird network with setup key...") up_cmd = f"sudo netbird up --setup-key {NETBIRD_SETUP_KEY}" response = sandbox.process.run(up_cmd, timeout=120) if response.exit_code != 0: print(f"Error running 'netbird up': {response.output}") return sandbox print(response.output) # Final status check print("\nFinal NetBird status:") response = sandbox.process.run("netbird status", timeout=30) print(response.output) return sandbox if __name__ == "__main__": sandbox = setup_netbird() ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `timeout` | float | Sets how many seconds the SDK waits for the command in `process.run`. When it elapses, `run` returns without raising, `reason` is `"timed_out"`, and `exit_code` is `None`. The timeout does not stop the command. | ```typescript import { Daytona } from '@daytona/sdk'; import { Image } from '@daytona/sdk/v2'; // Configuration const DAYTONA_API_KEY = "YOUR_API_KEY"; const NETBIRD_SETUP_KEY = "YOUR_SETUP_KEY"; // Initialize the Daytona client const daytona = new Daytona({ apiKey: DAYTONA_API_KEY, }); async function setupNetbird(): Promise { /** * Connect a Daytona sandbox to a NetBird network using the TypeScript SDK. * Uses the official NetBird install script and a Setup Key for non-interactive auth. * See: https://docs.netbird.io/manage/peers/access-infrastructure/setup-keys-add-servers-to-network */ // Create the sandbox console.log("Creating sandbox..."); const sandbox = await daytona.v2.create('ubuntu-24.04'); console.log(`Sandbox created: ${sandbox.id}`); // Install NetBird via the official install script console.log("\nInstalling NetBird via the official install script..."); const installCmd = [ "sudo rm -f /etc/apt/sources.list.d/yarn.list", "curl -fsSL https://pkgs.netbird.io/install.sh | sudo sh", ].join(" && "); let response = await sandbox.process.run(installCmd, { timeoutSeconds: 300 }); if (response.exitCode !== 0) { console.log(`Error installing NetBird: ${response.output}`); return; } console.log("NetBird installed successfully."); // Connect to the NetBird network using the setup key console.log("\nConnecting to NetBird network with setup key..."); const upCmd = `sudo netbird up --setup-key ${NETBIRD_SETUP_KEY}`; response = await sandbox.process.run(upCmd, { timeoutSeconds: 120 }); if (response.exitCode !== 0) { console.log(`Error running 'netbird up': ${response.output}`); return; } console.log(response.output); // Final status check console.log("\nFinal NetBird status:"); response = await sandbox.process.run("netbird status", { timeoutSeconds: 30 }); console.log(response.output); } // Run the main function setupNetbird().catch(console.error); ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `timeoutSeconds` | number | Sets how many seconds the SDK waits for the command in `process.run`. When it elapses, `run` resolves without throwing, `reason` is `'timed_out'`, and `exitCode` is undefined. The timeout does not stop the command. | ### Netbird browser login [#netbird-browser-login] The browser login method initiates an interactive authentication flow where Netbird generates a unique login URL that you visit in your web browser to authenticate the Daytona sandbox. The following snippets connect to Netbird with a browser login. ```python from daytona import Daytona, DaytonaConfig import time import re # Configuration DAYTONA_API_KEY = "YOUR_API_KEY" # Initialize the Daytona client config = DaytonaConfig(api_key=DAYTONA_API_KEY) daytona = Daytona(config) def setup_netbird(): """ Connect a Daytona sandbox to a NetBird network using the Python SDK. Uses the official NetBird install script and interactive browser login. """ # Create the sandbox print("Creating sandbox...") sandbox = daytona.v2.create("ubuntu-24.04") print(f"Sandbox created: {sandbox.id}") # Install NetBird via the official install script print("\nInstalling NetBird via the official install script...") install_cmd = ( "sudo rm -f /etc/apt/sources.list.d/yarn.list && " "curl -fsSL https://pkgs.netbird.io/install.sh | sudo sh" ) response = sandbox.process.run(install_cmd, timeout=300) if response.exit_code != 0: print(f"Error installing NetBird: {response.output}") return sandbox print("NetBird installed successfully.") # Run netbird up in background and capture output to a file print("\nInitiating NetBird login...") sandbox.process.run( "netbird up > /tmp/netbird-login.txt 2>&1 &", timeout=10 ) # Wait for the login URL to be written to the file time.sleep(5) # Read the login URL from the output file response = sandbox.process.run("cat /tmp/netbird-login.txt", timeout=10) output = response.output url_match = re.search(r'https?://[^\s]+', output) if url_match: login_url = url_match.group(0) print(f"\n{'='*60}") print("To authenticate, visit this URL in your browser:") print(f"\n {login_url}") print(f"\n{'='*60}") print("\nWaiting for authentication...") # Poll for connection status max_wait = 300 # 5 minutes max wait poll_interval = 5 waited = 0 while waited < max_wait: time.sleep(poll_interval) waited += poll_interval status_response = sandbox.process.run("netbird status 2>&1", timeout=30) status_output = status_response.output # Check if we're connected if status_response.exit_code == 0 and "connected" in status_output.lower(): print(f"\nConnected to NetBird network!") print(f"NetBird status:\n{status_output}") break print(f" Still waiting... ({waited}s)") else: print("\nTimeout waiting for authentication. Please try again.") return sandbox else: # Maybe already connected or different output print(f"Output from netbird up:\n{output}") # Check if already connected status_response = sandbox.process.run("netbird status", timeout=30) if status_response.exit_code == 0: print("\nNetBird status:") print(status_response.output) # Final status check print("\nFinal NetBird status:") response = sandbox.process.run("netbird status", timeout=30) print(response.output) return sandbox if __name__ == "__main__": sandbox = setup_netbird() ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `timeout` | float | Sets how many seconds the SDK waits for the command in `process.run`. When it elapses, `run` returns without raising, `reason` is `"timed_out"`, and `exit_code` is `None`. The timeout does not stop the command. | ```typescript import { Daytona } from '@daytona/sdk'; import { Image } from '@daytona/sdk/v2'; // Configuration const DAYTONA_API_KEY = "YOUR_API_KEY"; // Initialize the Daytona client const daytona = new Daytona({ apiKey: DAYTONA_API_KEY, }); function sleep(ms: number): Promise { return new Promise(resolve => setTimeout(resolve, ms)); } async function setupNetbirdVpnInteractive(): Promise { /** * Connect a Daytona sandbox to a NetBird network using the TypeScript SDK. * Uses the official NetBird install script and interactive browser login. */ // Create the sandbox console.log("Creating sandbox..."); const sandbox = await daytona.v2.create('ubuntu-24.04'); console.log(`Sandbox created: ${sandbox.id}`); // Remove the broken Yarn list so apt-get update inside the installer succeeds, // then run the official NetBird install script. The script adds the NetBird // APT repo, imports the signing key, installs the package, and registers the // systemd service. console.log("\nInstalling NetBird via the official install script..."); const installCmd = [ "sudo rm -f /etc/apt/sources.list.d/yarn.list", "curl -fsSL https://pkgs.netbird.io/install.sh | sudo sh", ].join(" && "); let response = await sandbox.process.run(installCmd, { timeoutSeconds: 300 }); if (response.exitCode !== 0) { console.log(`Error installing NetBird: ${response.output}`); return; } console.log("NetBird installed successfully."); // Run netbird up in background and capture output to a file console.log("\nInitiating NetBird login..."); await sandbox.process.run("netbird up > /tmp/netbird-login.txt 2>&1 &", { timeoutSeconds: 10 }); // Wait for the login URL to be written to the file await sleep(5000); // Read the login URL from the output file response = await sandbox.process.run("cat /tmp/netbird-login.txt", { timeoutSeconds: 10 }); const output = response.output || ""; const urlMatch = output.match(/https?:\/\/[^\s]+/); if (urlMatch) { const loginUrl = urlMatch[0]; console.log("\n" + "=".repeat(60)); console.log("To authenticate, visit this URL in your browser:"); console.log(`\n ${loginUrl}`); console.log("\n" + "=".repeat(60)); console.log("\nWaiting for authentication..."); // Poll for connection status const maxWait = 300; // 5 minutes max wait const pollInterval = 5; let waited = 0; while (waited < maxWait) { await sleep(pollInterval * 1000); waited += pollInterval; const statusResponse = await sandbox.process.run("netbird status 2>&1", { timeoutSeconds: 30 }); const statusOutput = statusResponse.output || ""; // Check if we're connected if (statusResponse.exitCode === 0 && statusOutput.toLowerCase().includes("connected")) { console.log("\nConnected to NetBird network!"); console.log(`NetBird status:\n${statusOutput}`); break; } console.log(` Still waiting... (${waited}s)`); } if (waited >= maxWait) { console.log("\nTimeout waiting for authentication. Please try again."); return; } } else { // Maybe already connected or different output console.log(`Output from netbird up:\n${output}`); // Check if already connected const statusResponse = await sandbox.process.run("netbird status", { timeoutSeconds: 30 }); if (statusResponse.exitCode === 0) { console.log("\nNetBird status:"); console.log(statusResponse.output); } } // Final status check console.log("\nFinal NetBird status:"); response = await sandbox.process.run("netbird status", { timeoutSeconds: 30 }); console.log(response.output); } // Run the main function setupNetbirdVpnInteractive().catch(console.error); ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `timeoutSeconds` | number | Sets how many seconds the SDK waits for the command in `process.run`. When it elapses, `run` resolves without throwing, `reason` is `'timed_out'`, and `exitCode` is undefined. The timeout does not stop the command. | # Preview URLs (/docs/preview) Daytona provides preview URLs for accessing services running in your sandboxes. Any process listening for HTTP traffic on ports 1 to 65535 can be previewed through a generated URL. Daytona supports two types of preview URLs, each with a different authentication mechanism: - [Standard preview URL](#standard-preview-url) contains the sandbox ID and requires a separate authentication token - [Signed preview URL](#signed-preview-url) embeds the authentication token directly in the URL, requiring no headers ## Use cases [#use-cases] Preview URLs are used when a service in a sandbox must be reachable over HTTP from outside the sandbox. - **Web application previews.** A web server that an agent or a developer starts in the sandbox opens in a browser. Members of the organization sign in through the browser to reach a private port. Any process that listens for HTTP traffic on a port from 1 to 65535 can be previewed once its port is exposed. - **Links for people without an account.** A signed preview URL carries its token, so anyone with the link reaches the service without headers. Each link is valid for one port, expires at a set time, and can be revoked on its own. The expiry ranges from 1 second to 7 days, with a default of 60 seconds. - **API and webhook tests.** An HTTP API in the sandbox receives requests from external clients and services. A public port accepts requests from services that cannot send a credential. Clients that control their HTTP headers use the [standard preview URL](#standard-preview-url) and send the token in a header. - **Real-time applications.** WebSocket connections and streaming responses pass through preview URLs. Authenticated streams count as activity and reset the idle timeout. A browser WebSocket client cannot set headers, so it passes an API key as the daytona_token query parameter. - **Custom domains.** A proxy you run in front of preview URLs serves them on your own domain, with your own authentication and error pages. The proxy forwards each request to the [standard preview URL](#standard-preview-url) with a credential, even for public ports, so the traffic counts as activity. Daytona strips the credential headers before the request reaches the sandbox. ## Authentication [#authentication] Visibility is set per port. A port is exposed as a **private** preview endpoint when you first request its preview URL. Private endpoints require authentication; public ones do not. Make a port public when exposing it, or change the visibility of an already exposed port: ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() # Expose a port publicly endpoint = sandbox.ports.expose(3000, public=True) print(endpoint.url) # Change visibility of an already exposed port sandbox.ports.expose(3000, public=False) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------------------------------------------------------------- | | `public` | bool | Makes the endpoint public. On a port that is already exposed, it changes the visibility. The default is `False`, so `expose(3000)` creates a private endpoint. | ```typescript import { Daytona } from '@daytona/sdk'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); // Expose a port publicly const endpoint = await sandbox.ports.expose(3000, { public: true }); console.log(endpoint.url); // Change visibility of an already exposed port await sandbox.ports.expose(3000, { public: false }); ``` | **Parameter** | **Type** | **Description** | | ------------- | --------- | --------------------------------------------------------------------- | | `public` | boolean | Makes the endpoint public. On a port that is already exposed, it changes the visibility. The default is `false`, so `expose(3000)` creates a private endpoint. | ```bash # Expose a port publicly curl 'https://api.daytona.com/sandboxes/{sandboxId}/ports/3000' \ --request PUT \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \ --data '{ "public": true }' # Change visibility of an already exposed port curl 'https://api.daytona.com/sandboxes/{sandboxId}/ports/3000' \ --request PUT \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \ --data '{ "public": false }' ``` | **Field** | **Type** | **Description** | | --------- | --------- | ------------------ | | `public` | boolean | Makes the endpoint public. This field is required. | Each exposed port is returned with its port, visibility, URL, and creation time. Exposing a port that is already exposed returns the existing endpoint, with its visibility updated if it differs from the requested one. ### List exposed ports [#list-exposed-ports] List the preview endpoints of a sandbox, ordered by port number. The list returns one page at a time, and each page holds the cursor of the next one. Each endpoint has its port, visibility, URL, and creation time. A port with a listener but no endpoint is not listed; see [listening ports](#listening-ports). ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.ports.expose(3000) cursor = None while True: page = sandbox.ports.list_endpoints(limit=50, cursor=cursor) for endpoint in page.items: print(endpoint.port, endpoint.public, endpoint.url, endpoint.created_at) cursor = page.next_cursor # None on the last page if cursor is None: break # Or iterate over every endpoint without handling page cursors for endpoint in sandbox.ports.iter_endpoints(): print(endpoint.port, endpoint.public, endpoint.url) ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------- | | `limit` | int | Sets the page size, from `1` to `200`. A value outside the range raises `BadRequestError` before any request is sent. The default is `100`. | | `cursor` | str | Resumes the list after the previous page. Pass the `next_cursor` of that page. Omit it for the first page. | ```typescript import { Daytona } from '@daytona/sdk'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); await sandbox.ports.expose(3000); let cursor: string | undefined; do { const page = await sandbox.ports.listEndpoints({ limit: 50, cursor }); for (const endpoint of page.items) { console.log(endpoint.port, endpoint.public, endpoint.url, endpoint.createdAt); } cursor = page.nextCursor; // undefined on the last page } while (cursor); // Or iterate over every endpoint without handling page cursors for await (const endpoint of sandbox.ports.iterEndpoints()) { console.log(endpoint.port, endpoint.public, endpoint.url); } ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------- | | `limit` | number | Sets the page size, from `1` to `200`. A value outside the range throws `BadRequestError` before any request is sent. The default is `100`. | | `cursor` | string | Resumes the list after the previous page. Pass the `nextCursor` of that page. Omit it for the first page. | ```bash # List exposed ports curl 'https://api.daytona.com/sandboxes/{sandboxId}/ports?limit=50' \ --header 'Authorization: Bearer ' # Get one exposed port curl 'https://api.daytona.com/sandboxes/{sandboxId}/ports/3000' \ --header 'Authorization: Bearer ' ``` | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------- | | `limit` | integer | Sets the page size, from `1` to `200`. A value outside the range is set to the nearest bound. The default is `100`. | | `cursor` | string | Resumes the list after the previous page. Pass the `next_cursor` of that page. Omit it for the first page. | The list response has the following fields: | **Field** | **Description** | | --------- | --------------- | | `ports` | Lists the endpoints of the page, ordered by port number. | | `next_cursor` | The cursor of the next page, or `null` on the last page. | ### Unexpose a port [#unexpose-a-port] Stop exposing a port to remove its preview endpoint. The port's preview URL stops serving, and every [signed preview URL](#signed-preview-url) minted for that port stops resolving. The [standard preview token](#standard-preview-url) is not affected and keeps working for the sandbox's other private endpoints. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() sandbox.ports.expose(3000) sandbox.ports.unexpose(3000) ``` ```typescript import { Daytona } from '@daytona/sdk'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); await sandbox.ports.expose(3000); await sandbox.ports.unexpose(3000); ``` ```bash curl 'https://api.daytona.com/sandboxes/{sandboxId}/ports/3000' \ --request DELETE \ --header 'Authorization: Bearer ' ``` ### Listening ports [#listening-ports] List the ports that have a listener inside the sandbox, or check whether one port has a listener. This inspects the sandbox's network listeners and is separate from preview endpoints: a listening port is not reachable through a preview URL until it has an endpoint. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() # Every TCP port with a listener inside the sandbox ports = sandbox.ports.list() print(ports.items) # Check one port (3000 to 9999) if sandbox.ports.is_in_use(3000): link = sandbox.ports.preview_link(3000) ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() // Every TCP port with a listener inside the sandbox const ports = await sandbox.ports.list() console.log(ports.items) // Check one port (3000 to 9999) if (await sandbox.ports.isInUse(3000)) { const link = await sandbox.ports.previewLink(3000) } ``` ```bash # Every TCP port with a listener inside the sandbox daytona sandbox port list {sandboxId} ``` ```bash # Every TCP port with a listener inside the sandbox curl '{toolboxProxyUrl}/{sandboxId}/port' \ --header 'Authorization: Bearer ' # Check one port (3000 to 9999) curl '{toolboxProxyUrl}/{sandboxId}/port/3000/in-use' \ --header 'Authorization: Bearer ' ``` - The request requires the `write:sandboxes` permission. - `{toolboxProxyUrl}` is the `toolbox_proxy_url` field of the [sandbox](/docs/sandboxes#get-a-sandbox). ## Standard preview URL [#standard-preview-url] Standard preview URLs contain the sandbox ID; the authentication token is separate. The sandbox ID is the sandbox UUID and the proxy domain is the preview domain of the sandbox's [region](/docs/regions). Sandboxes in a [custom region](/docs/regions#custom-regions) get URLs under that region's preview domain. The token returned by the preview URL API is bound to the sandbox and grants access to every private preview endpoint on it. It does not expire and stays the same across sandbox restarts. With an API key, the SDKs return a sandbox access token scoped to the requested port instead, valid for 1 hour by default. Use standard preview URLs for programmatic access and API integrations where you control the HTTP headers. Requesting a preview link for a port that is not yet exposed exposes it as a private endpoint. For a public endpoint, the returned token is an empty string because no credential is needed. ```python import requests from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() preview_info = sandbox.ports.preview_link(3000) print(f"URL: {preview_info.url}") print(f"Token: {preview_info.token}") # Use with requests response = requests.get( preview_info.url, headers={"x-daytona-preview-token": preview_info.token} ) ``` - The request requires the `write:sandboxes` permission. - The port-scoped access token expires after 1 hour by default; call `preview_link` again to get a new one. - The port-scoped access token is also accepted as an `Authorization` bearer token or as the `daytona_token` query parameter. ```typescript import { Daytona } from '@daytona/sdk'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); const previewInfo = await sandbox.ports.previewLink(3000); console.log(`URL: ${previewInfo.url}`); console.log(`Token: ${previewInfo.token}`); // Use with fetch const response = await fetch(previewInfo.url, { headers: { 'x-daytona-preview-token': previewInfo.token } }); ``` - The request requires the `write:sandboxes` permission. - The port-scoped access token expires after 1 hour by default; call `previewLink` again to get a new one. - The port-scoped access token is also accepted as an `Authorization` bearer token or as the `daytona_token` query parameter. ```bash daytona sandbox port preview-url {sandboxId} 3000 ``` ```bash curl 'https://api.daytona.com/sandboxes/{sandboxId}/ports/3000/preview-url' \ --request POST \ --header 'Authorization: Bearer ' ``` ### Authentication [#authentication-1] Authenticate by sending the token in the x-daytona-preview-token header: ```bash curl -H "x-daytona-preview-token: 2fa41c900320a20409fd42dbc5629d38" \ https://3000-a78d7657-ad90-4ad6-ac7d-d415a0dc98cc.proxy.daytona.works ``` Private preview endpoints also accept a Daytona API key with the sandbox write permission as a bearer token in the Authorization header. Clients that cannot set headers, such as browser WebSocket connections, can pass the API key as a daytona_token query parameter instead: ```bash curl "https://3000-a78d7657-ad90-4ad6-ac7d-d415a0dc98cc.proxy.daytona.works/?daytona_token=" ``` The x-daytona-preview-token header is accepted only as a header, not as a query parameter. All three credentials (the Authorization header, the x-daytona-preview-token header, and the daytona_token query parameter) are stripped before the request reaches your application. Requests without a valid credential get 401, but browsers are redirected to sign in. ### Browser sign-in [#browser-sign-in] When a private preview URL is opened in a browser without a credential, Daytona redirects the navigation to sign in. A user is authorized when they are a member of the organization that owns the sandbox and hold the sandbox read permission on the sandbox's project. Only top-level navigations (GET or HEAD requests with a navigate fetch mode, or an Accept header containing text/html) trigger the redirect; API calls, fetch requests, and SDKs always receive 401. The session is stored in a cookie scoped to that preview hostname and bound to the sandbox and port, so it does not carry over to other ports or sandboxes. Membership and permissions are re-checked each time the session token is refreshed, so removing a member revokes access within one session token lifetime, 15 minutes by default. Two paths are reserved on every preview hostname and are never forwarded to your application: - `/.daytona-auth/accept` completes the sign-in - `/.daytona-auth/logout` ends the session for that hostname Session cookies are stripped before the request reaches your application. ## Signed preview URL [#signed-preview-url] The signed preview URL embeds the authentication token directly in the URL, eliminating the need for separate headers. Each call mints a new token that is valid for a single port and can be revoked individually before it expires. Set a custom expiry time for the token. The token replaces the sandbox ID in the hostname, so the link does not reveal the sandbox ID. Tokens are 33 characters: the letter s followed by 32 lowercase hexadecimal characters. Standard and signed preview tokens are not interchangeable: the standard preview token is sent in the x-daytona-preview-token header, and the signed preview token is embedded in the URL itself. Use signed preview URLs when sharing links with users who cannot set custom headers, embedding previews in iframes or emails, or creating time-limited shareable links. ```python import requests from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() # Create a signed preview URL that expires in 3600 seconds (1 hour) signed_link = sandbox.ports.signed_preview_link(3000, expires_in_seconds=3600) print(f"URL: {signed_link.url}") # Token is embedded in the URL print(f"Token: {signed_link.token}") # Can be used to revoke access print(f"Expires at: {signed_link.expires_at}") # Use directly - no headers needed response = requests.get(signed_link.url) # Revoke the token before expiry if needed sandbox.ports.expire_signed_preview_link(3000, signed_link.token) ``` | **Parameter** | **Type** | **Description** | | -------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `expires_in_seconds` | int | Seconds, from `1` to `604800` (7 days). Must be a positive integer; other values raise `BadRequestError` before any request is sent. When omitted, the server applies 60 seconds. Set it explicitly: the 60-second default is short for security reasons, and most use cases need at least 3600 (1 hour). | The response has the following fields: | **Field** | **Description** | | ------------ | ------------------------------------------------------------------------------------------------------------------ | | `url` | The signed preview URL, in the form `https://{port}-{token}.{daytonaProxyDomain}`. | | `token` | The token of the signed link. The token is returned only once, at mint time. Store the token if you need to revoke the link later. | | `expires_at` | The expiry time of the token. | ```typescript import { Daytona } from '@daytona/sdk'; const daytona = new Daytona(); const sandbox = await daytona.v2.create(); // Create a signed preview URL that expires in 3600 seconds (1 hour) const signedLink = await sandbox.ports.signedPreviewLink(3000, { expiresInSeconds: 3600 }); console.log(`URL: ${signedLink.url}`); // Token is embedded in the URL console.log(`Token: ${signedLink.token}`); // Can be used to revoke access console.log(`Expires at: ${signedLink.expiresAt}`); // Use directly - no headers needed const response = await fetch(signedLink.url); // Revoke the token before expiry if needed await sandbox.ports.expireSignedPreviewLink(3000, signedLink.token); ``` | **Parameter** | **Type** | **Description** | | ------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `expiresInSeconds` | number | Seconds, from `1` to `604800` (7 days). Must be a positive integer; other values throw `BadRequestError` before any request is sent. When omitted, the server applies 60 seconds. Set it explicitly: the 60-second default is short for security reasons, and most use cases need at least 3600 (1 hour). | The response has the following fields: | **Field** | **Description** | | ----------- | ------------------------------------------------------------------------------------------------------------------ | | `url` | The signed preview URL, in the form `https://{port}-{token}.{daytonaProxyDomain}`. | | `token` | The token of the signed link. The token is returned only once, at mint time. Store the token if you need to revoke the link later. | | `expiresAt` | The expiry time of the token. | ```bash # Create a signed preview URL that expires in 1 hour daytona sandbox port preview-url {sandboxId} 3000 --signed --ttl 1h # Revoke the token before expiry if needed daytona sandbox port preview-url expire {sandboxId} 3000 {token} ``` | **Flag** | **Type** | **Description** | | -------- | -------- | -------------------------------------------------------------------- | | `--ttl` | duration | Sets the lifetime of the signed URL as a Go duration such as `1h`, from `1s` to `168h`, which is 7 days. The default is `60s`. Set it explicitly: the 60-second default is short for security reasons, and most use cases need at least `1h`. This flag works only together with `--signed`. | - The requests require the `write:sandboxes` permission. - Store the printed token to revoke the link later; the CLI does not show it again. ```bash # Create a signed preview URL that expires in 3600 seconds (1 hour) curl 'https://api.daytona.com/sandboxes/{sandboxId}/ports/3000/signed-preview-urls' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \ --data '{ "expires_in_seconds": 3600 }' # Revoke the token before expiry if needed curl 'https://api.daytona.com/sandboxes/{sandboxId}/ports/3000/signed-preview-urls/revoke' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \ --data '{ "token": "{token}" }' ``` | **Field** | **Type** | **Description** | | -------------------- | --------- | ----------------------------------------------------------------------- | | `expires_in_seconds` | integer | Sets the lifetime of the signed URL in seconds, from `1` to `604800`. Other values return `400`. The default is `60`. Set it explicitly: the 60-second default is short for security reasons, and most use cases need at least 3600 (1 hour). | The response has the following fields: | **Field** | **Description** | | ------------ | ------------------------------------------------------------------------------------------------------ | | `url` | The signed preview URL, in the form `https://{port}-{token}.{daytonaProxyDomain}`. | | `token` | The token of the signed link. The token is returned only once. Daytona stores only the hash of the token. | | `expires_at` | The expiry time of the token. | ### Authentication [#authentication-2] The token is embedded in the URL itself, so no additional headers are required: ```bash curl https://3000-.proxy.daytona.works ``` The token is the whole credential and is re-validated on every request: - The token is bound to its port; another port in the hostname returns 404. - A signed link never creates a browser session and never redirects to sign in. An invalid, expired, or revoked token returns 404 for browsers and SDKs alike. - The port must remain exposed. [Unexposing the port](#unexpose-a-port) invalidates every signed link minted for it. - Revocation takes effect on all proxies within about one second. Minting a signed link for a port that is not yet exposed exposes it as a private endpoint. Minting never changes the visibility of a port that is already exposed. ## Sandbox activity [#sandbox-activity] Only **authenticated** preview requests count as sandbox activity. A request is authenticated when it carries a valid Authorization header, x-daytona-preview-token header, daytona_token query parameter, browser sign-in session, or when it uses a signed preview URL. - Authenticated requests and streams, including WebSockets, reset the [idle timeout](/docs/linux-sandboxes#idle-timeout) - Anonymous requests to public preview endpoints never reset the sandbox's idle timer Any request to a sandbox that is not running receives 409. ## Response codes [#response-codes] | **Status** | **Body** | **Cause** | | ---------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `302` | | Private endpoint without a credential; browser navigation redirected to sign in | | `401` | `unauthorized` | Private endpoint without a valid credential (non-browser request) | | `404` | `not found` | Hostname does not match the `{port}-{sandboxId}` or `{port}-{token}` shape, or the signed token is invalid, expired, revoked, or minted for a different port | | `404` | `unknown preview endpoint` | The port is not exposed on this sandbox | | `404` | `unknown sandbox` | The port is exposed but the sandbox cannot be routed from this preview domain, for example because it runs in another region | | `409` | `sandbox not running` | The sandbox is not running | | `409` | `sandbox failed to start` | The sandbox's last start failed | ## Using your own proxy [#using-your-own-proxy] Place your own proxy in front of preview URLs to serve previews on a custom domain (e.g., preview.yourcompany.com), add your own authentication, or show branded error pages. Your proxy resolves the sandbox and port from the incoming request and forwards it to the [standard preview URL](#standard-preview-url) of that sandbox and port, attaching one of the following credentials for private endpoints: ``` X-Daytona-Preview-Token: {sandboxToken} ``` or ``` Authorization: Bearer {apiKey} ``` Both headers are stripped before the request reaches the sandbox. The request path and query string are forwarded unchanged (apart from the daytona_token parameter, which is removed), and WebSocket upgrades and streaming responses are proxied automatically. Only authenticated requests keep sandboxes running. For proxy traffic to count as activity, attach a credential even for public endpoints. ## Permissions [#permissions] Previews use the sandbox permissions of the project, which you can grant to an [organization role](/docs/organizations#roles) or an [API key](/docs/api-keys). The [audit logs](/docs/audit-logs) record port exposes and unexposes, preview URL creation, and signed URL revocation. | **Permission** | **Grants** | | --------------------- | ------------------------------------------------------------------------------------------------------------- | | **`read:sandboxes`** | List and get exposed ports, and open private previews in a signed-in browser | | **`write:sandboxes`** | Expose and unexpose ports, create standard and signed preview URLs, and open private previews with an API key | # Playground (/docs/playground) Daytona provides an interactive environment ("playground") in the [Daytona Dashboard ↗](https://app.daytona.com/dashboard) for writing TypeScript against the [TypeScript SDK](/docs/typescript-sdk) and running it in your browser. It bundles the SDK and provides a code editor with type checking and completions, an examples browser, and a console for program output. You do not install anything locally or handle an API key. ## Use cases [#use-cases] The playground is used to run TypeScript SDK code without a local setup. - **SDK trials.** SDK calls run in a web worker inside the browser. The playground provides the API key and endpoints, so there is nothing to install or configure. The Run button compiles the program and executes it in that web worker. - **Learning the SDK.** The editor checks types and completes names from the SDK's type definitions. A new user sees the available methods and their parameters while writing the code. Programs are plain TypeScript that import the Daytona SDK, and top-level await is supported. - **Commands and files.** A program runs a shell command in a sandbox, writes and reads files, and prints the results to the console. The Run a command and File operations examples show both tasks. File reads and writes go through the toolbox file system API. - **Operation sequences.** A sequence of sandbox operations runs against the Daytona API and is checked before it goes into an application. A stopped run does not clean up the sandboxes it already created. Any sandbox created mid-run can still exist after the stop, and a delete removes it. - **Starting points.** A curated example runs as it is, then changes, then moves into your own application. The examples cover the sandbox lifecycle, commands, files, images, and volumes. A Snapshots example creates a sandbox snapshot and launches a second sandbox from it. ## Access from Dashboard [#access-from-dashboard] 1. Go to [Daytona Dashboard ↗](https://app.daytona.com/dashboard) 2. Click in the sidebar to access the playground ## Writing code [#writing-code] Programs are plain TypeScript that import the Daytona SDK. Top-level await is supported, and the editor provides type checking and completions from the SDK's type definitions. ```typescript import { Daytona } from '@daytona/sdk' // The playground provides the API key and endpoints for you — no config needed. const daytona = new Daytona() async function main() { console.log('Creating a sandbox…') const sandbox = await daytona.v2.create() console.log('Sandbox ready:', sandbox.id, '(', sandbox.state, ')') console.log('Cleaning up…') await daytona.v2.delete(sandbox) console.log('Done.') } await main() ``` ## Running code [#running-code] 1. Go to [Daytona Playground ↗](https://app.daytona.com/dashboard/playground) to access the playground. 2. Click to compile the program and execute it in a web worker inside your browser. 3. Click to terminate a run in progress. Stopping a run does not clean up resources it already created. Any sandbox created mid-run may still exist — delete it if needed. ## Examples [#examples] | Example | Description | | --------------------------- | ---------------------------------------------------------------------------------------- | | **Hello sandbox** | Create a sandbox, print its id and state, then delete it. | | **Lifecycle** | Create, list and delete sandboxes; inspect state transitions. | | **Run a command** | Execute a shell command inside a sandbox and read its output. | | **File operations** | Write, list and read files in a sandbox via the toolbox file system API. | | **Snapshots** | Create a sandbox snapshot and launch a second sandbox from it. | | **Build from a Dockerfile** | Build an image from an inline Dockerfile, then launch a sandbox from it. | | **Volumes** | Attach a persistent volume to two sandboxes: write a file in one, read it in the other. | For more information on the operations used in the examples, see [sandboxes](/docs/sandboxes), [process execution](/docs/process-execution), [code execution](/docs/code-execution), [file system operations](/docs/file-system-operations), [snapshots](/docs/snapshots), and [volumes](/docs/volumes). # Secrets (/docs/secrets) Secrets store sensitive values such as API keys, tokens, and passwords for use across your Daytona sandboxes. They let sandbox code authenticate to external services without hardcoding credentials into your source, snapshots, or sandbox environment variables. Secrets are project-scoped, encrypted credentials that Daytona injects into a sandbox's outbound HTTPS traffic without ever placing the plaintext inside the sandbox. Instead of an environment variable holding the actual API key, the sandbox holds an opaque placeholder token. An outbound proxy replaces the placeholder with the real value before the request reaches its destination, and only when the request goes to a host you have allowed. This lets you give a sandbox access to a credential such as an LLM API key or a database password while keeping the plaintext out of the sandbox environment, file system, process arguments, and logs. Code running in the sandbox can use the credential to reach an approved host, but cannot read the value from the sandbox or send it to any other host. The proxy does not rewrite responses, so an approved host that [echoes the credential](#verify-substitution) returns the value into the sandbox. | **Field** | **Description** | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | **Name** | Unique name within the project, 1 to 256 letters, digits, and underscores, not starting with a digit. Doubles as the environment variable name in the sandbox. | | **Value** | The plaintext value, up to 64 KiB. Encrypted at rest and never returned by the API after creation. | | **Description** | Optional human-readable description. | | **Allowed Domains** | Allowlist of hosts the secret may be sent to. Supports exact hosts, wildcard subdomains, or any verified host. Required. | | **Updated At** | Timestamp of the last write. | ## Use cases [#use-cases] Secrets are used when sandbox code needs a credential for an HTTPS service but must not be able to read it. - **Model provider keys for agents.** An agent calls a model API with a key it cannot read. The proxy substitutes the key only for the provider's host, so the agent cannot send it anywhere else. Responses pass through unchanged, so a provider that echoes the key returns the plaintext into the sandbox. - **Third-party HTTPS APIs.** Tokens for source control, payment, or other APIs are substituted in each request. The plaintext stays out of files, environment variables, process arguments, and logs. The proxy replaces placeholders in the request line, every header, and the body, so the token can sit wherever the API expects. - **Untrusted code.** Code from users or agents uses a credential, and the host allowlist limits where the value can go. A request to any other host carries only the placeholder. The proxy dials the destination itself and validates its certificate, so code that spoofs DNS, SNI, or the Host header cannot redirect the value. - **Credentials outside images and snapshots.** The sandbox holds only a placeholder, so source code, images, and snapshots carry no plaintext. A snapshot restore attaches the source's secrets again, with the exceptions in [use a secret in a sandbox](#use-a-secret-in-a-sandbox). Forks attach the source's secrets too, under the same placeholders. - **Shared credentials without shared values.** A member with the secrets read permission attaches a secret to a sandbox but never sees its value. The API does not return a value after creation. The member also needs the sandbox write permission, which an [organization role](/docs/organizations) or an API key can grant. ## Substitution scope [#substitution-scope] The proxy substitutes placeholders in the request line and query string, in every request header, and in the request body. Send the secret wherever the destination service expects it, for example in an Authorization or X-Api-Key header or in a JSON body field. Before substituting into an HTTPS request, the proxy resolves and dials the destination itself and validates the upstream certificate against the system roots, so a sandbox that spoofs DNS, SNI, or the Host header cannot redirect a substituted secret. Every request on a TLS connection must address the SNI host; a request for another host on that connection returns 400. The following cases are not substituted: - **Cleartext HTTP** is never substituted. A plain `http://` destination cannot be authenticated, so the placeholder is forwarded intact, even for allowlisted hosts. Use HTTPS. - **Request bodies over 1 MiB** stream through; placeholders past 1 MiB are not replaced. - **Transformed placeholders** are not substituted. Substitution is a literal replacement, so the request must carry the placeholder unmodified. Tools that encode the placeholder before sending, such as Basic Auth helpers that Base64-encode credentials, produce a header the proxy cannot match. See [HTTP Basic auth](#http-basic-auth). - **HTTP/2** is not supported. The proxy speaks HTTP/1.1 and does not offer `h2` during ALPN, so standard HTTP clients negotiate HTTP/1.1. A client that requires HTTP/2, such as a gRPC client, fails because the proxy negotiates HTTP/1.1. - **Certificate-pinned and ECH clients** cannot be intercepted. The proxy terminates TLS with its own certificate authority, so a client that pins a different certificate rejects the proxy's leaf and the handshake fails. A client that uses Encrypted Client Hello is not supported either. In both cases the request does not reach the destination. - **Non-HTTP protocols** on other ports carry the placeholder as-is. Sandboxes with secrets block UDP port 443, so HTTP/3 clients fall back to TLS over TCP and are substituted normally. ## Certificate trust [#certificate-trust] The proxy terminates TLS with its own certificate authority and mints a leaf certificate per destination. Daytona installs the authority before the entrypoint so clients trust the leaf: | **File** | **Contents** | | ---------------------------- | -------------------------------------------------- | | **`/etc/rlp/ca.pem`** | The proxy CA certificate. | | **`/etc/rlp/ca-bundle.pem`** | The system root bundle with the proxy CA appended. | Daytona also exports the following environment variables into every process the sandbox spawns, so common clients trust the bundle without configuration: | **Variable** | **Value** | **Read by** | | ----------------------- | ------------------------- | ------------------------ | | **`SSL_CERT_FILE`** | `/etc/rlp/ca-bundle.pem` | OpenSSL-based clients | | **`REQUESTS_CA_BUNDLE`**| `/etc/rlp/ca-bundle.pem` | Python `requests`, `httpx` | | **`CURL_CA_BUNDLE`** | `/etc/rlp/ca-bundle.pem` | `curl` | | **`NODE_EXTRA_CA_CERTS`**| `/etc/rlp/ca.pem` | Node.js | | **`GIT_SSL_CAINFO`** | `/etc/rlp/ca-bundle.pem` | `git` over HTTPS | | **`DENO_CERT`** | `/etc/rlp/ca-bundle.pem` | Deno | A client that ignores these variables and reads only its own trust store must be pointed at the CA bundle in the table, otherwise its TLS handshake against the proxy fails. Do not disable certificate verification to work around this. The CA install is best-effort: when the image does not allow writes to the CA location, the placeholder environment variables are still set. The proxy does not rewrite responses. If a destination echoes the credential, the real value enters the sandbox in the response body. Do not send a secret to an echo or debugging service you would not trust with the plaintext or use one to test substitution. See [verify substitution](#verify-substitution). ## Host allowlist [#host-allowlist] The host allowlist is the set of hosts a secret may be sent to. Set your allowed hosts using the allowed domains array when [creating a secret](#create-a-secret) or [updating a secret](#update-a-secret). The proxy replaces the placeholder only for requests whose destination host matches an entry in the allowlist; a request to any other host carries the unmodified placeholder. Every secret requires an allowlist. A wildcard entry that is a single asterisk allows any verified host: the proxy replaces the placeholder for HTTPS requests to any host, including one a compromised sandbox controls. List specific hosts unless you have a specific reason not to. | **Rule** | **Description** | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Hosts only** | Use hostnames of up to 253 characters made of letters, digits, dots, and hyphens; entries with a scheme, path, port, whitespace, a leading dot, or an empty label are rejected with `400`. | | **Wildcards supported** | Prefix a host with `*.` to allow its subdomains. The base domain itself does not match, and the part after `*.` cannot be a public suffix such as `com` or `co.uk`. | | **Case-insensitive** | Host matching ignores letter case. | | **Scope tightly** | List only the hosts the secret requires. | The following examples are valid: | **Example** | **Value** | | ------------------ | ------------------------------------------------------------- | | **Single host** | `["api.example.com"]` | | **Wildcard host** | `["*.example.com"]` | | **Multiple hosts** | `["api.example.com", "*.example.org", "service.example.net"]` | The allowlist decides only whether a placeholder is substituted. It does not block traffic: a request to a host outside the allowlist is still forwarded, carrying the placeholder. To restrict which hosts a sandbox can reach at all, set a sandbox [network policy](/docs/network-limits). The two are independent and both apply. ## Create a secret [#create-a-secret] Daytona provides methods to create a secret. A secret is created with a put request to its name, which also updates an existing secret of the same name. Set the if-not-exists flag to make the write create-only: the request then fails if the name is already taken, and the check runs in the same transaction as the write, so two concurrent creates cannot overwrite each other. 1. Go to [Daytona Dashboard ↗](https://app.daytona.com/dashboard/secrets) 2. Click 3. Enter a **Name** and a **Value**. The value is write-only and is not shown again after saving 4. Optionally enter a **Description** and a comma-separated list of **Allowed Domains** 5. Click ```python from daytona import Daytona daytona = Daytona() daytona.v2.secrets.set( "MY_API_KEY", "secret-value", description="Example API key", allowed_domains=["api.example.com"], if_not_exists=True, ) ``` | **Parameter** | **Type** | **Description** | | ----------------- | --------------- | ------------------------------------------------------------------------------ | | `allowed_domains` | Sequence\[str\] | Sets the host allowlist of the secret. This parameter is required. `["*"]` allows any verified host, including one a compromised sandbox controls. | ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() await daytona.v2.secrets.set('MY_API_KEY', 'secret-value', { description: 'Example API key', allowedDomains: ['api.example.com'], ifNotExists: true, }) ``` | **Parameter** | **Type** | **Description** | | ---------------- | ---------- | ---------------------------------------------------------------------------- | | `allowedDomains` | string\[\] | Sets the host allowlist of the secret. This parameter is required. `['*']` allows any verified host, including one a compromised sandbox controls. | ```bash # --stdin keeps the value out of the process list and shell history # secret set creates or replaces; the CLI has no create-only (if_not_exists) mode printf %s 'secret-value' | daytona secret set MY_API_KEY \ --stdin \ --description 'Example API key' \ --allowed-domain api.example.com ``` | **Flag** | **Type** | **Description** | | ------------------ | --------- | --------------------------------------------------- | | `--stdin` | bool | Reads the value from standard input. It strips exactly one trailing newline or CRLF. | | `--from-file` | string | Reads the value from a file. It strips exactly one trailing newline or CRLF. | | `--allowed-domain` | strings | Adds one host to the allowlist. Repeat the flag once per host. Required when creating a secret. `'*'` allows any verified host. | - The request requires the `write:secrets` permission. - Pass the value with exactly one of `--stdin`, `--from-file`, or `--value`. ```bash # If-None-Match: * makes the write create-only; an existing name returns 412 curl 'https://api.daytona.com/secrets/MY_API_KEY' \ --request PUT \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --header 'If-None-Match: *' \ --data '{ "value": "secret-value", "description": "Example API key", "allowed_domains": ["api.example.com"] }' ``` | **Field** | **Type** | **Description** | | ----------------- | ---------- | --------------------------------------------------------------- | | `allowed_domains` | string\[\] | Sets the host allowlist of the secret. This field is required, and an empty list returns `400 Bad Request`. The list holds at most 50 entries. A longer list returns `400 Bad Request`. | | `description` | string | Sets the description. The description is at most 1 KiB. A longer description returns `400 Bad Request`. | ## Use a secret in a sandbox [#use-a-secret-in-a-sandbox] Daytona provides methods to inject a secret into a sandbox. 1. When creating the sandbox, pass `secrets` as a list of secret names. The secret name is the environment variable name injected into the sandbox. 2. Daytona sets that variable to the secret's placeholder, not the real value, before the entrypoint starts. Every process, session, PTY, and SSH exec in the sandbox inherits it. 3. Your code reads the environment variable as usual and sends it in an outbound HTTPS request, for example in an `Authorization` or `X-Api-Key` header. 4. The outbound proxy substitutes the real value into requests to the secret's allowed hosts and leaves the placeholder for any other host. See [substitution scope](#substitution-scope). The same stored secret cannot be injected under a different variable name. Attaching a name that does not exist in the project fails the create before any sandbox is scheduled. Duplicate names are collapsed to one. The secrets parameter is accepted on sandbox creates. To change the secrets of an existing sandbox, see [replace sandbox secrets](#update-secrets-in-a-sandbox). Secrets attached to a sandbox travel with it: a snapshot restore or fork attaches the secrets the source had when its memory was captured, under the same placeholders. Secrets deleted since the capture are not attached, and a caller without the secrets read permission gets none; the copy then reports a partial capture. A restore from a snapshot taken before Daytona recorded the attached secrets attaches none. The [capture status](#get-sandbox-secrets) of the copy reports which case applies. 1. Go to [Daytona Sandboxes ↗](https://app.daytona.com/dashboard/sandboxes) 2. Click 3. Open the **Environment** tab and click 4. Select the secrets to attach and return to the form 5. Click ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create(secrets=["MY_API_KEY"]) ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create({ secrets: ['MY_API_KEY'], }) ``` ```bash daytona sandbox create --secret MY_API_KEY ``` ```bash curl 'https://api.daytona.com/sandboxes' \ --request POST \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "secrets": ["MY_API_KEY"] }' ``` ## Get sandbox secrets [#get-sandbox-secrets] Get the secrets attached to a sandbox. The response lists the attached secret names, never values or placeholders, and reports how far the sandbox has applied them. A change is applied in the background, so the status stays pending until the sandbox has the new set. The response also carries a revision tag that a [replace](#update-secrets-in-a-sandbox) must send back. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create(secrets=["MY_API_KEY"]) info = sandbox.get_secrets() print(info.secrets, info.status, info.etag) ``` The response has the following fields: | **Field** | **Description** | | --- | --- | | `secrets` | The names of the project secrets attached to the sandbox. | | `desired_revision` | The revision of `secrets`. A sandbox that has not changed its secrets since creation is at revision `0`. | | `applied_revision` | The revision the sandbox has applied, or `None` before the first change. | | `status` | The status is `pending`, `applied`, or `failed`. It is `None` before the first change. | | `error` | Explains why the change failed when `status` is `failed`. | | `etag` | The revision token to send back when you replace the secrets. | | `http_status` | The HTTP status code of the response. | | `capture_status` | For a restored or forked sandbox, how much of the source's secrets the copy received: `complete`, `partial`, or `unresolved_legacy`. Otherwise `None`. | | `capture_unresolved_count` | For a `partial` copy, the number of the source's secrets the copy did not receive. | - The request requires the `read:sandboxes` and `read:secrets` permissions. - The sandbox must be a Linux sandbox without GPUs. ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create({ secrets: ['MY_API_KEY'] }) const info = await sandbox.getSecrets() console.log(info.secrets, info.status, info.etag) ``` The response has the following fields: | **Field** | **Description** | | --- | --- | | `secrets` | The names of the project secrets attached to the sandbox. | | `desiredRevision` | The revision of `secrets`. A sandbox that has not changed its secrets since creation is at revision `0`. | | `appliedRevision` | The revision the sandbox has applied, or `undefined` before the first change. | | `status` | The status is `pending`, `applied`, or `failed`. It is `undefined` before the first change. | | `error` | Explains why the change failed when `status` is `failed`. | | `etag` | The revision token to send back when you replace the secrets. | | `httpStatus` | The HTTP status code of the response. | | `captureStatus` | For a restored or forked sandbox, how much of the source's secrets the copy received: `complete`, `partial`, or `unresolved_legacy`. Otherwise `undefined`. | | `captureUnresolvedCount` | For a `partial` copy, the number of the source's secrets the copy did not receive. | - The request requires the `read:sandboxes` and `read:secrets` permissions. - The sandbox must be a Linux sandbox without GPUs. ```bash # --include prints the ETag response header curl 'https://api.daytona.com/sandboxes/{sandboxId}/secrets' \ --include \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ```json { "secrets": ["MY_API_KEY", "GITHUB_TOKEN"], "desired_revision": 1, "applied_revision": 1, "status": "applied", "error": null, "capture_status": null, "capture_unresolved_count": null } ``` The response has the following fields: | **Field** | **Description** | | --- | --- | | `ETag` | Holds the revision as `"sv-"`, for example `"sv-1"`. This value is a response header. | | `status` | The status is `pending`, `applied`, or `failed`. It is `null` before the first change. | - The request requires the `read:sandboxes` and `read:secrets` permissions. - The sandbox must be a Linux sandbox without GPUs. ## Update secrets in a sandbox [#update-secrets-in-a-sandbox] Replace the secrets attached to an existing sandbox. A replace sends the full list of names; names left out are detached, names that stay attached keep their placeholders, and new names get new ones. Every replace sends the revision tag from the last read. If the secrets changed since that read, the replace fails instead of overwriting them; get the secrets again and retry with the new tag. The sandbox applies the change asynchronously. The replace reports the change as pending, and a later [get](#get-sandbox-secrets) reports it as applied once the sandbox has the new set, or as failed with an error. Processes that are already running keep their environment; processes started after the change see the new names. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create(secrets=["MY_API_KEY"]) current = sandbox.get_secrets() updated = sandbox.replace_secrets( secrets=["MY_API_KEY", "GITHUB_TOKEN"], if_match=current.etag, ) print(updated.status) # pending until the sandbox applies the change ``` | **Parameter** | **Type** | **Description** | | ------------- | --------------- | ------------------------------------------------------------------------------------------------------- | | `secrets` | Sequence\[str\] | Sets the full list of project secret names attached to the sandbox. Names left out are detached. | | `if_match` | str | Sets the revision tag from the last read. This parameter is required. A stale tag raises an error. Read again and retry. | - The request requires the `write:sandboxes` and `read:secrets` permissions. - The sandbox must be a Linux sandbox without GPUs. - The sandbox must be running, paused, or stopped. - A sandbox in a transition, or with a memory snapshot or fork in progress, must settle before the request. ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create({ secrets: ['MY_API_KEY'] }) const current = await sandbox.getSecrets() const updated = await sandbox.replaceSecrets( ['MY_API_KEY', 'GITHUB_TOKEN'], { ifMatch: current.etag }, ) console.log(updated.status) // pending until the sandbox applies the change ``` | **Parameter** | **Type** | **Description** | | ------------- | ---------- | ------------------------------------------------------------------------------------------------------- | | `secrets` | string\[\] | Sets the full list of project secret names attached to the sandbox. Names left out are detached. | | `ifMatch` | string | Sets the revision tag from the last read. This parameter is required. A stale tag throws an error. Read again and retry. | - The request requires the `write:sandboxes` and `read:secrets` permissions. - The sandbox must be a Linux sandbox without GPUs. - The sandbox must be running, paused, or stopped. - A sandbox in a transition, or with a memory snapshot or fork in progress, must settle before the request. ```bash # If-Match takes the ETag from the last read, for example "sv-1" curl 'https://api.daytona.com/sandboxes/{sandboxId}/secrets' \ --request PUT \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --header 'If-Match: "sv-1"' \ --data '{ "secrets": ["MY_API_KEY", "GITHUB_TOKEN"] }' ``` | **Field / Header** | **Type** | **Description** | | ------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------- | | `secrets` | string\[\] | Sets the full list of project secret names attached to the sandbox. A duplicate name returns `400 Bad Request`. | | `If-Match` | header | Sets the `ETag` from the last read. A missing header returns `428 Precondition Required`; a stale one returns `412 Precondition Failed`. | - The request requires the `write:sandboxes` and `read:secrets` permissions. - The sandbox must be a Linux sandbox without GPUs. - The sandbox must be running, paused, or stopped. - A sandbox in a transition, or with a memory snapshot or fork in progress, must settle before the request. - The response `ETag` header holds the new revision tag; send it as `If-Match` on the next replace. ## Verify substitution [#verify-substitution] Verify substitution by calling the real service and checking the status code. For example, store a GitHub token as a secret allowed for api.github.com, then call the GitHub user endpoint from the sandbox. A successful response proves the proxy replaced the placeholder with the real token, because GitHub rejects the placeholder. Do not use an echo service for this. Responses are not rewritten, so an echo service returns the substituted value into the sandbox and defeats the point of the secret. ```python from daytona import Daytona daytona = Daytona() daytona.v2.secrets.set( "GITHUB_TOKEN", "ghp_your_real_token", allowed_domains=["api.github.com"], ) sandbox = daytona.v2.create( secrets=["GITHUB_TOKEN"], ) response = sandbox.process.run( 'curl -s -o /dev/null -w "%{http_code}" ' '-H "Authorization: Bearer $GITHUB_TOKEN" https://api.github.com/user' ) print(response.output) # 200 proves substitution works ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() await daytona.v2.secrets.set('GITHUB_TOKEN', 'ghp_your_real_token', { allowedDomains: ['api.github.com'], }) const sandbox = await daytona.v2.create({ secrets: ['GITHUB_TOKEN'], }) const response = await sandbox.process.run( 'curl -s -o /dev/null -w "%{http_code}" -H "Authorization: Bearer $GITHUB_TOKEN" https://api.github.com/user' ) console.log(response.output) // 200 proves substitution works ``` ```bash printf %s 'ghp_your_real_token' | daytona secret set GITHUB_TOKEN --stdin --allowed-domain api.github.com daytona sandbox create --secret GITHUB_TOKEN # 200 proves substitution works daytona sandbox exec {sandboxId} -- sh -c \ 'curl -s -o /dev/null -w "%{http_code}" -H "Authorization: Bearer $GITHUB_TOKEN" https://api.github.com/user' ``` ## Operations [#operations] ### List secrets [#list-secrets] List operations return one page of the project's secrets, ordered by name, with a cursor for the next page. A page holds 100 secrets by default and at most 200. List operations return metadata only. Secret values are never returned after creation. 1. Go to [Daytona Dashboard ↗](https://app.daytona.com/dashboard/secrets) 2. Use the search field to filter the list by name ```python from daytona import Daytona daytona = Daytona() secrets = daytona.v2.secrets.list() for secret in secrets.items: print(secret.name) ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const secrets = await daytona.v2.secrets.list() secrets.items.forEach((secret) => console.log(secret.name)) ``` ```bash daytona secret list ``` ```bash curl 'https://api.daytona.com/secrets' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ##### Iterate over all secrets [#iterate-over-all-secrets] Iterate over all secrets in the project. The iterator requests the pages one after another and yields the items one at a time. ```python from daytona import Daytona daytona = Daytona() for secret in daytona.v2.secrets.iter(): print(secret.name, secret.allowed_domains) ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() for await (const secret of daytona.v2.secrets.iter()) { console.log(secret.name, secret.allowedDomains) } ``` ### Get a secret [#get-a-secret] Get a secret by name: allowed domains, description, and update time, never the value. ```python from daytona import Daytona daytona = Daytona() secret = daytona.v2.secrets.get("MY_API_KEY") ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const secret = await daytona.v2.secrets.get('MY_API_KEY') ``` ```bash daytona secret get MY_API_KEY ``` ```bash curl 'https://api.daytona.com/secrets/MY_API_KEY' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ### Update a secret [#update-a-secret] Update a secret. An update is the same write as a create: it always takes a new value and replaces the value, the allowed domains, and the description together. 1. Go to [Daytona Dashboard ↗](https://app.daytona.com/dashboard/secrets) 2. Click the menu of the secret and click 3. Enter a **New Value**. The current value cannot be shown, so a new value is required 4. Adjust the **Description** and **Allowed Domains** as needed 5. Click ```python from daytona import Daytona daytona = Daytona() daytona.v2.secrets.set( "MY_API_KEY", "new-secret-value", allowed_domains=["api.example.com", "*.example.com"], ) ``` - The request requires the `write:secrets` permission. - `set` does not merge with the stored secret. - Omitting `description` clears the description. - Pass `description` again to keep it. ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() await daytona.v2.secrets.set('MY_API_KEY', 'new-secret-value', { allowedDomains: ['api.example.com', '*.example.com'], }) ``` - The request requires the `write:secrets` permission. - `set` does not merge with the stored secret. - Omitting `description` clears the description. - Pass `description` again to keep it. ```bash # The description and allowed domains you omit keep their current values printf %s 'new-secret-value' | daytona secret set MY_API_KEY \ --stdin \ --allowed-domain api.example.com \ --allowed-domain '*.example.com' ``` ```bash curl 'https://api.daytona.com/secrets/MY_API_KEY' \ --request PUT \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "value": "new-secret-value", "allowed_domains": ["api.example.com", "*.example.com"] }' ``` - The request requires the `write:secrets` permission. - `PUT` replaces the whole secret. - Omitting `description` clears the description. ### Delete a secret [#delete-a-secret] Delete a secret. To revoke a secret without deleting it, overwrite its value or narrow its allowed domains. 1. Go to [Daytona Dashboard ↗](https://app.daytona.com/dashboard/secrets) 2. Click the menu of the secret and click 3. Click to confirm ```python from daytona import Daytona daytona = Daytona() daytona.v2.secrets.delete("MY_API_KEY") ``` - The request requires the `delete:secrets` permission. - No sandbox or bucket volume may reference the secret. - To detach the secret from a sandbox, [replace the sandbox secrets](#update-secrets-in-a-sandbox) first. ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() await daytona.v2.secrets.delete('MY_API_KEY') ``` - The request requires the `delete:secrets` permission. - No sandbox or bucket volume may reference the secret. - To detach the secret from a sandbox, [replace the sandbox secrets](#update-secrets-in-a-sandbox) first. ```bash daytona secret delete MY_API_KEY ``` - The request requires the `delete:secrets` permission. - No sandbox or bucket volume may reference the secret. - To detach the secret from a sandbox, [replace the sandbox secrets](#update-secrets-in-a-sandbox) first. ```bash curl 'https://api.daytona.com/secrets/MY_API_KEY' \ --request DELETE \ --header 'Authorization: Bearer YOUR_API_KEY' ``` - The request requires the `delete:secrets` permission. - No sandbox or bucket volume may reference the secret. - To detach the secret from a sandbox, [replace the sandbox secrets](#update-secrets-in-a-sandbox) first. ### HTTP Basic Auth [#http-basic-auth] Basic Auth helpers in HTTP clients do not work with a secret that holds a raw password. These helpers Base64-encode the credential inside the sandbox, so the outbound Authorization header carries the encoded username and placeholder. The encoded header no longer contains the placeholder, the proxy cannot substitute it, and the upstream service rejects the request. To authenticate with Basic Auth, store the Base64-encoded username and password pair as the secret value and set the Authorization header directly: 1. Encode the credential outside the sandbox: `printf '%s' 'username:password' | base64` 2. Store the encoded value as a secret 3. In the sandbox, set the header directly: `Authorization: Basic $MY_SECRET` The placeholder then appears unmodified in the header, and the proxy substitutes the encoded credential for requests to the secret's allowed hosts. Do not pass the mounted variable through a helper that encodes it again. ```python import base64 from daytona import Daytona daytona = Daytona() payload = base64.b64encode(b"username:password").decode() daytona.v2.secrets.set( "BASIC_AUTH", payload, allowed_domains=["api.example.com"], ) sandbox = daytona.v2.create( secrets=["BASIC_AUTH"], ) response = sandbox.process.run( 'curl -s -o /dev/null -w "%{http_code}" ' '-H "Authorization: Basic $BASIC_AUTH" https://api.example.com/protected' ) print(response.output) ``` - The requests require the `write:secrets` and `write:sandboxes` permissions. - To send the full header value instead, store `Basic Base64(username:password)` as the secret value and send `Authorization: $BASIC_AUTH`. ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const payload = Buffer.from('username:password').toString('base64') await daytona.v2.secrets.set('BASIC_AUTH', payload, { allowedDomains: ['api.example.com'], }) const sandbox = await daytona.v2.create({ secrets: ['BASIC_AUTH'], }) const response = await sandbox.process.run( 'curl -s -o /dev/null -w "%{http_code}" -H "Authorization: Basic $BASIC_AUTH" https://api.example.com/protected' ) console.log(response.output) ``` - The requests require the `write:secrets` and `write:sandboxes` permissions. - To send the full header value instead, store `Basic Base64(username:password)` as the secret value and send `Authorization: $BASIC_AUTH`. ```bash # --stdin strips the trailing newline that base64 prints printf %s 'username:password' | base64 | daytona secret set BASIC_AUTH --stdin --allowed-domain api.example.com daytona sandbox create --secret BASIC_AUTH daytona sandbox exec {sandboxId} -- sh -c \ 'curl -s -o /dev/null -w "%{http_code}" -H "Authorization: Basic $BASIC_AUTH" https://api.example.com/protected' ``` - The requests require the `write:secrets` and `write:sandboxes` permissions. - To send the full header value instead, store `Basic Base64(username:password)` as the secret value and send `Authorization: $BASIC_AUTH`. ## Permissions [#permissions] Secrets are scoped to a project. A secret needed by two projects must be stored in each. Access is governed by three permissions, which you can grant to an [organization role](/docs/organizations) or an [API key](/docs/api-keys). Attaching a secret when creating a sandbox requires the secrets read permission in addition to the sandbox write permission. The dashboard enforces the same project-scoped permissions as the API: a member whose role lacks the secrets write permission does not see the create and edit actions, and one without the secrets delete permission does not see the delete action. The [audit logs](/docs/audit-logs) record creates, updates, and deletes by secret name, never value. | **Permission** | **Grants** | | ------------------- | ------------------------------------------------ | | **`read:secrets`** | List and get secret metadata, never values | | **`write:secrets`** | Create and update secrets | | **`delete:secrets`** | Delete secrets | # Audit Logs (/docs/audit-logs) Audit logs provide a detailed record of user and system activity across your organization. Each entry records an action, the actor and credential behind it, the resource it targeted, and the result. Reading audit logs requires the audit read organization permission. [Administrators](/docs/organizations#roles) hold it, as does the dedicated **Auditor** role, which grants read access to the log without the ability to turn logging off. Contact your organization administrator to get access to audit logs. Audit logs are retained for 365 days. Querying audit logs requires the Enterprise [plan](/docs/billing#get-the-plan). Daytona records audit logs for every organization regardless of plan. ## Use cases [#use-cases] Audit logs are used when an organization must know who did what, when, and with which credential. - **Security audits.** Unauthorized access or sandbox misuse is traced to a user, an API key, an IP address, and a time. The key prefix identifies the key without exposing it. Entries may also include the user agent of the request. - **Debugging.** Sandbox lifecycle problems, such as a failed start, are traced to the request that caused them. Each entry carries the HTTP status code and the error message. Entries for a failed action show the Error [outcome](#outcomes), which covers 4xx and 5xx codes. - **Compliance reviews.** Actions across the organization stay on record for 365 days. Management-plane actions, such as changes to members and credentials, are always recorded and cannot be turned off. Earlier entries stay readable until retention ends, even after workload-plane capture is turned off. - **Access reviews.** Member role changes and removals, invitations, and the creation and role updates of service accounts are recorded with the previous and the new roles. A review shows who granted which access and when. Role changes that were only validated carry a dry run flag in their metadata. - **Scripted reviews.** The CLI and the API filter entries by action, target, actor, status code, and time range. A script pages through the results to collect the entries for a review. Each request accepts at most 10 [filters](#query-parameters) and returns up to 200 entries per page. ## Access from Dashboard [#access-from-dashboard] 1. Go to [Daytona Dashboard ↗](https://app.daytona.com/dashboard) Access the audit logs page directly from [Daytona Dashboard ↗](https://app.daytona.com/dashboard/audit-logs). The audit logs page displays a list of all audit logs for your organization, including the following columns: | **Column** | **Description** | | ------------------------- | ---------------------------------------------- | | **Time** | The timestamp of the action. | | **Actor** | The user or API key that performed the action. | | **Action** | The action performed. | | **Target** | The resource affected by the action. | | [**Outcomes**](#outcomes) | The result of the action. | Select any row to open the full log entry, including its metadata. On plans other than Enterprise, the table is disabled and empty under an Enterprise notice. To filter audit logs by time, use the date range picker in the top-left corner of the page. The filter menu next to it adds equality filters on action, target type, target ID, actor, and status code. ## Real-time updates [#real-time-updates] Refresh the audit log list as new events occur. 1. Go to [Daytona Audit Logs ↗](https://app.daytona.com/dashboard/audit-logs) 2. Use the refresh control in the top-right corner of the page The refresh icon fetches the current page immediately. The interval selector repeats that fetch every **10s**, **30s**, **1m**, or **5m**, or on **Auto**, which polls every 30 seconds. Auto-refresh is **Off** by default. ## Log structure [#log-structure] Each audit log entry contains the following fields: | Field | Type | Description | | ------------------ | ---------------- | --------------------------------------------------------------------------------- | | `id` | string | Unique log entry identifier | | `org_id` | string | ID of the organization the action belongs to | | `project_id` | string \| null | ID of the project the action belongs to, or `null` for organization-level actions | | `actor_kind` | string | Credential type of the actor: `user`, `api_key`, `org_key`, `vm`, or `system` | | `actor_user_id` | string \| null | ID of the user who performed the action, or `null` for a machine credential | | `actor_email` | string \| null | Email of the user who performed the action | | `actor_key_id` | string \| null | ID of the API key used, or `null` when the actor is a signed-in user | | `actor_key_prefix` | string \| null | Prefix of the API key used, for identifying a key without exposing it | | `action` | string | Operation executed (e.g. `create`, `start`, `stop`) | | `target_type` | string | Resource type affected (e.g. `sandbox`, `snapshot`) | | `target_id` | string \| null | ID of the affected resource | | `status_code` | number | HTTP status code of the result | | `error_message` | string \| null | Error message if the action failed, or `null` for a successful action | | `ip_address` | string \| null | IP address of the request origin | | `user_agent` | string \| null | User agent of the request origin | | `metadata` | object \| null | Additional context about the action | | `created_at` | string | RFC 3339 timestamp of when the action occurred | ## Get audit logs for organization [#get-audit-logs-for-organization] Get audit logs for a specific organization, newest first. ```bash daytona audit list --org {organizationId} ``` - The request requires the `read:audit` permission, with an organization API key or a signed-in session. - The request requires the Enterprise plan. ```bash curl 'https://api.daytona.com/orgs/{organizationId}/audit-logs' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` - The request requires the `read:audit` permission, with an organization API key or a signed-in session. - The request requires the Enterprise plan. The response contains one page of entries and a cursor for the next page: ```json { "next_cursor": "MjAyNi0wOS0wOVQxMDoxMjozMy4xMjM0NTY3ODlafDAxOTliMmMx...", "audit_logs": [ { "id": "{auditLogId}", "org_id": "{organizationId}", "project_id": "{projectId}", "actor_kind": "user", "actor_user_id": "{userId}", "actor_email": "user@example.com", "actor_key_id": null, "actor_key_prefix": null, "action": "create", "target_type": "sandbox", "target_id": "{sandboxId}", "status_code": 200, "error_message": null, "ip_address": "203.0.113.42", "user_agent": "daytona-sdk-python", "metadata": { "class": "linux", "region": "{regionId}" }, "created_at": "2026-09-09T10:12:33.123456789Z" } ] } ``` ### Query parameters [#query-parameters] All filters are optional and combine with AND. A filter matches exactly unless it names an operator. A request accepts at most 10 filters. ```bash daytona audit list --org {organizationId} --limit 100 --action create --target-type sandbox ``` | **Flag** | **Type** | **Description** | | ---------- | -------- | ----------------------------------------- | | `--limit` | int | Sets the number of entries per page. The default is `100`. | | `--cursor` | string | Passes a `next_cursor` value. | | `--all` | bool | Follows every page until the last one. | - Each filter flag sets the matching query parameter. - For example, `--target-id` sets `target_id`. ```bash curl 'https://api.daytona.com/orgs/{organizationId}/audit-logs?limit=100&action=create&target_type=sandbox' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` | **Field** | **Type** | **Description** | | ------------- | --------- | -------------------------------------------------------------------------------------------------------------------------- | | `limit` | integer | Sets the number of entries per page. The maximum is `200`, and larger values are clamped. The default is `100`. | | `cursor` | string | Passes an opaque continuation token. Pass the `next_cursor` of the previous page. Pass back only cursors that the API returned. | | `action` | string | Returns only entries with this action. | | `target_type` | string | Returns only entries with this target type. | | `target_id` | string | Returns only entries affecting this resource. | | `actor` | string | Returns only entries with this user ID or API key ID. The value matches either `actor_user_id` or `actor_key_id`. A value that is not a UUID returns `400`. | | `status` | integer | Returns only entries with this HTTP status code. | | `start_at` | string | Returns only entries recorded at or after this RFC 3339 timestamp. The bound is inclusive. | | `end_at` | string | Returns only entries recorded before this RFC 3339 timestamp. The bound is exclusive. | - A filter written as `field=value` matches exactly. - A filter written as `field[op]=value` applies an operator, where `op` is `eq`, `not`, `in`, `not_in`, `gt`, `gte`, `lt`, or `lte`. - The `in` and `not_in` operators take a comma-separated list, and the range operators apply only to `status`. ## List audit actions [#list-audit-actions] List audit actions. The response lists every target type the audit log records and the actions possible for each, derived from the audited operations. Use it to build valid filters for audit log queries. The list is the same for every organization, and the request requires a credential. ```python from daytona import Daytona daytona = Daytona() actions = daytona.v2.list_audit_actions() for target in actions.targets: print(target.target_type, target.actions) ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const actions = await daytona.v2.listAuditActions() for (const target of actions.targets) { console.log(target.targetType, target.actions) } ``` ```bash curl 'https://api.daytona.com/audit/actions' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` The response contains one entry per target type: ```json { "targets": [ { "target_type": "api_key", "actions": ["create", "delete"] }, { "target_type": "checkpoint", "actions": ["create"] }, { "target_type": "function", "actions": ["create", "delete", "update"] }, { "target_type": "image", "actions": ["create", "delete"] }, { "target_type": "org_api_key", "actions": ["create", "delete"] }, { "target_type": "organization", "actions": ["create", "delete", "update"] }, { "target_type": "organization_invitation", "actions": ["create", "decline", "delete", "update"] }, { "target_type": "organization_user", "actions": ["delete", "update"] }, { "target_type": "otel_config", "actions": ["delete", "update"] }, { "target_type": "platform_token", "actions": ["create"] }, { "target_type": "preview_endpoint", "actions": ["create", "delete", "expire", "update"] }, { "target_type": "project", "actions": ["create", "delete", "update"] }, { "target_type": "project_member", "actions": ["create", "delete"] }, { "target_type": "project_service_account", "actions": ["create", "delete"] }, { "target_type": "registry", "actions": ["delete", "update"] }, { "target_type": "sandbox", "actions": ["create", "delete", "fork", "pause", "resume", "start", "stop", "update"] }, { "target_type": "secret", "actions": ["delete", "update"] }, { "target_type": "service_account", "actions": ["create", "delete", "update"] }, { "target_type": "snapshot", "actions": ["create", "delete", "replicate"] }, { "target_type": "volume", "actions": ["create", "delete"] } ] } ``` Some pairs cover more than one operation: - `organization` `update` is recorded for changes to the organization itself, for the [audit logging toggle](#turn-audit-logging-off), and for billing changes: wallet top-ups, the automatic top-up rule, coupon redemption, plan changes, the balance notification rule, and the billing contact email. - `organization_invitation` `update` is the invitee accepting the invitation. `delete` is the organization revoking it. `decline` is the invitee refusing it. - `sandbox` `create` is also recorded for every pre-signed file URL and every sandbox access token minted for the sandbox. - `sandbox` `update` covers label, network policy, secret, and lifecycle policy changes, and signing key rotation. - `service_account` `delete` archives the account and its keys; the record survives. ## Metadata [#metadata] The metadata field carries context that the handler for the action already resolved. It never contains secret values. Entries for pairs not listed here have empty or null metadata. | Target type | Action | Keys | | ----------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------- | | **`sandbox`** | `create` | `class`, `region` | | **`sandbox`** | `fork` | `forked_from`: ID of the source sandbox | | **`snapshot`** | `create` | `kind`: `disk` or `full` | | **`image`** | `create` | `region` | | **`api_key`** | `create` | `service_account_id` when the key was minted for a service account. Otherwise no metadata | | **`project`** | `update` | `previous_name`, `name` | | **`project`** | `delete` | `revoked_keys`: number of API keys revoked with the project | | **`project_member`** | `create` | `user_ids` on a bulk add, where `target_id` is the project ID. A single add has no metadata and `target_id` is the user ID | | **`project_member`** | `delete` | `revoked_keys`: number of API keys revoked with the membership | | **`project_service_account`** | `delete` | `revoked_keys`: number of API keys revoked with the membership | | **`organization`** | `update` | `audit_logs_disabled` (boolean) when the entry records the audit logging toggle. Other updates have no metadata | | **`organization`** | `delete` | `revoked_keys`: number of API keys revoked, `revoked_org_keys`: number of organization API keys revoked, `projects`: number of projects deleted with the organization | | **`organization_user`** | `update` | `previous_roles`, `roles`, and `dry_run: true` when the change was only validated | | **`organization_user`** | `delete` | `previous_roles`, `roles` (empty), `self_removal` (boolean) | | **`organization_invitation`** | `create` | `email`, `previous_roles`, `roles` | | **`organization_invitation`** | `delete` | `email`, `previous_roles`, `roles` (empty) | | **`organization_invitation`** | `decline` | `previous_roles`, `roles` (empty) | | **`service_account`** | `create` | `previous_roles` (empty), `roles` | | **`service_account`** | `update` | `previous_roles`, `roles`, and `dry_run: true` when the change was only validated | | **`service_account`** | `delete` | `already_archived` (boolean) | The roles and previous roles fields are arrays of role slugs. ## Outcomes [#outcomes] The outcome field indicates the result of the action. Statuses follow standard HTTP semantics: | **Outcome** | **Description** | | ----------- | ---------------------------------------- | | Info | Informational (1xx codes) | | Success | Action succeeded (2xx codes) | | Redirect | Redirects (3xx codes) | | Error | Client/server error (4xx/5xx) | | Unknown | No status code was recorded on the entry | ## Turn audit logging off [#turn-audit-logging-off] Audit logging is on by default. Organizations that do not want sandbox activity recorded can turn off capture on the workload plane. Management-plane actions, such as changes to the organization, its members, and its credentials, are always recorded and cannot be turned off. Neither can this setting itself: toggling it is recorded as an update on the organization target. Turning capture off is not retroactive: earlier entries stay readable until retention ends. No API key can change the setting, and the **Auditor** role can read the log but not disable it. ```bash # Read the current setting curl 'https://api.daytona.com/orgs/{organizationId}/audit-logs/config' \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' # Turn workload-plane capture off curl 'https://api.daytona.com/orgs/{organizationId}/audit-logs/config' \ --request PATCH \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' \ --data '{ "disabled": true }' ``` | **Field** | **Type** | **Description** | | ---------- | --------- | --------------------------------------------------------------------- | | `disabled` | boolean | Turns workload-plane capture off with `true` and on with `false`. This field is required. | - Reading the configuration requires the `read:audit` permission. - Changing the configuration requires the `write:audit` permission. Both return the current state: ```json { "disabled": true } ``` ## Permissions [#permissions] Audit logs are scoped to the organization. Access is governed by two organization permissions, which you can grant through an [organization role](/docs/organizations#roles). Administrators hold both permissions. The **Auditor** role holds only the read permission, so it can read the log but not turn logging off. An [organization API key](/docs/api-keys#organization-api-keys) can hold the read permission but never the write permission. | **Permission** | **Grants** | | ----------------- | -------------------------------------------------- | | **`read:audit`** | Query audit logs and get the audit logging setting | | **`write:audit`** | Turn audit logging on or off | # OpenTelemetry (/docs/opentelemetry) OpenTelemetry in Daytona covers two independent paths. Sandbox telemetry is the logs, traces, and metrics produced inside a sandbox, which Daytona collects and can forward to your own OpenTelemetry collector. SDK tracing is the client spans that the Daytona SDKs emit in your application for each request they send to Daytona. Every sandbox reports its own telemetry without any setup: traces of toolbox requests, the output of its processes, and resource metrics. Programs that you run in a sandbox send telemetry only when you point them at the sandbox telemetry endpoint. Daytona does not point any program at the endpoint, including instrumented services that an image starts on its own, such as Docker. SDK tracing is off by default. When it is on, each SDK request runs in a client span in your application's trace and carries W3C trace context headers. The SDKs do not install an OpenTelemetry tracer provider or exporter; your application configures both. | **Term** | **Description** | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | **Sandbox telemetry** | Logs, traces, and metrics produced in a sandbox, by the sandbox itself and by programs configured to send them | | **Telemetry endpoint** | The OTLP/HTTP endpoint inside each sandbox, at the address in `DAYTONA_OTEL_ENDPOINT` | | **Telemetry forwarding** | The organization setting that forwards sandbox telemetry to your OpenTelemetry collector | | **SDK tracing** | Client spans that the Python and TypeScript SDKs emit for each request to Daytona | ## Send telemetry from a program [#send-telemetry-from-a-program] Point a program in a sandbox at the telemetry endpoint to send its logs, traces, and metrics. Every process in the sandbox sees the endpoint address in `DAYTONA_OTEL_ENDPOINT`. Daytona does not set the standard OpenTelemetry exporter variables, so set both of them when you start the program. Telemetry that the program sends is collected with the sandbox's own telemetry and forwarded to your collector when [telemetry forwarding](#forward-sandbox-telemetry) is set. ```python from daytona import Daytona daytona = Daytona() sandbox = daytona.v2.create() response = sandbox.process.run( "OTEL_EXPORTER_OTLP_ENDPOINT=$DAYTONA_OTEL_ENDPOINT " "OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf " "python app.py" ) ``` | **Variable** | **Description** | | ----------------------------- | --------------------------------------------------------------------------------------------------- | | `OTEL_EXPORTER_OTLP_ENDPOINT` | Sets the endpoint the OpenTelemetry SDK in the program exports to. Set it to `$DAYTONA_OTEL_ENDPOINT`. | | `OTEL_EXPORTER_OTLP_PROTOCOL` | Sets the export protocol. Set it to `http/protobuf`. | - The program must use an OpenTelemetry SDK or another OTLP exporter. - The endpoint accepts only uncompressed OTLP/HTTP with protobuf bodies, so set the protocol explicitly. It rejects gRPC, JSON, and gzip. ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const sandbox = await daytona.v2.create() const response = await sandbox.process.run( 'OTEL_EXPORTER_OTLP_ENDPOINT=$DAYTONA_OTEL_ENDPOINT ' + 'OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf ' + 'node app.js', ) ``` | **Variable** | **Description** | | ----------------------------- | --------------------------------------------------------------------------------------------------- | | `OTEL_EXPORTER_OTLP_ENDPOINT` | Sets the endpoint the OpenTelemetry SDK in the program exports to. Set it to `$DAYTONA_OTEL_ENDPOINT`. | | `OTEL_EXPORTER_OTLP_PROTOCOL` | Sets the export protocol. Set it to `http/protobuf`. | - The program must use an OpenTelemetry SDK or another OTLP exporter. - The endpoint accepts only uncompressed OTLP/HTTP with protobuf bodies, so set the protocol explicitly. It rejects gRPC, JSON, and gzip. ```bash daytona sandbox exec {sandboxId} -- bash -c \ 'OTEL_EXPORTER_OTLP_ENDPOINT=$DAYTONA_OTEL_ENDPOINT OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf python app.py' ``` | **Variable** | **Description** | | ----------------------------- | --------------------------------------------------------------------------------------------------- | | `OTEL_EXPORTER_OTLP_ENDPOINT` | Sets the endpoint the OpenTelemetry SDK in the program exports to. Set it to `$DAYTONA_OTEL_ENDPOINT`. | | `OTEL_EXPORTER_OTLP_PROTOCOL` | Sets the export protocol. Set it to `http/protobuf`. | - The program must use an OpenTelemetry SDK or another OTLP exporter. - The endpoint accepts only uncompressed OTLP/HTTP with protobuf bodies, so set the protocol explicitly. It rejects gRPC, JSON, and gzip. - Wrap the command in `bash -c '...'` with single quotes, so the variable expands in the sandbox and not on your machine. ## Forward sandbox telemetry [#forward-sandbox-telemetry] Forward the sandbox telemetry of an organization to your OpenTelemetry collector. Daytona forwards the logs, traces, and metrics of every sandbox in the organization to the OTLP/HTTP endpoint in the forwarding configuration. A configuration set before a plan change keeps forwarding until it is deleted. ### Get the configuration [#get-the-configuration] Get the telemetry forwarding configuration. The response lists the names of the configured request headers; header values are write-only and never returned. ```bash curl 'https://api.daytona.com/orgs/ORGANIZATION_ID/otel-config' \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' ``` ```json { "endpoint": "https://otel.example.com", "header_names": ["Authorization"], "created_at": "2026-09-10T12:00:00Z", "updated_at": "2026-09-10T12:00:00Z" } ``` ### Set the configuration [#set-the-configuration] Set telemetry forwarding. Each write replaces the whole configuration, including headers. ```bash curl 'https://api.daytona.com/orgs/ORGANIZATION_ID/otel-config' \ --request PUT \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "endpoint": "https://otel.example.com", "headers": { "Authorization": "Bearer YOUR_COLLECTOR_TOKEN" } }' ``` | **Field** | **Type** | **Description** | | ---------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `endpoint` | string | Required. Must use `https`, be at most 2048 bytes, and resolve only to public IP addresses; `localhost` and local host names are refused. The collector appends `/v1/logs`, `/v1/traces`, or `/v1/metrics` to the endpoint for each signal. | | `headers` | object | Holds at most 16 entries and at most 16 KiB of names and values in total. Header names are 1 to 128 bytes and unique regardless of case. Header values are 1 to 4096 bytes of visible ASCII, space, or tab. You cannot set transport headers such as `Host`, `Content-Type`, and `Content-Length`. You also cannot set `User-Agent` or any `Proxy-*` header. To keep a stored header value without resending the value, pass `********` as the value. | - The request requires the `write:organization` permission. - The request requires the Enterprise [plan](/docs/billing#get-the-plan). ### Delete the configuration [#delete-the-configuration] Delete the telemetry forwarding configuration. Sandbox telemetry stops being forwarded. ```bash curl 'https://api.daytona.com/orgs/ORGANIZATION_ID/otel-config' \ --request DELETE \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' ``` - The request requires the `write:organization` permission. ## Trace SDK requests [#trace-sdk-requests] Turn on SDK tracing to emit a client span for each request the SDK sends to Daytona. Each span is named after the HTTP method and the route template, such as `daytona.post /sandboxes`, and the SDK adds W3C trace context headers to the request. The spans go to the tracer provider that your application registers; without one, they are not exported. ```bash pip install 'daytona[otel]==2.0.0a11' opentelemetry-sdk opentelemetry-exporter-otlp-proto-http ``` ```python from opentelemetry import trace from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter from opentelemetry.sdk.trace import TracerProvider from opentelemetry.sdk.trace.export import BatchSpanProcessor from daytona import Daytona, DaytonaConfig provider = TracerProvider() provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter())) trace.set_tracer_provider(provider) with Daytona(DaytonaConfig(otel_enabled=True)) as daytona: sandbox = daytona.v2.create() ``` | **Parameter** | **Type** | **Description** | | -------------- | -------- | ----------------------------------------------------------------------------------------------- | | `otel_enabled` | bool | Emits a client span for each SDK request. Falls back to `DAYTONA_OTEL_ENABLED` (`1` or `true`). | - The `otel` extra installs only `opentelemetry-api`. Install the OpenTelemetry SDK and an exporter for your collector. ```bash npm install @daytona/sdk@2.0.0-alpha.11 @opentelemetry/sdk-node @opentelemetry/exporter-trace-otlp-proto ``` ```typescript import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto' import { NodeSDK } from '@opentelemetry/sdk-node' import { Daytona } from '@daytona/sdk' const otel = new NodeSDK({ traceExporter: new OTLPTraceExporter() }) otel.start() const daytona = new Daytona({ otelEnabled: true }) const sandbox = await daytona.v2.create() ``` | **Parameter** | **Type** | **Description** | | -------------- | -------- | ---------------------------------------------------------------------------------------------------------------- | | `otelEnabled` | boolean | Emits a client span for each SDK request. Falls back to `DAYTONA_OTEL_ENABLED` (`1` or `true`). | | `otelApi` | object | Passes your application's `@opentelemetry/api` module. Required in bundled browser applications; optional in Node.js. | - In Node.js, the SDK loads `@opentelemetry/api` itself. In a bundled browser application, pass `import * as otel from '@opentelemetry/api'` as `otelApi`. Each span has the following attributes: | **Attribute** | **Description** | | --------------------------- | --------------------------------------------------------------------- | | `http.request.method` | HTTP method of the request | | `url.template` | Route template of the request, such as `/sandboxes/{id}` | | `server.address` | Host name of the server the request goes to, such as the Daytona API or the toolbox | | `daytona.sandbox_id` | ID of the sandbox the request targets, when the request has one | | `http.response.status_code` | HTTP status code of the response. A status of 400 or higher marks the span as an error. | ## Permissions [#permissions] Telemetry forwarding is configured per organization and is governed by organization permissions, which you can grant through an [organization role](/docs/organizations#roles). Sending telemetry from a program and SDK tracing require no permissions beyond those of the requests they run. The [audit logs](/docs/audit-logs) record changes to the forwarding configuration. | **Permission** | **Grants** | | ------------------------ | ----------------------------------------------- | | **`read:organization`** | Get the telemetry forwarding configuration | | **`write:organization`** | Set and delete the telemetry forwarding configuration | # Migrate from Daytona v0 (/docs/migrate-from-v0) Migration from Daytona v0 moves an organization's resources to Daytona v2. When an organization is migrated, Daytona syncs its API keys, container registries, and snapshots into the organization's default project. Sandboxes are not synced: you import archived Daytona v0 sandboxes one at a time, each as a new persistent sandbox in the default project. Snapshots arrive as named images in an older image format. Each image converts on its first Linux sandbox create, or ahead of time through [image conversion](/docs/images#convert-images). An imported sandbox boots from the last backup of its Daytona v0 sandbox and keeps the settings that Daytona v2 supports. Importing copies a sandbox and does not move it: the original keeps working on Daytona v0. Every migration request is scoped to the organization's default project, and a request made with an API key for any other project is refused. API keys created in the default project can also be copied to Daytona v0; see [Daytona v0 key sync](/docs/api-keys). An organization shared with Daytona v0 also shares its [single sign-on](/docs/sso) configuration. | **Resource** | **Migration** | | ------------------------ | --------------------------------------------------------------------------------------------------------------------- | | **API keys** | Synced into the default project. A key synced from Daytona v0 works on both platforms unchanged. | | **Container registries** | Synced into the default project. | | **Snapshots** | Synced into the default project as named images in an older format. Each image converts on first use or on request. | | **Sandboxes** | Not synced. Archived container sandboxes are imported one at a time as persistent sandboxes. | ## Get the migration summary [#get-the-migration-summary] Get a summary of what the migration brought into the organization's default project. The summary reports whether the organization was migrated from Daytona v0 and counts the API keys, container registries, and images from Daytona v0 snapshots in the default project. Images are counted separately by whether they are converted to the current format. The summary also counts the Daytona v0 sandboxes imported so far. ```bash curl 'https://api.daytona.com/migration/v0/summary' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ```json { "from_v0": true, "api_keys": 3, "registries": 1, "images_to_convert": 4, "images_converted": 2, "sandboxes_imported": 5, "personal": false } ``` The response has the following fields: | **Field** | **Description** | | -------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | `from_v0` | `true` when the organization was migrated from Daytona v0, personal organizations included. | | `api_keys` | The number of live API keys in the default project, both synced from Daytona v0 and created on Daytona v2. | | `registries` | The number of container registries in the default project. | | `images_to_convert` | The number of images from Daytona v0 snapshots still in the older format: not converted yet, converting, or failed to convert. | | `images_converted` | The number of images from Daytona v0 snapshots in the current format. | | `sandboxes_imported` | The number of Daytona v0 sandboxes imported into the default project. A sandbox imported more than once counts once. | | `personal` | `true` when the organization is a personal organization. | ## List Daytona v0 sandboxes [#list-daytona-v0-sandboxes] List the organization's Daytona v0 sandboxes, one page at a time. Daytona reads the list from Daytona v0 on each request, so it reflects the current state of each sandbox. Each entry reports whether the sandbox can be imported now and, when it cannot, why. A sandbox that was already imported carries the ID of the sandbox the import created. 1. Go to [Daytona Sandboxes ↗](https://app.daytona.com/dashboard/sandboxes?version=v0) 2. Select the default project 3. Select **Daytona v0** in the version toggle The version toggle appears only for an organization migrated from Daytona v0. ```bash curl 'https://api.daytona.com/migration/v0/sandboxes?limit=100' \ --header 'Authorization: Bearer YOUR_API_KEY' # Pass next_cursor from the previous page to get the next one curl 'https://api.daytona.com/migration/v0/sandboxes?limit=100&cursor={nextCursor}' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` | **Parameter** | **Type** | **Description** | | ------------- | --------- | ------------------------------------------------------------------------------------- | | `limit` | integer | Sets the page size, from `1` to `200`. The default is `100`. | | `cursor` | string | Resumes the list after the previous page. Pass the `next_cursor` of that page as-is. | ```json { "sandboxes": [ { "v0_id": "0b6c5c43-7a52-4c1f-9a42-3f0c3d7f2a11", "name": "data-pipeline", "status": "archived", "class": "container", "importable": true, "last_backup_at": "2026-10-14T09:21:07Z", "labels": { "team": "data" }, "cpu": 2, "memory_gib": 4, "disk_gib": 10 } ], "next_cursor": null } ``` The response has the following fields: | **Field** | **Description** | | --------------------- | --------------------------------------------------------------------------------------------------- | | `sandboxes` | The Daytona v0 sandboxes in this page. | | `next_cursor` | The token for the next page, or `null` on the last page. | | `v0_id` | The sandbox ID on Daytona v0. The import takes this ID. | | `name` | The sandbox name. | | `status` | The sandbox state on Daytona v0, for example `archived`. | | `class` | The sandbox class on Daytona v0, for example `container`. | | `importable` | `true` when the sandbox can be imported now. | | `reason` | Why the sandbox cannot be imported. Present only when `importable` is `false`. | | `last_backup_at` | When Daytona v0 last completed a backup of the sandbox, or `null`. | | `labels` | The sandbox labels on Daytona v0. | | `cpu` | The CPU cores on Daytona v0. | | `memory_gib` | The memory on Daytona v0, in GiB. | | `disk_gib` | The disk size on Daytona v0, in GiB. | | `imported_sandbox_id` | The ID of the sandbox an earlier import created. Present only while that sandbox exists. | A sandbox cannot be imported for reasons such as the following. The API can return other reasons, so handle a reason that is not listed here. | **Value** | **Description** | | ----------------------------- | --------------------------------------------------------------- | | `not_container` | The sandbox is not a container sandbox. | | `not_archived` | The sandbox is not archived on Daytona v0. | | `backup_not_completed` | Daytona v0 has not completed a backup of the sandbox. | | `backup_registry_unavailable` | Daytona v0 cannot reach the registry that holds the backup. | | `gpu_not_supported` | The sandbox is a GPU sandbox, which cannot be imported. | - The request requires the `read:sandboxes` permission. - A page can hold fewer entries than `limit` without being the last page; only a `null` `next_cursor` ends the list. ## Import a Daytona v0 sandbox [#import-a-daytona-v0-sandbox] Import an archived Daytona v0 sandbox as a new persistent sandbox in the default project. The import registers the sandbox's last Daytona v0 backup as an image, converts the image to the current format, and creates the sandbox from it in the default project's region. The new sandbox waits in the queued state until the conversion finishes. The original Daytona v0 sandbox keeps working and is labeled with the ID of the sandbox the import created. Importing the same sandbox again returns the existing import instead of creating another sandbox, unless you force a new import. When the sandbox an earlier import created was deleted or failed, the next import creates a new one. 1. Go to [Daytona Sandboxes ↗](https://app.daytona.com/dashboard/sandboxes?version=v0) and select **Daytona v0** in the version toggle 2. Click on the row of an importable sandbox 3. Click to confirm ```bash curl 'https://api.daytona.com/migration/v0/sandboxes/{v0Id}/import' \ --request POST \ --header 'Authorization: Bearer YOUR_API_KEY' # force creates another sandbox even when a live import exists curl 'https://api.daytona.com/migration/v0/sandboxes/{v0Id}/import' \ --request POST \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "force": true }' ``` | **Field** | **Type** | **Description** | | --------- | --------- | -------------------------------------------------------------------------------------------- | | `force` | boolean | Creates another sandbox even when a live import of the sandbox exists. The default is `false`. | ```json { "sandbox_id": "sbx_4kQm9TzVb2LxWp7R", "image_id": "img_7fJk2mQpXv9dLc3RtY", "status": "queued", "existing": false, "v0_labeled": true, "warnings": [ "env vars not carried (sandbox secrets on Daytona v0; set them on the imported sandbox): OPENAI_API_KEY" ], "secret_env_vars": ["OPENAI_API_KEY"] } ``` The response has the following fields: | **Field** | **Description** | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `sandbox_id` | The ID of the persistent sandbox the import created or returned. | | `image_id` | The ID of the image registered from the Daytona v0 backup. | | `status` | The sandbox status. A new import is `queued` while its image converts. | | `existing` | `true` when the call returned an earlier import instead of creating a sandbox. | | `v0_labeled` | `true` when Daytona v0 confirmed the label on the original sandbox. `false` means the label could not be set; repeating the call retries it. | | `warnings` | The settings and values that could not be imported. | | `secret_env_vars` | The names of environment variables backed by a Daytona v0 sandbox secret. The imported sandbox starts without them. Empty for an existing import. | - The request requires the `write:sandboxes` permission and an API key for the default project. - The Daytona v0 sandbox must be an archived container sandbox with a completed backup. The import carries the following settings from the Daytona v0 sandbox and reports every dropped setting in the warnings: | **Setting** | **Import behavior** | | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Name** | Kept when it is a valid sandbox name; otherwise the sandbox gets a generated name. | | **Environment variables** | Kept, except reserved or invalid names, values over 64 KiB, and values that contain a NUL byte. Variables backed by a Daytona v0 sandbox secret are not carried. | | **Labels** | Kept, except labels Daytona v2 refuses and labels beyond the per-sandbox label limit. The `daytona.io/migrated-to` label is not copied. | | **CPU, memory, and disk** | Kept, rounded up to whole units. Values above the per-sandbox limit are lowered to it. | | **OS user** | Kept when it is a valid user name; otherwise the sandbox runs as the image's default user. | | **Auto-stop interval** | Becomes an idle timeout that stops the sandbox. An auto-stop interval of `0` disables the idle timeout. | | **Network restrictions** | Become a [network policy](/docs/network-limits) that blocks all egress except the allowed CIDRs and domains. Refused entries and entries over the limit are dropped. | | **Auto-archive and auto-delete intervals** | Not carried. Daytona v2 has no archive state and no delete-after-stop timer. | | **Volumes, sandbox ID, preview URLs, memory state** | Not carried. | ## Permissions [#permissions] Migration uses the sandbox permissions of the default project, which you can grant to an [organization role](/docs/organizations#roles) or an [API key](/docs/api-keys). An import requires an API key for the default project. | **Permission** | **Grants** | | --------------------- | ------------------------------------------------------- | | **`read:sandboxes`** | Get the migration summary and list Daytona v0 sandboxes | | **`write:sandboxes`** | Import Daytona v0 sandboxes | # Tools (/docs/tools) ## Toolbox [#toolbox] ## Access [#access] # Architecture (/docs/architecture) Daytona platform is organized into multiple plane components, each serving a specific purpose: - [Interface plane](#interface-plane) provides client interfaces for interacting with Daytona - [Control plane](#control-plane) accepts requests, stores state, and hands work to runners - [Compute plane](#compute-plane) runs sandboxes and serves sandbox traffic ### Interface plane [#interface-plane] The interface plane provides client interfaces for users and agents to interact with Daytona. The following components are part of the interface plane and available to all users and agents: - **SDK**: [Python](/docs/python-sdk), [TypeScript](/docs/typescript-sdk). Each SDK sends requests to the Daytona API endpoint, which routes each request to the [region](/docs/regions) that owns the sandbox. Lifecycle and resource operations (sandboxes, images, snapshots, volumes) go to that region's [API](#api); data-plane calls into a running sandbox (file system, process execution, Git, PTY) go directly to that region's [proxy](#proxy) - [Dashboard](https://app.daytona.com/dashboard/): web UI for sandboxes, images, snapshots, volumes, projects, and organization settings, with a terminal, file browser, desktop, SSH panel, and [playground](/docs/playground) - [SSH](/docs/ssh-access): shell, `scp`/`sftp`, and port forwarding into sandboxes through the SSH gateway - [Preview URLs](/docs/preview): HTTP and WebSocket access to services listening inside a sandbox ### Control plane [#control-plane] The control plane is the central coordination layer of the Daytona platform. It receives all client requests, authenticates them, records the desired state, and publishes jobs that [runners](#sandbox-runners) pick up. Runners report progress back as events, so no sandbox operation requires a synchronous round trip between the API and a runner. The control plane includes the following components: - [API](#api) handles authentication, tenancy, sandboxes, images, snapshots, volumes, and secrets - [Database and job queue](#database-and-job-queue) persist platform state and carry work to runners Every [region](/docs/regions) runs its own control plane, job queue, proxy, and runner fleet. The home region also hosts the management plane: organizations, users, projects, API keys, and billing. #### API [#api] The API is a Rust-based RESTful service that serves as the primary entry point for all platform operations. Creating a sandbox writes a row, publishes a job to the region's queue, and returns; everything that follows happens on a runner and is reported back as events that the API applies to its state. The API also runs the maintenance loops that enforce automated sandbox lifecycle policies: the [timeout and idle timeout](/docs/linux-sandboxes#timeouts) of each sandbox. The API authenticates the following credentials: - **Project API keys** carry an explicit set of [permissions](/docs/api-keys) and an optional expiry, and are the credential used by SDKs, the proxy, and the SSH gateway - **Organization API keys** are managed by organization admins and limited to their endpoints - **Sandbox tokens** are issued to each sandbox so it can delete itself - **OIDC tokens** authenticate dashboard sign-ins through the OpenID Connect provider Access control follows [organization](/docs/organizations) and [project](/docs/projects) boundaries: every sandbox, image, snapshot, volume, and secret belongs to a project, and project API keys see only their project. To interact with sandboxes from the API, see the [API](/docs/api/daytona) and [Toolbox API](/docs/api/toolbox) references. #### Database and job queue [#database-and-job-queue] - **PostgreSQL** is the primary persistent store for organizations, projects, sandboxes, images, snapshots, volumes, and secrets. Each region keeps its own database; tenancy data is replicated read-only from the home region so API keys authenticate locally in every region - **NATS JetStream** carries sandbox jobs from the API to runners (create and delete; for persistent macOS sandboxes also stop, start, pause, resume and fork) and streams runner events back to the API and proxy. Runners pull jobs only from their region's queue - **Redis** is optional and used for authentication rate limiting and signed preview URL state [Secrets](/docs/secrets) are encrypted at rest with AES-256-GCM and sealed to each runner's key for delivery. Sandboxes see only placeholders; the host substitutes real values only in outbound HTTPS requests to each secret's allowed domains. Responses are not rewritten, so an allowed destination that echoes a value returns it into the sandbox. ### Compute plane [#compute-plane] The compute plane is where sandboxes run and their traffic is served. Sandboxes run on [runners](#sandbox-runners), compute nodes that host multiple sandboxes with dedicated resources and scale horizontally across shared or dedicated [regions](/docs/regions). It includes the following components: - [Sandbox runners](#sandbox-runners) build images and boot sandboxes as virtual machines - [Sandbox daemon](#sandbox-daemon) provides code execution and environment access inside each sandbox - [Proxy](#proxy) routes Toolbox, SSH, preview, and VNC traffic straight to sandboxes - [Image store](#image-store) holds converted image layers shared by all runners in a region - [Sandbox storage](#sandbox-storage) holds sandbox disks and VM snapshots - [Volumes](#volumes) provide persistent storage shared across sandboxes #### Sandbox runners [#sandbox-runners] Runners are the compute nodes of Daytona's compute plane. Each runner is a Go agent that pulls jobs from its region's queue and executes sandbox operations: building or pulling [images](/docs/images), creating, resizing, and deleting sandboxes, stopping, starting, pausing, resuming, and forking persistent macOS sandboxes, and capturing [snapshots](/docs/snapshots). Runners accept no inbound connections from the control plane; they report state changes as events and stream sandbox usage to the metering pipeline that feeds [billing](/docs/billing). Each sandbox runs as a hardware-isolated virtual machine with its own kernel and dedicated vCPU, RAM, and disk. Linux sandboxes run as Firecracker microVMs, Windows sandboxes run on Cloud Hypervisor, and macOS sandboxes run on Apple's Virtualization framework on dedicated Apple silicon Macs ([hardware virtualization](/docs/sandboxes#hardware-virtualization)). Runners boot most Linux sandboxes by resuming a pre-built memory snapshot of the image rather than cold-booting, which is what makes sub-second creation possible. Traffic between sandboxes is blocked on the host, and per-sandbox [egress policies](/docs/network-limits) are enforced there as well. See [isolation](/docs/isolation) for details. #### Sandbox daemon [#sandbox-daemon] The sandbox daemon is a Rust agent that runs as the init process inside each sandbox. It is injected by the runner as a read-only system layer, so it does not need to be part of your image. It exposes the [Toolbox API](/docs/api/toolbox), providing direct access to the sandbox environment: [file system](/docs/file-system-operations) and [Git](/docs/git-operations) operations, [process](/docs/process-execution) and [code execution](/docs/code-execution), [PTY](/docs/pty) and [log streaming](/docs/log-streaming), [language servers](/docs/language-server-protocol), and [computer use](/docs/computer-use). It also runs the SSH server that the [SSH gateway](/docs/ssh-access) connects to. #### Proxy [#proxy] The proxy is a stateless service serving the sandbox data plane. It authenticates each request, resolves the target sandbox to its address on the runner overlay network, and forwards the connection directly to the [sandbox daemon](#sandbox-daemon) or a port inside the sandbox, bypassing the API. It supports HTTP, WebSocket, and server-sent events, and exposes these endpoints: | **Endpoint** | **Routing and authentication** | | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Toolbox** | Path-based routing at `/toolbox/{sandboxId}/...`, with a project API key. | | **Preview** | Host-based routing at `{port}-{sandboxId}.{preview-domain}`, authenticated with an API key, a preview token, or a signed URL unless the endpoint is [public](/docs/preview). | | **[SSH gateway](/docs/ssh-access)** | Port `2222`, authenticated with `#` as the username, where the credential is a project API key or a sandbox token that allows SSH. For macOS sandboxes, use a sandbox token ([macOS SSH](/docs/macos-sandboxes#ssh)). | | **VNC** | WebSocket bridge to the sandbox desktop used by the dashboard and [VNC clients](/docs/vnc-access). | Authenticated Toolbox, preview, and SSH traffic also resets the [idle timeout](/docs/linux-sandboxes#idle-timeout). #### Image store [#image-store] Daytona does not run an internal image registry. When an [image](/docs/images) is pulled from a [container registry](#container-registry) or built from a Dockerfile, the runner converts each layer into a read-only, content-addressed filesystem image and stores it in a per-region shared store, together with a manifest that records the layer stack, entrypoint, environment, and working directory. Layers are keyed by content hash, so a layer shared by many images is converted and stored once per region, and sandboxes attach these layers read-only at boot without copying them. An image reaches another region automatically: that region fetches it from the global artifact store the first time a sandbox there uses it. #### Sandbox storage [#sandbox-storage] Sandbox writes go to a layer above the read-only image layers: - **Ephemeral sandboxes** write to the runner's NVMe scratch disk, discarded on delete - **Persistent macOS sandboxes** keep their disk on their Mac across stop and start. When the Mac reservation ends, the disk is exported as an image before the Mac is erased ([macOS sandboxes](/docs/macos-sandboxes#when-a-reservation-ends)) - **[VM snapshots](/docs/snapshots)** capture a sandbox's disk, and memory in full snapshots, for restore #### Volumes [#volumes] [Volumes](/docs/volumes) provide persistent storage that can be shared across sandboxes. Disk volume data lives in S3-compatible object storage as content-addressed blobs; a mounted disk volume is materialized inside the sandbox as a read-write directory, and changes are committed back periodically. A bucket volume mounts an S3 bucket directly. Multiple sandboxes can mount the same volume simultaneously, allowing data to be shared across sandboxes and persist independently of the sandbox lifecycle. ### Container registry [#container-registry] Container registries serve as the source for sandbox base images. When you pull an [image](/docs/images), a runner fetches it from the external registry and converts it into the [image store](#image-store); for Dockerfile builds, parent images in FROM directives are pulled the same way. Credentials for private registries are stored per project as [registries](/docs/registries). Daytona supports any OCI-compatible registry: - [Docker Hub](/docs/registries#docker-hub) - [Google Artifact Registry](/docs/registries#google-artifact-registry) - [GitHub Container Registry (GHCR)](/docs/registries#github-container-registry) - [Amazon ECR](/docs/registries#amazon-ecr) - [Private registries](/docs/registries#use-private-registry-images): any OCI distribution registry that supports basic authentication # Organizations (/docs/organizations) Daytona provides organizations as a way to group resources and enable collaboration. Users can work individually in their personal organization or together in a collaborative organization. Manage your organizations in the [Daytona Dashboard ↗](https://app.daytona.com/dashboard) or through the [API](/docs/api/daytona). ## Personal vs Collaborative [#personal-vs-collaborative] Every Daytona user starts with a personal organization for solo use and experimentation. Collaborative organizations are created manually for teams, with shared access and controls. | **Feature** | **Personal organization** | **Collaborative organization** | | ------------------ | -------------------------------- | ---------------------------------------------- | | **Creation** | Automatic on signup | Manually by a user | | **Members** | Single user only | Multiple users (invite-based) | | **Access Control** | No roles or permissions | Roles with fixed permission sets | | **Billing** | Tied to individual user | Shared across team members | | **Use Case** | Personal testing, small projects | Company/team development and production | | **Quota Scope** | Per user | Shared across all members | | **Deletable** | No | Yes (by admins) | Switch between personal and collaborative organizations with the dropdown in the [Daytona Dashboard ↗](https://app.daytona.com/dashboard) sidebar. Each organization has its own sandboxes, API keys, and resource quotas. ## Create organization [#create-organization] Create organizations in the [Daytona Dashboard ↗](https://app.daytona.com/dashboard/) or with the [API](/docs/api/daytona). 1. Go to [Daytona Dashboard ↗](https://app.daytona.com/dashboard/) 2. Expand the dropdown at the top-left corner of the sidebar to view your organizations 3. Click 4. Enter the organization name 5. Select a [region](/docs/regions) 6. Click ```bash daytona org create 'My Organization' ``` ```bash curl 'https://api.daytona.com/orgs' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' \ --data '{ "name": "My Organization" }' ``` | **Field** | **Type** | **Description** | | --------- | -------- | --------------------------------------------------------------------------------------------------------------------------- | | `name` | string | Sets the organization name. The name is trimmed and must be 1 to 100 characters with no control characters. Other values return `400`. This field is required. | ## Operations [#operations] ### List organizations [#list-organizations] List all organizations the authenticated user belongs to. ```bash daytona org list ``` ```bash curl 'https://api.daytona.com/orgs' \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' ``` ### Select organization [#select-organization] Select the organization that following CLI commands run against. The CLI also restores the [project](/docs/projects#select-project) you last used in that organization, or its default project. Pass an ID or an unambiguous name; with no argument, the CLI shows a picker at a terminal. ```bash daytona org use ORGANIZATION_ID ``` ### Get by ID [#get-by-id] Get an organization by ID. ```bash daytona org get ORGANIZATION_ID ``` ```bash curl 'https://api.daytona.com/orgs/ORGANIZATION_ID' \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' ``` ### Current user [#current-user] ```bash # The signed-in user, the credential in use, and the selected organization and project daytona whoami ``` ```bash # The calling user: id, email, name curl 'https://api.daytona.com/me' \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' ``` ### Current organization API key [#current-organization-api-key] Get the organization API key that authenticates the request, with the organization permissions it holds now. The response never contains the token. ```bash curl 'https://api.daytona.com/orgs/ORGANIZATION_ID/api-keys/current' \ --header 'Authorization: Bearer YOUR_ORG_API_KEY' ``` ```json { "id": "KEY_ID", "org_id": "ORGANIZATION_ID", "name": "my-org-key", "key_prefix": "dtno_...", "org_permissions": ["read:audit"], "created_at": "2026-09-10T12:00:00Z", "expires_at": null, "last_used_at": "2026-09-11T08:30:00Z", "revoked_at": null } ``` - The request requires an organization API key. ### Rename organization [#rename-organization] Rename an organization. The new name follows the same rules as on create: it is trimmed, and must be 1 to 100 characters with no control characters. ```bash daytona org update ORGANIZATION_ID --name 'New Organization Name' ``` ```bash curl 'https://api.daytona.com/orgs/ORGANIZATION_ID' \ --request PATCH \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' \ --data '{ "name": "New Organization Name" }' ``` ### Leave organization [#leave-organization] Leave an organization. 1. Go to [Daytona Dashboard ↗](https://app.daytona.com/dashboard/) 2. Expand the dropdown at the top-left corner of the sidebar to view your organizations 3. Select the organization you want to leave 4. Click in the sidebar 5. Click 6. Confirm by clicking ```bash daytona org leave ORGANIZATION_ID ``` - The request requires the `read:organization` permission. - `daytona org leave` asks for confirmation at a terminal and requires `--yes` otherwise. ```bash # Leaving is a self-removal: USER_ID is the id returned by GET /me curl 'https://api.daytona.com/orgs/ORGANIZATION_ID/members/USER_ID' \ --request DELETE \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' ``` ### Delete organization [#delete-organization] Delete an organization. 1. Go to [Daytona Dashboard ↗](https://app.daytona.com/dashboard/) 2. Expand the dropdown at the top-left corner of the sidebar to view your organizations 3. Select the organization you want to delete 4. Click in the sidebar 5. Click 6. Confirm the deletion by typing the organization name and clicking ```bash daytona org delete ORGANIZATION_ID ``` - The request requires the `delete:organization` permission. - The organization must not be a personal organization. - The organization must have no sandboxes, volumes, images, snapshots, or functions, and no live Mac reservation. - `daytona org delete` asks for confirmation at a terminal and requires `--yes` otherwise. ```bash curl 'https://api.daytona.com/orgs/ORGANIZATION_ID' \ --request DELETE \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' ``` - The request requires the `delete:organization` permission. - The organization must not be a personal organization. - The organization must have no sandboxes, volumes, images, snapshots, or functions, and no live Mac reservation. ## Roles [#roles] Each member of an organization holds one or more roles. A role is a set of permissions, and a member's permissions are the union of the permissions of all roles they hold. Daytona provides the built-in roles below, and an organization on the Enterprise plan can also define [custom roles](#create-custom-role) from its own choice of permissions. The admin role is protected: the organization must always keep at least one admin, and only an admin can grant or remove it. An invitation that names no roles grants the developer role. | **Role** | **Description** | | ------------------------------ | ---------------------------------------------------------------------------------------------------- | | **`admin`** | Full control of the organization, its members, and everything in it | | **`maintainer`** | Full control of everything inside the organization's projects, with no authority over the organization itself | | **`developer`** | Run and manage sandboxes, invoke functions, and view everything a sandbox can use | | **`read-only`** | View every project resource, and change none of them | | **`member`** | Sign in and see the organization, with no access to any resource | | **`auditor`** | Read the organization's [audit log](/docs/audit-logs), without the ability to turn it off | | **`billing`** | See what the organization spends and manage how it pays | | **`spending-viewer`** | See what the organization spends, and nothing about how it pays | | **`budget-manager`** | Set and remove monthly budgets on the projects the member can access | | **`sso-admin`** | Configure [single sign-on](/docs/sso) for the organization | | **`infrastructure-admin`** | Read-only access to the organization. A reserved role kept so existing assignments continue to work | | **`sandboxes-manager`** | Create, change, and delete sandboxes | | **`snapshots-manager`** | Create, change, and delete snapshots and images | | **`volumes-manager`** | Create, change, and delete volumes | | **`registries-manager`** | Create, change, and delete private container registries | | **`secrets-manager`** | Create, change, and delete project secrets | | **`functions-manager`** | Deploy, invoke, change, and delete serverless functions | ### List roles [#list-roles] List all roles in an organization: the built-in roles, then the organization's custom roles by name. ```bash # The built-in roles and the permissions each role grants daytona role list ``` ```bash # The built-in roles, then the organization's custom roles curl 'https://api.daytona.com/orgs/ORGANIZATION_ID/roles' \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' # The built-in roles only curl 'https://api.daytona.com/roles' \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' ``` The organization's list has the following fields: | **Field** | **Description** | | --------- | --------------- | | `roles` | The built-in roles, then the custom roles. | | `max_custom_roles` | The most custom roles the organization can define. | Each role has the following fields: | **Field** | **Description** | | --------- | --------------- | | `id` | Identifies the role: the identifier of a built-in role, such as `developer`, or the UUID of a custom role. | | `name` | The display name. | | `description` | The purpose of the role. | | `kind` | The kind is `built_in` or `custom`. | | `project_permissions` | The project permissions the role grants. | | `organization_permissions` | The organization permissions the role grants. | | `permissions` | Every permission the role grants: the project permissions, then the organization permissions. | ### Get role [#get-role] Get one role of an organization, built-in or custom, with the permissions it grants. ```bash # ROLE_ID is the identifier of a built-in role, such as developer, or the UUID of a custom role curl 'https://api.daytona.com/orgs/ORGANIZATION_ID/roles/ROLE_ID' \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' ``` The response has the fields of a role in [list roles](#list-roles). ### Create custom role [#create-custom-role] Define a role from your own choice of permissions. A custom role can grant only permissions you hold. Every role includes the organization read permission, and a role that grants any project permission also includes the permissions to read projects and to create project API keys. Custom roles are assigned like built-in roles, to members, service accounts, and invitations. ```bash curl 'https://api.daytona.com/orgs/ORGANIZATION_ID/roles' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' \ --data '{ "name": "Sandbox operator", "description": "Runs and manages sandboxes", "project_permissions": ["read:sandboxes", "write:sandboxes"], "organization_permissions": ["read:organization", "read:projects", "write:project_api_keys"] }' ``` | **Field** | **Type** | **Description** | | --------- | -------- | --------------- | | `name` | string | Sets the role name, unique in the organization ignoring case and different from the name of every built-in role. Leading and trailing whitespace is removed, and runs of whitespace inside become one space. The result must be from `1` to `64` characters. This field is required. | | `description` | string | Sets the purpose of the role, at most `256` characters. | | `project_permissions` | string\[\] | Sets the project permissions the role grants. This field is required. | | `organization_permissions` | string\[\] | Sets the organization permissions the role grants. It must include `read:organization`, and also `read:projects` and `write:project_api_keys` when `project_permissions` is not empty. This field is required. | The response has the fields of a role in [list roles](#list-roles). - The request requires the `write:roles` permission and the Enterprise [plan](/docs/billing#get-the-plan). - The role can grant only permissions you hold. - [List permissions](#list-permissions) returns the permission identifiers the role can grant. - The organization can define at most `max_custom_roles` custom roles, as [list roles](#list-roles) returns it. - Assign the role by its `id` in the `roles` of an invitation, a member, or a service account. ### Update custom role [#update-custom-role] Change the name, description, or permissions of a custom role. A permission list in the request replaces the role's list. Narrowing a role revokes the API keys of its holders that exceed their new permissions. A preview reports what the same update would change without applying it. Built-in roles cannot be changed. ```bash # Report what the update would change, without applying it curl 'https://api.daytona.com/orgs/ORGANIZATION_ID/roles/ROLE_ID/update-preview' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' \ --data '{ "project_permissions": ["read:sandboxes"] }' # Apply the update curl 'https://api.daytona.com/orgs/ORGANIZATION_ID/roles/ROLE_ID' \ --request PATCH \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' \ --data '{ "project_permissions": ["read:sandboxes"] }' ``` | **Field** | **Type** | **Description** | | --------- | -------- | --------------- | | `name` | string | Sets the new role name. Whitespace is normalized as on create, and the result must be from `1` to `64` characters. | | `description` | string | Sets the new purpose of the role, at most `256` characters. | | `project_permissions` | string\[\] | Replaces the project permissions the role grants. | | `organization_permissions` | string\[\] | Replaces the organization permissions the role grants. | The preview response has the following fields: | **Field** | **Description** | | --------- | --------------- | | `revoked_api_keys` | The number of API keys the update would revoke. | | `affected_members` | The number of members who hold the role. | | `affected_service_accounts` | The number of active service accounts that hold the role. | | `pending_invitations` | The number of pending invitations that grant the role. | The update response has the following fields: | **Field** | **Description** | | --------- | --------------- | | `role` | The updated role, with the fields of a role in [list roles](#list-roles). | | `revoked_api_keys` | The number of API keys the update revoked. | - The requests require the `write:roles` permission and the Enterprise [plan](/docs/billing#get-the-plan). An update or preview that only removes permissions does not require the Enterprise plan. - The role's current and new permissions must be within the permissions you hold, and you must be able to assign roles to every member and service account that holds the role. ### Delete custom role [#delete-custom-role] Delete a custom role. A role that a member, a service account, or a pending invitation holds cannot be deleted; remove it from them first. Built-in roles cannot be deleted. ```bash curl 'https://api.daytona.com/orgs/ORGANIZATION_ID/roles/ROLE_ID' \ --request DELETE \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' ``` ### List permissions [#list-permissions] List the permissions that roles and API keys grant. Each permission has an identifier, a display name, and a display category. Project permissions apply to the resources inside a project, and organization permissions apply to the organization itself. ```bash # Every permission; scope=project or scope=organization restricts the list to one scope curl 'https://api.daytona.com/permissions?scope=project' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` | **Parameter** | **Type** | **Description** | | ------------- | --------- | --------------------------------------------------------------------------------------------------- | | `scope` | string | Restricts the list to `project` or `organization` permissions. Any other value returns `400`. Omit it to list both. | ## Members [#members] Daytona provides methods to manage members in an organization. ### List members [#list-members] List all members in an organization. ```bash daytona member list --org ORGANIZATION_ID ``` ```bash curl 'https://api.daytona.com/orgs/ORGANIZATION_ID/members' \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' ``` ### Invite members [#invite-members] Invite a new user to an organization. 1. Go to [Daytona Dashboard ↗](https://app.daytona.com/dashboard/members) 2. Click 3. Enter the email address of the user you want to invite 4. Select one or more [roles](#roles) for the new user under **Roles** ```bash daytona invite create mail@example.com --org ORGANIZATION_ID --role developer ``` | **Flag** | **Type** | **Description** | | -------- | -------- | ------------------------------------- | | `--role` | string | Sets the roles, as a comma-separated list of role slugs. | - The request requires the `write:members` permission. - When the deployment sends no email, `daytona invite create` prints the invitation link to share with the invitee. ```bash # roles defaults to ["developer"] when omitted curl 'https://api.daytona.com/orgs/ORGANIZATION_ID/invitations' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' \ --data '{ "email": "mail@example.com", "roles": ["developer"] }' ``` The response has the following fields: | **Field** | **Description** | | ------------ | -------------------------------------------------------------------------------------------------------- | | `id` | The invitation ID. | | `roles` | The roles the invitee receives on acceptance. | | `status` | The invitation status. | | `expires_at` | When the invitation expires. | | `accept_url` | The invitation link to share with the invitee when the deployment sends no email, or `null` when the invitation was sent by email. | ### Remove members [#remove-members] Remove a user from an organization. 1. Go to [Daytona Dashboard ↗](https://app.daytona.com/dashboard/members) 2. Click next to the user you want to remove 3. Confirm the removal by clicking ```bash # Preview what the member loses before removing them daytona member remove USER_ID --org ORGANIZATION_ID --dry-run daytona member remove USER_ID --org ORGANIZATION_ID ``` ```bash # Preview what the member loses before removing them curl 'https://api.daytona.com/orgs/ORGANIZATION_ID/members/USER_ID/removal-preview' \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' curl 'https://api.daytona.com/orgs/ORGANIZATION_ID/members/USER_ID' \ --request DELETE \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' ``` The removal preview response has the following fields: | **Field** | **Description** | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------- | | `revoked_api_keys` | Holds the count of project and organization API keys that the removal revokes. | | `revoked_preview_grants` | Holds the count of signed preview grants that the removal deletes. The value is `null` when the count is unknown, not `0`. | ### Update access [#update-access] Update the access of a member in an organization. 1. Go to [Daytona Dashboard ↗](https://app.daytona.com/dashboard/members) 2. Click the three-dot menu on the member row 3. Click 4. Select the member's [roles](#roles) and click ```bash # Replace the member's role set daytona member update USER_ID --org ORGANIZATION_ID --role maintainer,billing # Rehearse the change without applying it daytona member update USER_ID --org ORGANIZATION_ID --role read-only --dry-run ``` ```bash # Replace the member's role set curl 'https://api.daytona.com/orgs/ORGANIZATION_ID/members/USER_ID' \ --request PATCH \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' \ --data '{ "roles": ["maintainer", "billing"] }' # Rehearse the change without applying it: { "revoked_api_keys": ..., "revoked_preview_grants": ... } curl 'https://api.daytona.com/orgs/ORGANIZATION_ID/members/USER_ID/update-preview' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' \ --data '{ "roles": ["read-only"] }' ``` | **Field** | **Type** | **Description** | | --------- | ---------- | ---------------------------------------------------- | | `roles` | string\[\] | Replaces the member's whole role set. This field is required. | - The requests require the `write:members` permission. - You cannot change your own roles. - You can change only a member whose current and requested permissions you hold. - Only an admin can grant or remove the admin role. ## Invitations [#invitations] View an organization invitation from the link or token in the invitation email. 1. Open the link in the invitation email; it opens [Daytona Dashboard ↗](https://app.daytona.com/dashboard/user/invitations) 2. Review the organization, inviter, roles, and expiry of the invitation ```bash # Show the invitation behind the dtni_ token or the link from the invitation email daytona invite get INVITATION_TOKEN ``` ```bash # Show the invitation behind the dtni_ token from the invitation email curl 'https://api.daytona.com/invitations/lookup' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' \ --data '{ "token": "INVITATION_TOKEN" }' ``` ### Accept invitation [#accept-invitation] Accept a pending organization invitation. 1. Open the link in the invitation email; it opens [Daytona Dashboard ↗](https://app.daytona.com/dashboard/user/invitations) 2. Sign in if prompted 3. Review the organization, inviter, roles, and expiry of the invitation 4. Click ```bash daytona invite accept INVITATION_TOKEN ``` ```bash curl 'https://api.daytona.com/invitations/accept' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' \ --data '{ "token": "INVITATION_TOKEN" }' ``` - The token is single-use. Once a user accepts an invitation to join an organization, they get access to the organization's resource quotas and can create an [API key](/docs/api-keys) and sandboxes. ### Decline invitation [#decline-invitation] Decline a pending organization invitation. 1. Open the link in the invitation email; it opens [Daytona Dashboard ↗](https://app.daytona.com/dashboard/user/invitations) 2. Sign in if prompted 3. Review the organization, inviter, roles, and expiry of the invitation 4. Click 5. Confirm by clicking ```bash daytona invite decline INVITATION_TOKEN ``` ```bash curl 'https://api.daytona.com/invitations/decline' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' \ --data '{ "token": "INVITATION_TOKEN" }' ``` ### List pending [#list-pending] List pending invitations for an organization. ```bash daytona invite list --org ORGANIZATION_ID ``` ```bash curl 'https://api.daytona.com/orgs/ORGANIZATION_ID/invitations' \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' ``` - The request requires the `read:members` permission. - The list also contains declined and expired invitations; use `declined_at` and `expires_at` to tell them apart from pending ones. ### Cancel invitation [#cancel-invitation] Cancel an invitation for an organization. 1. Go to [Daytona Dashboard ↗](https://app.daytona.com/dashboard/members) 2. Scroll to the **Invitations** table 3. Click the three-dot menu on the invitation row 4. Click 5. Confirm by clicking ```bash daytona invite revoke INVITATION_ID --org ORGANIZATION_ID ``` ```bash curl 'https://api.daytona.com/orgs/ORGANIZATION_ID/invitations/INVITATION_ID' \ --request DELETE \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' ``` ## Limits [#limits] Get the effective [organization limits](/docs/limits#organization-limits) and the current usage they are checked against. Each limit reports its effective cap and the usage counted against it. The member limit also counts the pending invitations that reserve a seat. A read with an API key returns the limits of the API key's organization and leaves out the member limit. ```python from daytona import Daytona daytona = Daytona() limits = daytona.v2.get_limits() concurrent = limits.sandboxes.concurrent print(f"Concurrent sandboxes: {concurrent.usage} of {concurrent.limit}") ``` - The request requires the `read:limits` permission with an API key, or the `read:organization` permission when signed in. - With `jwt_token` authentication, pass `organization_id`. ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const limits = await daytona.v2.getLimits() const concurrent = limits.sandboxes.concurrent console.log(`Concurrent sandboxes: ${concurrent.usage} of ${concurrent.limit}`) ``` - The request requires the `read:limits` permission with an API key, or the `read:organization` permission when signed in. - With `jwtToken` authentication, pass `organizationId`. ```bash # The argument is optional; omit it to use the selected organization daytona org limits ORGANIZATION_ID ``` - The request requires the `read:limits` permission with an API key, or the `read:organization` permission when signed in. ```bash curl 'https://api.daytona.com/orgs/ORGANIZATION_ID/limits' \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' ``` ```json { "sandboxes": { "concurrent": { "limit": 10, "usage": 2 }, "total": { "limit": 50, "usage": 4 }, "gpu_concurrent": { "limit": 0, "usage": 0 }, "windows_concurrent": { "limit": 0, "usage": 0 } }, "image_builds": { "concurrent": { "limit": null, "usage": 0 } }, "storage": { "volumes": { "limit": null, "usage": 2 }, "images": { "limit": null, "usage": 5 }, "snapshots": { "limit": null, "usage": 3 } }, "members": { "limit": 5, "usage": 3, "pending_invitations": 1 }, "api_keys_per_organization": { "limit": 1000, "usage": 12 }, "api_keys_per_project": { "limit": 100, "usage": 7 }, "secrets_per_project": { "limit": 500, "usage": 20 } } ``` The response has the following fields: | **Field** | **Description** | | --------------------------- | ------------------------------------------------------------------------------------------------------------------- | | `limit` | Each limit reports its effective cap in `limit`. A value of `null` means no limit. Reaching the cap refuses new work. | | `usage` | Each limit reports the current usage counted against it in `usage`. | | `sandboxes` | The concurrent, total, GPU, and Windows sandbox limits. | | `image_builds` | The concurrent image build limit. | | `storage` | The volume, image, and snapshot limits. | | `members` | The seat cap. `pending_invitations` counts the invitations that reserve a seat until they are accepted or declined. | | `api_keys_per_organization` | The live API key limit of the organization. | | `api_keys_per_project` | The live API key limit of any one project, with the highest current usage. | | `secrets_per_project` | The secret limit of any one project, with the highest current usage. | - The request requires the `read:limits` permission with an API key, or the `read:organization` permission when signed in. ### Set the timeout cap [#set-the-timeout-cap] Set or clear the organization's maximum sandbox timeout. Daytona validates every sandbox [timeout](/docs/linux-sandboxes#timeout) against this cap. The cap can be any value up to the platform maximum, and clearing it inherits the platform maximum. ```bash # Cap every sandbox timeout in the organization at 1 hour curl 'https://api.daytona.com/orgs/ORGANIZATION_ID' \ --request PATCH \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' \ --data '{ "max_sandbox_timeout_seconds": 3600 }' # Clear the cap and inherit the platform maximum curl 'https://api.daytona.com/orgs/ORGANIZATION_ID' \ --request PATCH \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' \ --data '{ "max_sandbox_timeout_seconds": null }' ``` | **Field** | **Type** | **Description** | | ----------------------------- | --------- | --------------------------------------------------------------------------------------------------- | | `max_sandbox_timeout_seconds` | integer | Sets the cap in seconds, up to the platform maximum, which is `86400` by default. A value of `null` clears the cap. A value above the platform maximum returns `400`. | - The request requires the `write:organization` permission. - The request requires a signed-in user token. ## Entitlements and feature flags [#entitlements-and-feature-flags] Entitlements are the capabilities an organization's plan grants; feature flags are platform switches evaluated per organization. Both are read-only and return every catalog key, so a client never has to guess at an absent key. ### Entitlements [#entitlements] ```bash curl 'https://api.daytona.com/orgs/ORGANIZATION_ID/entitlements' \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' ``` ```json { "entitlements": { "preview_warning_opt_out": false } } ``` - The request requires the `read:organization` permission, which every role includes. ### Feature flags [#feature-flags] ```bash curl 'https://api.daytona.com/orgs/ORGANIZATION_ID/feature-flags' \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' ``` - The request requires the `read:organization` permission, which every role includes. ## Preview warning [#preview-warning] Turn the preview warning page off or on. It applies to every [sandbox preview](/docs/preview) in the organization and decides whether a visitor sees the warning page first. ```bash curl 'https://api.daytona.com/orgs/ORGANIZATION_ID/preview-warning' \ --request PATCH \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "disabled": true }' ``` | **Field** | **Type** | **Description** | | --------- | -------- | --------------- | | `disabled` | boolean | Turns the preview warning off when `true` and on when `false`. | - The request requires the `write:organization` permission. - Turning the preview warning off requires the Team or Enterprise [plan](/docs/billing#get-the-plan). - Turning the preview warning on is available on every plan. ## OpenTelemetry configuration [#opentelemetry-configuration] Forward the logs, traces, and metrics of every sandbox in the organization to your OpenTelemetry collector. The forwarding configuration holds the OTLP/HTTP endpoint and the request headers to send. Getting the configuration requires the `read:organization` permission, and setting or deleting it requires the `write:organization` permission. For the requests and their fields, see [forward sandbox telemetry](/docs/opentelemetry#forward-sandbox-telemetry). ## Permissions [#permissions] Organization settings and membership are governed by organization permissions, which you can grant through an [organization role](/docs/organizations#roles). Every role includes the organization read permission, and leaving an organization requires only that permission. The [audit logs](/docs/audit-logs) record organization changes, invitations, and member changes. | **Permission** | **Grants** | | ------------------------- | ------------------------------------------------------------------------------------------------ | | **`read:organization`** | Get the organization, its limits, entitlements, feature flags, and telemetry configuration | | **`write:organization`** | Rename the organization and change its timeout cap, preview warning, and telemetry configuration | | **`delete:organization`** | Delete the organization | | **`read:members`** | List members and pending invitations | | **`write:members`** | Invite members, change their access, and cancel invitations | | **`delete:members`** | Remove members | | **`write:roles`** | Create and update custom roles | | **`delete:roles`** | Delete custom roles | # Projects (/docs/projects) Projects group resources and credentials inside an [organization](/docs/organizations). Organizations contain projects, and projects contain everything else: every sandbox, image, snapshot, volume, secret, registry credential, and API key is scoped to exactly one project. Projects are the unit of isolation. Nothing is shared between projects implicitly: a secret or volume in one project is invisible to sandboxes in another, and a project's API key cannot see other projects' resources. Organizations are the unit of membership and billing. | **Concept** | **Description** | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | **Organization** | The unit of membership and billing. Members, invitations, and credits belong to the organization. Contains any number of projects. | | **Project** | The unit of isolation. Holds sandboxes, images, snapshots, volumes, secrets, registry credentials, and API keys. | | **API key** | Minted per project. Confined to that project and to its permission scopes; revoking a key takes effect immediately for new requests. | Every organization has a project named default that cannot be renamed or deleted. The name is reserved, so no other project can use it. ### Project access [#project-access] Projects also decide which organization members can reach their resources: - Organization admins can access every project. - Every member can access the `default` project. - Any other project is visible only to members who have been added to it. Members who are not on a project get a `404` for it, as if it did not exist. Whoever creates a project is added to it automatically. Projects are managed on the dashboard's **Projects** page and switched in the header's organization and project switcher. These routes use your dashboard session token (an OIDC bearer JWT), not a project API key, and need matching organization project permissions. ## Create projects [#create-projects] Create a project. Names are trimmed, unique per organization, and up to 100 characters. 1. Go to [Daytona Dashboard](https://app.daytona.com/dashboard/projects) 2. Click 3. Enter a for the project 4. Click You can also click the project switcher in the header and choose **Create Project**. ```bash daytona project create my-project --org ORG_ID ``` ```bash curl 'https://api.daytona.com/orgs/ORG_ID/projects' \ --request POST \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "name": "my-project" }' ``` ```json { "id": "PROJECT_ID", "org_id": "ORG_ID", "name": "my-project", "default": false, "created_by": "USER_ID", "created_at": "2026-09-10T12:00:00Z", "updated_at": "2026-09-10T12:00:00Z" } ``` The creator field is null unless the caller holds the members read permission. ## Operations [#operations] ### List projects [#list-projects] List the projects you can access in an organization, newest first. ```bash daytona project list --org ORG_ID ``` ```bash curl 'https://api.daytona.com/orgs/ORG_ID/projects' \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' ``` ```json { "projects": [ { "id": "PROJECT_ID", "org_id": "ORG_ID", "name": "my-project", "default": false, "created_by": "USER_ID", "created_at": "2026-09-10T12:00:00Z", "updated_at": "2026-09-10T12:00:00Z" }, { "id": "DEFAULT_PROJECT_ID", "org_id": "ORG_ID", "name": "default", "default": true, "created_by": null, "created_at": "2026-09-01T09:00:00Z", "updated_at": "2026-09-01T09:00:00Z" } ] } ``` ### Select project [#select-project] Select the project that later CLI commands run against. The selection is per organization, so switching organizations restores your last project there. Pass an ID or an unambiguous name; with no argument, the CLI shows a picker at a terminal. ```bash daytona project use PROJECT_ID ``` ### Get by ID [#get-by-id] Get a single project. ```bash daytona project get PROJECT_ID ``` ```bash curl 'https://api.daytona.com/projects/PROJECT_ID' \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' ``` ### Rename projects [#rename-projects] Rename a project. The default project cannot be renamed. 1. Go to [Daytona Dashboard](https://app.daytona.com/dashboard/projects) 2. Click the menu of the project 3. Click 4. Enter the new name and confirm ```bash daytona project update PROJECT_ID --name my-renamed-project --org ORG_ID ``` ```bash curl 'https://api.daytona.com/projects/PROJECT_ID' \ --request PATCH \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "name": "my-renamed-project" }' ``` ### Delete projects [#delete-projects] Delete a project, revoking its API keys and removing its secrets and registries. The default project cannot be deleted. 1. Go to [Daytona Dashboard](https://app.daytona.com/dashboard/projects) 2. Click the menu of the project 3. Click 4. Confirm the deletion ```bash daytona project delete PROJECT_ID --org ORG_ID ``` - The request requires the `delete:projects` permission. - The project must own no sandboxes, volumes, images, snapshots, or functions. - Delete the remaining resources first. ```bash curl 'https://api.daytona.com/projects/PROJECT_ID' \ --request DELETE \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' ``` ```json { "deleted": "PROJECT_ID" } ``` - The request requires the `delete:projects` permission. - The project must own no sandboxes, volumes, images, snapshots, or functions. - Delete the remaining resources first. ## Project budgets [#project-budgets] A project budget caps the project's spend in each calendar month, in UTC, at list price and before credits. When the month-to-date spend reaches the budget, creating, forking, starting, or resuming a sandbox in the project, or restoring one from a snapshot, is refused. After the organization's grace period, running persistent sandboxes are stopped and running ephemeral sandboxes are deleted. macOS sandboxes, which run on a prepaid Mac reservation, keep running until the reservation's paid period ends; while the project is held, a renewal fails, so the reservation ends at the end of its paid period. The hold lifts at the start of the next month; when the grace period would end after that, no sandbox is ended that month. Spend is evaluated periodically and can lag usage by several minutes. ### Get a project budget [#get-a-project-budget] Get a project's monthly budget and this month's spend. The SDKs, and the API with an API key, read the budget of the API key's project. ```python from daytona import Daytona daytona = Daytona() budget = daytona.v2.get_project_budget() if budget.monthly_limit_cents is None: print("The project has no budget") else: print(f"Spent {budget.spent_cents} of {budget.monthly_limit_cents} cents") ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const budget = await daytona.v2.getProjectBudget() if (budget.monthlyLimitCents === undefined) { console.log('The project has no budget') } else { console.log(`Spent ${budget.spentCents} of ${budget.monthlyLimitCents} cents`) } ``` ```bash # The argument is optional; omit it to use the selected project daytona project budget get PROJECT_ID ``` ```bash # Any project, with a signed-in user token curl 'https://api.daytona.com/projects/PROJECT_ID/budget' \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' # The API key's project curl 'https://api.daytona.com/usage/budget' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ```json { "project_id": "PROJECT_ID", "monthly_limit_cents": 50000, "period_start": "2026-10-01", "spent_cents": 12345, "evaluated_at": "2026-10-09T01:20:00Z", "exceeded_at": null, "stop_at": null, "stop_grace_hours": 1 } ``` The response has the following fields: | **Field** | **Description** | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `monthly_limit_cents` | The monthly budget, in US cents. | | `spent_cents` | The spend this period, in US cents. The value is `null` until the first evaluation in the period. | | `evaluated_at` | The value is `null` until the first evaluation in the period. | | `exceeded_at` | The time the budget was reached this period. The value is `null` while the spend is under the budget. | | `stop_at` | The time running sandboxes are ended, which is `exceeded_at` plus the organization's grace period. The value is `null` when `exceeded_at` is `null`. The value is also `null` when `exceeded_at` plus the grace period falls in the next month. | - Getting the budget of a project by ID requires the `read:budgets` permission. - Getting the budget of the project of the API key requires the `read:spending` permission. ### Set a project budget [#set-a-project-budget] Set or replace a project's monthly budget. 1. Go to [Daytona Dashboard](https://app.daytona.com/dashboard/projects) 2. Click the project 3. In the **Budget** section, click , or to replace an existing one 4. Enter the **Monthly budget** in USD 5. Click ```bash # The argument is optional; omit it to use the selected project daytona project budget set PROJECT_ID --monthly-usd 500 ``` | **Flag** | **Type** | **Description** | | --------------- | -------- | ---------------------------------------------------------------------------------------- | | `--monthly-usd` | string | Required. Monthly budget in US dollars, at least `1.00` and at most two decimals, such as `500` or `499.99`. | - The request requires the `write:budgets` permission. - The request requires the Team or Enterprise [plan](/docs/billing#get-the-plan). ```bash curl 'https://api.daytona.com/projects/PROJECT_ID/budget' \ --request PUT \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' \ --data '{ "monthly_limit_cents": 50000 }' ``` | **Field** | **Type** | **Description** | | --------------------- | --------- | ---------------------------------------------------------------------------------- | | `monthly_limit_cents` | integer | Required. Monthly budget in US cents, from `100` ($1.00) to `100000000000` ($1 billion). | - The request requires the `write:budgets` permission. - The request requires the Team or Enterprise [plan](/docs/billing#get-the-plan). ### Remove a project budget [#remove-a-project-budget] Remove a project's monthly budget. Removing it releases a budget hold on the project; sandboxes that were already stopped stay stopped. 1. Go to [Daytona Dashboard](https://app.daytona.com/dashboard/projects) 2. Click the project 3. In the **Budget** section, click 4. Confirm with ```bash # The argument is optional; omit it to use the selected project daytona project budget remove PROJECT_ID ``` - The request requires the `write:budgets` permission. - `daytona project budget remove` asks for confirmation. ```bash curl 'https://api.daytona.com/projects/PROJECT_ID/budget' \ --request DELETE \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' ``` ## Lifecycle defaults [#lifecycle-defaults] Lifecycle defaults set the [timeouts](/docs/linux-sandboxes#timeouts) that new Linux sandboxes in a project receive when the create request leaves them out. A project stores them as defaults for ephemeral sandboxes, and these timeouts always delete the sandbox. A macOS create does not take the project's lifecycle defaults: it gets the platform defaults. Daytona reads the defaults only when it creates a sandbox. Each field the create request sets overrides the matching default, and saving new defaults never changes existing sandboxes. ### Get lifecycle defaults [#get-lifecycle-defaults] Get a project's stored lifecycle defaults and the policy a create without lifecycle settings receives for each sandbox type. 1. Go to [Daytona Dashboard](https://app.daytona.com/dashboard/projects) 2. Click the project 3. Open the **Settings** tab and find the **Sandbox Lifecycle Policy** section ```bash curl 'https://api.daytona.com/projects/PROJECT_ID/lifecycle-policy' \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' ``` The following response is abridged to the effective defaults of ephemeral Linux sandboxes. The full response also has the effective defaults of Windows, GPU, and macOS sandboxes. ```json { "policy": { "ephemeral": { "timeout_seconds": 1800, "idle_timeout_seconds": 600 } }, "effective": { "linux": { "ephemeral": { "timeout_seconds": 1800, "on_timeout": "delete", "timeout_source": "project", "timeout_capped": false, "idle_timeout_seconds": 600, "on_idle_timeout": "delete" } } } } ``` The response has the following fields: | **Field** | **Description** | | ------------------ | -------------------------------------------------------------------------------------------------------------------------------- | | `policy` | Holds the stored values. An unset field is `null`. | | `effective` | Holds what a create with no lifecycle settings receives. The `macos` block shows the platform defaults that a macOS create receives. | | `timeout_source` | The value in each `effective` block is `project`, `platform`, or `none`. | | `timeout_capped` | The value in each `effective` block is `true` when a stored timeout above the organization's [timeout cap](/docs/organizations#set-the-timeout-cap) is capped to it. | ### Update lifecycle defaults [#update-lifecycle-defaults] Update a project's lifecycle defaults. Each block is updated as a whole: a block left out of the request is kept, an empty value clears it, and a sent block replaces the stored one, so a field left out of a sent block is unset. 1. Go to [Daytona Dashboard](https://app.daytona.com/dashboard/projects) 2. Click the project 3. Open the **Settings** tab 4. In the **Sandbox Lifecycle Policy** section, click the edit button on the **Ephemeral sandboxes** card 5. Set the timeouts, then click ```bash curl 'https://api.daytona.com/projects/PROJECT_ID/lifecycle-policy' \ --request PATCH \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' \ --data '{ "ephemeral": { "timeout_seconds": 1800, "idle_timeout_seconds": 600 } }' ``` | **Field** | **Type** | **Description** | | ------------------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------- | | `ephemeral` | object | Sets the timeouts for sandboxes. `null` clears the block. If omitted, the stored block is kept. | | `ephemeral.timeout_seconds` | integer | Sets the seconds until a sandbox is deleted, from `1` to the organization's maximum timeout. By default, it is unset. | | `ephemeral.idle_timeout_seconds` | integer | Sets the idle seconds until a sandbox is deleted. Values below `60` are raised to `60`. By default, it is unset. | - The request requires the `write:projects` permission. - Setting, changing, or clearing a delete action also requires the `delete:sandboxes` permission. ## Project members [#project-members] Control which organization members can access a non-default project. Organization admins are members of every project implicitly and do not need to be added. ### List project members [#list-project-members] ```bash daytona project member list --project PROJECT_ID ``` ```bash curl 'https://api.daytona.com/projects/PROJECT_ID/members' \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' ``` ```json { "members": [ { "user_id": "USER_ID", "email": "jane@example.com", "name": "Jane Doe", "implicit": false, "added_at": "2026-09-10T12:00:00Z" } ] } ``` The implicit flag is true for organization admins, who have access without a membership entry. ### Add project members [#add-project-members] Add one or more members in one request. ```bash daytona project member add USER_ID --project PROJECT_ID --org ORG_ID daytona project member add --bulk USER_ID_1,USER_ID_2 --project PROJECT_ID --org ORG_ID ``` | **Flag** | **Type** | **Description** | | -------- | -------- | ---------------------------------------------------------------------------------------------------- | | `--bulk` | string | Adds several users, as a comma-separated list of user IDs, emails, or names. This flag cannot be combined with a positional user. | ```bash curl 'https://api.daytona.com/projects/PROJECT_ID/members' \ --request POST \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "user_ids": ["USER_ID_1", "USER_ID_2"] }' ``` ```json { "added_user_ids": ["USER_ID_1", "USER_ID_2"] } ``` | **Field** | **Type** | **Description** | | ---------- | ---------- | --------------------------------------------------------------------------------------- | | `user_ids` | string\[\] | Required. At most 200 user IDs per request; a larger list returns `400 Bad Request`. | ### Remove project members [#remove-project-members] Remove a member from a project. Unless they are an organization admin, removal also revokes the API keys they minted in the project; admins keep access through their role. ```bash daytona project member remove USER_ID --project PROJECT_ID --org ORG_ID ``` ```bash curl 'https://api.daytona.com/projects/PROJECT_ID/members/USER_ID' \ --request DELETE \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' ``` The request returns 204 No Content. ## Project service accounts [#project-service-accounts] ### List project service accounts [#list-project-service-accounts] List the service accounts that can hold API keys in a project. A service account mints keys only in projects it has been added to. The default project is open to every service account. ```bash daytona project service-account list --project PROJECT_ID ``` ```bash curl 'https://api.daytona.com/projects/PROJECT_ID/service-accounts' \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' ``` ### Add project service accounts [#add-project-service-accounts] Add a service account to a project. Archived service accounts cannot be added, and you must hold every permission the account holds. ```bash daytona project service-account add SERVICE_ACCOUNT_ID --project PROJECT_ID --org ORG_ID ``` ```bash curl 'https://api.daytona.com/projects/PROJECT_ID/service-accounts' \ --request POST \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "service_account_id": "SERVICE_ACCOUNT_ID" }' ``` ### Remove project service accounts [#remove-project-service-accounts] Remove a service account from a project, revoking every API key it holds there. ```bash daytona project service-account remove SERVICE_ACCOUNT_ID --project PROJECT_ID --org ORG_ID ``` ```bash curl 'https://api.daytona.com/projects/PROJECT_ID/service-accounts/SERVICE_ACCOUNT_ID' \ --request DELETE \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' ``` The request returns 204 No Content. ## Project secrets and registries [#project-secrets-and-registries] [Secrets](/docs/secrets) and [registry credentials](/docs/registries) belong to a project. Manage them with a credential that acts in the project: a project API key, or the access token from [exchanging a token](/docs/api-keys#exchange-a-token) for that project. The CLI uses the selected project's credential after you sign in. ## Permissions [#permissions] Projects and their budgets, members, and service accounts are governed by organization permissions, which you can grant through an [organization role](/docs/organizations#roles). A project API key or project access token reads the budget of its own project with the project spending permission. Changing a lifecycle default whose action is delete also requires the permission to delete sandboxes. The [audit logs](/docs/audit-logs) record project creates, updates, and deletes, and budget, member, and service account changes. | **Permission** | **Grants** | | ---------------------------- | -------------------------------------------------------------- | | **`read:projects`** | List and get projects and their lifecycle defaults | | **`write:projects`** | Create and rename projects and change their lifecycle defaults | | **`delete:projects`** | Delete projects | | **`read:budgets`** | Get project budgets | | **`write:budgets`** | Set and remove project budgets | | **`read:spending`** | Get the budget of the project of the API key or access token | | **`read:members`** | List project members | | **`write:members`** | Add and remove project members | | **`read:service_accounts`** | List project service accounts | | **`write:service_accounts`** | Add and remove project service accounts | # API Keys (/docs/api-keys) Daytona API keys authenticate requests from the SDKs, the CLI, and the API to the resources in a [project](/docs/projects). To pass a key, see [authentication](/docs/authentication). [Organization API keys](#organization-api-keys) cover organization-level operations that are not tied to a project. Every project API key belongs to exactly one project and carries an explicit list of [permissions](#scopes); its requests are confined to both. Keys can carry an expiry. Revocation applies to new requests; a regional proxy can accept a revoked key for up to 30 seconds. In an organization kept in sync with Daytona v0, a key that a member creates in the default project under a name other than `default` is also copied to Daytona v0. The v0 copy can read every sandbox, snapshot, and registry in the organization, whatever the key's permissions. To keep a key off Daytona v0, set `sync_to_v0` to `false` when you create it, or update the key later. ## Create an API key [#create-an-api-key] Create an API key to authenticate Daytona SDK and API requests. 1. Go to [Daytona Dashboard ↗](https://app.daytona.com/dashboard/keys) 2. Select the project in the header switcher 3. Click 4. Enter a , optionally set an expiry, and [select permissions](#scopes) 5. Click 6. Copy the API key to your clipboard and use it to authenticate requests ```bash daytona key mint --project PROJECT_ID \ --name my-api-key \ --permission write:sandboxes,delete:sandboxes \ --expires 2027-01-01T00:00:00Z ``` | **Flag** | **Type** | **Description** | | -------------- | -------- | ------------------------------------------------------------------------------- | | `--permission` | string | A comma-separated list of permissions. | | `--expires` | string | An RFC 3339 timestamp or a Go duration such as `720h`, counted from now. | - The request requires the `write:project_api_keys` permission. - `daytona key mint` prints the plaintext token once, when the key is created. ```bash curl 'https://api.daytona.com/projects/PROJECT_ID/api-keys' \ --request POST \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "name": "my-api-key", "project_permissions": ["write:sandboxes", "delete:sandboxes"], "expires_at": "2027-01-01T00:00:00Z" }' ``` ```json { "id": "KEY_ID", "name": "my-api-key", "project_id": "PROJECT_ID", "key_prefix": "dtn_...", "token": "YOUR_API_KEY", "project_permissions": ["read:sandboxes", "write:sandboxes", "delete:sandboxes"], "expires_at": "2027-01-01T00:00:00Z", "service_account_id": null } ``` | **Field** | **Description** | | ------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | `name` | Display name for the key. Optional; defaults to `default`. Any other name must be unique among the project's live keys. | | `project_permissions` | Required, non-empty list of [permissions](#scopes). Unknown values are rejected. | | `expires_at` | Optional RFC 3339 timestamp in the future. Omit for a key that never expires. | | `service_account_id` | Optional. Mint the key for a [service account](#service-accounts) instead of yourself. Service account keys must be named. | | `sync_to_v0` | Optional. Copies the key to Daytona v0. Defaults to `true`. Applies only to keys a person mints in the `default` project; see [update an API key](#update-an-api-key). | The response has the following fields: | **Field** | **Description** | | --------------------- | --------------------------------------------------------------------------------------- | | `id` | The API key ID. | | `name` | The API key name. | | `project_id` | The project the key belongs to. | | `key_prefix` | The leading characters of the token, shown in lists to recognize the key. | | `token` | The secret token. Only the create response returns it, so store it then. | | `project_permissions` | The permissions of the key, with the read permission each write or delete implies. | | `expires_at` | When the key expires, or `null` when it does not expire. | | `service_account_id` | The service account that owns the key, or `null` for a key you own. | ## Credentials [#credentials] Daytona accepts two bearer credentials, named differently in this page's API examples: | **Credential** | **Description** | | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **API KEY** | A project API key created as described above. It authenticates SDK, toolbox, and sandbox requests, and the few management routes that accept it, such as [getting the current key](#get-current-api-key). This is the credential the SDKs and the `DAYTONA_API_KEY` variable carry. See [authentication](/docs/authentication) for how to pass it to the SDKs, the CLI, and API requests. | | **OIDC TOKEN** | The session token of a signed-in user (an OIDC bearer JWT, the credential the dashboard uses). Management routes that act on behalf of a person require it and reject API keys with `401`: creating, listing, and revoking keys, service accounts, [organizations](/docs/organizations), [projects](/docs/projects), and [billing](/docs/billing). Obtain it by signing in with the dashboard or `daytona login`; the CLI commands in those sections use the saved session for you. | [Organization API keys](#organization-api-keys) are a third kind, scoped to an organization rather than a project; that section lists the scopes they can hold. ## Scopes [#scopes] | **Resource** | **Scope** | **Description** | | ------------------ | ----------------------- | ------------------------------------------------------------------ | | Sandboxes | **`read:sandboxes`** | View sandboxes | | | **`write:sandboxes`** | Create/modify sandboxes and use the toolbox | | | **`delete:sandboxes`** | Delete sandboxes | | Snapshots | **`read:snapshots`** | View [snapshots](/docs/snapshots) | | | **`write:snapshots`** | Create/modify snapshots | | | **`delete:snapshots`** | Delete snapshots | | Images | **`read:images`** | View [images](/docs/images) | | | **`write:images`** | Create/modify images | | | **`delete:images`** | Delete images | | Volumes | **`read:volumes`** | View [volumes](/docs/volumes) | | | **`write:volumes`** | Create/modify volumes | | | **`delete:volumes`** | Delete volumes | | Registries | **`read:registries`** | View [registries](/docs/registries) | | | **`write:registries`** | Create/modify registries | | | **`delete:registries`** | Delete registries | | Secrets | **`read:secrets`** | View [secrets](/docs/secrets) | | | **`write:secrets`** | Create/modify secrets | | | **`delete:secrets`** | Delete secrets | | Spending | **`read:spending`** | View project spending | | Limits | **`read:limits`** | View [organization limits](/docs/organizations#limits) | | Functions | **`read:functions`** | View functions | | | **`write:functions`** | Deploy and configure functions | | | **`delete:functions`** | Delete functions | | Invocations | **`read:invocations`** | View invocation history | | | **`write:invocations`** | Invoke functions | ## Operations [#operations] ### List API keys [#list-api-keys] List the API keys of a project. The list never contains tokens or revoked keys; an expired key stays in the list until Daytona deletes it. Daytona deletes revoked and expired keys 7 days after they stop working. ```bash daytona key list --project PROJECT_ID ``` ```bash curl 'https://api.daytona.com/projects/PROJECT_ID/api-keys' \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' ``` ```json { "project_api_keys": [ { "id": "KEY_ID", "name": "my-api-key", "key_prefix": "dtn_...", "created_at": "2026-09-10T12:00:00Z", "revoked_at": null, "last_used_at": "2026-09-11T08:30:00Z", "project_permissions": ["read:sandboxes", "write:sandboxes", "delete:sandboxes"], "expires_at": "2027-01-01T00:00:00Z", "service_account_id": null, "service_account_name": null } ], "next_cursor": null } ``` ### Get API key [#get-api-key] ```bash curl 'https://api.daytona.com/projects/PROJECT_ID/api-keys/KEY_ID' \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' ``` ### Get current API key [#get-current-api-key] Get the API key that authenticates the request, including the project and organization it acts in and the permissions it carries. The response never contains the token. ```python from daytona import Daytona daytona = Daytona() key = daytona.v2.current_api_key() print(key.name, key.context.project_name, key.context.org_name) print(key.project_permissions) ``` ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const key = await daytona.v2.currentApiKey() console.log(key.name, key.context.projectName, key.context.orgName) console.log(key.projectPermissions) ``` ```bash curl 'https://api.daytona.com/api-keys/current' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ### Exchange a token [#exchange-a-token] Exchange a signed-in user's session token for a short-lived access token scoped to one project. The access token carries the user's own permissions in that project and authenticates workload requests in place of a project API key. Organization API keys cannot be exchanged. ```bash curl 'https://api.daytona.com/auth/token' \ --request POST \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange", "subject_token": "YOUR_OIDC_TOKEN", "subject_token_type": "urn:ietf:params:oauth:token-type:access_token", "project_id": "PROJECT_ID" }' ``` ```json { "access_token": "eyJ...", "issued_token_type": "urn:ietf:params:oauth:token-type:access_token", "token_type": "Bearer", "expires_in": 300 } ``` | **Field** | **Type** | **Description** | | -------------------- | -------- | ------------------------------------------------------------------------------------------------------------------- | | `grant_type` | string | Required. `urn:ietf:params:oauth:grant-type:token-exchange`. | | `subject_token` | string | Required. Must be the same token as the bearer in the `Authorization` header; otherwise the request returns `400`. | | `subject_token_type` | string | Required. `urn:ietf:params:oauth:token-type:access_token` or `urn:ietf:params:oauth:token-type:jwt`. | | `project_id` | string | Required. The project the access token is scoped to. An unknown project, or one you are not a member of, returns `404`. | - `expires_in` is the access token lifetime in seconds. - Exchange again for a new access token when the current access token expires. - The request must omit `scope` and `resource`. ### Update an API key [#update-an-api-key] Update whether an API key is copied to Daytona v0. A Daytona v0 copy can read every sandbox, snapshot, and registry of the organization on Daytona v0, because Daytona v0 has no read permissions. Turning the copy off deletes the Daytona v0 key shortly afterwards; the key keeps working on Daytona v2. ```bash curl 'https://api.daytona.com/projects/PROJECT_ID/api-keys/KEY_ID' \ --request PATCH \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "sync_to_v0": false }' ``` | **Field** | **Type** | **Description** | | ---------------- | ------------- | ---------------------------------------------------------------------------- | | `sync_to_v0` | boolean | Required. `false` deletes the Daytona v0 copy; `true` copies the key again. | - Updating a key you created requires the `write:project_api_keys` permission. - Updating a key that another member created requires the `delete:project_api_keys` permission. - Updating a service account key requires the `delete:service_accounts` permission. - The key must be one that a person minted in the `default` project of an organization that syncs with Daytona v0, under a name other than `default`. - Daytona copies only these keys to Daytona v0. ### Revoke an API key [#revoke-an-api-key] Revoke an API key. Revocation cannot be undone. New requests made with the key fail, except at a regional proxy, which can accept the key for up to 30 seconds after revocation. Daytona deletes the revoked key 7 days later. 1. Go to [Daytona Dashboard ↗](https://app.daytona.com/dashboard/keys) 2. Click next to the API key you want to revoke 3. Confirm the revocation ```bash daytona key revoke KEY_ID ``` - Revoking a key you created requires the `write:project_api_keys` permission. - Revoking a key that another member created requires the `delete:project_api_keys` permission. - Revoking a service account key requires the `delete:service_accounts` permission. ```bash curl 'https://api.daytona.com/projects/PROJECT_ID/api-keys/KEY_ID' \ --request DELETE \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' ``` - Revoking a key you created requires the `write:project_api_keys` permission. - Revoking a key that another member created requires the `delete:project_api_keys` permission. - Revoking a service account key requires the `delete:service_accounts` permission. ## Service accounts [#service-accounts] Service accounts are non-human identities in your organization. Use them to own API keys for automation so that the keys are not tied to a person's membership. ### Create a service account [#create-a-service-account] ```bash daytona service-account create my-service-account --role developer --org ORG_ID ``` | **Flag** | **Type** | **Description** | | -------- | -------- | ------------------------------------- | | `--role` | string | Sets the roles, as a comma-separated list of role slugs. | ```bash curl 'https://api.daytona.com/orgs/ORG_ID/service-accounts' \ --request POST \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "name": "my-service-account", "roles": ["developer"] }' ``` | **Field** | **Type** | **Description** | | ------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------- | | `name` | string | Required. At most 64 letters, digits, `-`, or `_`, unique in the organization. | | `description` | string | Optional, up to 512 characters. | | `roles` | string\[\] | Required. Must hold at least one role. The `admin` role is refused, and every permission the roles grant must be one you hold yourself. | - The request requires the `write:service_accounts` permission. - Personal organizations cannot have service accounts. ### Create a service account key [#create-a-service-account-key] Create an API key owned by a service account. The key keeps working when its creator leaves the organization. Outside the default project, the service account must first be [added to the project](/docs/projects#add-project-service-accounts), and the key can carry only permissions you and the service account both hold. 1. Go to [Daytona Dashboard ↗](https://app.daytona.com/dashboard/keys) 2. Click 3. Under , select the service account 4. Enter a , [select permissions](#scopes), and click ```bash daytona key mint --project PROJECT_ID \ --name my-service-account-key \ --permission write:sandboxes \ --service-account SERVICE_ACCOUNT_ID \ --org ORG_ID ``` ```bash curl 'https://api.daytona.com/projects/PROJECT_ID/api-keys' \ --request POST \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "name": "my-service-account-key", "project_permissions": ["write:sandboxes"], "service_account_id": "SERVICE_ACCOUNT_ID" }' ``` ### List service accounts [#list-service-accounts] ```bash daytona service-account list --org ORG_ID ``` ```bash curl 'https://api.daytona.com/orgs/ORG_ID/service-accounts' \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' ``` ### Get a service account [#get-a-service-account] ```bash daytona service-account get SERVICE_ACCOUNT_ID ``` ```bash curl 'https://api.daytona.com/orgs/ORG_ID/service-accounts/SERVICE_ACCOUNT_ID' \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' ``` ### Update a service account [#update-a-service-account] Update a service account's name, description, or roles. Fields you leave out stay unchanged, and new roles replace the whole role set. When the new roles are narrower, Daytona revokes the account's project API keys that exceed them. ```bash # The CLI updates the name (--name) and roles (--role); it cannot set the description daytona service-account update SERVICE_ACCOUNT_ID --role maintainer ``` ```bash curl 'https://api.daytona.com/orgs/ORG_ID/service-accounts/SERVICE_ACCOUNT_ID' \ --request PATCH \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "description": "CI runner", "roles": ["maintainer"] }' # Preview the change without applying it: { "revoked_api_keys": ..., "revoked_preview_grants": ... } curl 'https://api.daytona.com/orgs/ORG_ID/service-accounts/SERVICE_ACCOUNT_ID/update-preview' \ --request POST \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "roles": ["maintainer"] }' ``` - The requests require the `write:service_accounts` permission. - The request requires at least one of `name`, `description`, or `roles`. ### Archive a service account [#archive-a-service-account] Archive a service account. This revokes every project API key it owns. An archived account cannot be updated, added to projects, or given new keys, and lists do not contain it. ```bash daytona service-account delete SERVICE_ACCOUNT_ID ``` ```bash curl 'https://api.daytona.com/orgs/ORG_ID/service-accounts/SERVICE_ACCOUNT_ID' \ --request DELETE \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' ``` ## Organization API keys [#organization-api-keys] Organization API keys authenticate organization-level operations that are not tied to a project. | **Resource** | **Scope** | **Description** | | ------------------- | ------------------------------------------------------------- | ------------------------------------------- | | Audit logs | **`read:audit`** | View [audit logs](/docs/audit-logs) | | Billing | **`read:billing`**, **`write:billing`** | View and manage [billing](/docs/billing) | | Spending | **`read:spending`** | View organization spending | | Telemetry | **`read:telemetry`** | Read sandbox logs, traces, and metrics | ```bash # Create daytona org-key mint --org ORG_ID --name my-org-key --permission read:audit # List daytona org-key list --org ORG_ID # Revoke daytona org-key revoke KEY_ID ``` | **Flag** | **Type** | **Description** | | -------- | -------- | --------------- | | `--name` | string | This flag is required. | - Listing and getting organization API keys requires the `read:org_api_keys` permission. - Creating an organization API key requires the `write:org_api_keys` permission. - Revoking an organization API key requires the `delete:org_api_keys` permission. - `daytona org-key mint` prints the plaintext token once, when the key is created. - `daytona org-key revoke` asks for confirmation at a terminal and requires `--yes` otherwise. ```bash # Create curl 'https://api.daytona.com/orgs/ORG_ID/api-keys' \ --request POST \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "name": "my-org-key", "org_permissions": ["read:audit"] }' # List curl 'https://api.daytona.com/orgs/ORG_ID/api-keys' \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' # Get curl 'https://api.daytona.com/orgs/ORG_ID/api-keys/KEY_ID' \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' # Revoke curl 'https://api.daytona.com/orgs/ORG_ID/api-keys/KEY_ID' \ --request DELETE \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' ``` | **Field** | **Type** | **Description** | | ----------------- | ---------- | ------------------------------------------------------------ | | `name` | string | Required. | | `org_permissions` | string\[\] | Required. A non-empty list of scopes from the table above. | | `expires_at` | string | Optional. Must be in the future. | The create response has the following fields: | **Field** | **Description** | | ----------------- | ------------------------------------------------------------------------ | | `id` | The API key ID. | | `key_prefix` | The leading characters of the token, shown in lists to recognize the key. | | `token` | The secret token. Only the create response returns it, so store it then. | | `org_permissions` | The organization permissions of the key. | | `expires_at` | When the key expires, or `null` when it does not expire. | ## Permissions [#permissions] API keys and service accounts are managed with organization permissions, which you can grant through an [organization role](/docs/organizations#roles). A key can hold only the permissions its creator holds. The [audit logs](/docs/audit-logs) record key creates, updates, and revocations, and service account changes. | **Permission** | **Grants** | | ----------------------------- | ------------------------------------------------------------------- | | **`read:project_api_keys`** | List and get project API keys | | **`write:project_api_keys`** | Create project API keys, and update and revoke the keys you created | | **`delete:project_api_keys`** | Update and revoke keys that other members created | | **`read:org_api_keys`** | List and get organization API keys | | **`write:org_api_keys`** | Create organization API keys | | **`delete:org_api_keys`** | Revoke organization API keys | | **`read:service_accounts`** | List and get service accounts | | **`write:service_accounts`** | Create and update service accounts, and create their keys together with `write:project_api_keys` | | **`delete:service_accounts`** | Archive service accounts, and update and revoke their keys | # SSO (/docs/sso) Organization SSO (Single Sign-On) lets the members of a collaborative organization sign in through your identity provider. Directory sync (SCIM) keeps the organization's members in sync with your directory. You configure both in the Admin Portal, a hosted setup page that Daytona opens through a short-lived setup link. Each identity provider you connect there appears in Daytona as an SSO connection, with its status and the email domains it signs in. When the organization is shared with Daytona v0, its single sign-on and directory sync configuration is shared with Daytona v0 too. Managing SSO requires the SSO permissions. Members with the **admin** or **sso-admin** role hold them. See [roles](/docs/organizations#roles). | **Field** | **Description** | | ------------------- | ------------------------------------------------------- | | **Name** | The connection name. | | **Connection type** | The connection protocol and provider type. | | **Status** | The connection status. | | **Email domains** | The email domains the connection signs in. | | **Updated at** | When the connection was last updated. | SSO is available on the Enterprise plan for collaborative organizations. A personal organization cannot use SSO. ## Configure SSO and directory sync [#configure-sso-and-directory-sync] Daytona provides methods to open the Admin Portal for single sign-on or for directory sync. The setup link expires five minutes after it is created, so open it right away. When you finish in the Admin Portal, it returns you to the SSO page of the dashboard. 1. Go to [Daytona SSO ↗](https://app.daytona.com/dashboard/sso) 2. Click to connect your identity provider, or to connect your directory 3. Complete the setup in the Admin Portal ```bash curl 'https://api.daytona.com/orgs/ORGANIZATION_ID/sso/setup-links' \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' \ --data '{ "intent": "sso" }' ``` | **Field** | **Type** | **Description** | | --------- | -------- | ------------------------------------------------------------------------------------------------ | | `intent` | string | Sets the setup area to open: `sso` for single sign-on or `dsync` for directory sync. This field is required. | The response has the following fields: | **Field** | **Description** | | --------- | ---------------------------------------------------------------------- | | `url` | The Admin Portal setup link. It expires five minutes after it is created. | ## List SSO connections [#list-sso-connections] List the SSO connections configured for the organization in the Admin Portal. An organization that has not completed the setup has no connections. 1. Go to [Daytona SSO ↗](https://app.daytona.com/dashboard/sso) 2. The connections table shows each connection with its status, email domains, and last update ```bash curl 'https://api.daytona.com/orgs/ORGANIZATION_ID/sso/connections?limit=100' \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' ``` | **Parameter** | **Type** | **Description** | | ------------- | --------- | ---------------------------------------------------------------------------- | | `limit` | integer | Sets the page size, from `1` to `200`. The default is `100`. | | `cursor` | string | Resumes the list after the previous page. Pass the `next_cursor` of that page. | The response has the following fields: | **Field** | **Description** | | ------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `connections` | Lists the SSO connections, each with `id`, `name`, `connection_type`, `status`, the email `domains` it signs in, `created_at`, and `updated_at`. | | `next_cursor` | The cursor of the next page, or `null` on the last page. | ## Permissions [#permissions] SSO requests require a signed-in user token and do not accept [API keys](/docs/api-keys). SSO configuration is governed by two organization permissions, which you can grant through an [organization role](/docs/organizations#roles): | **Permission** | **Grants** | | --------------- | ----------------------------------------- | | **`read:sso`** | List SSO connections | | **`write:sso`** | Create SSO and directory sync setup links | # Limits (/docs/limits) Daytona enforces three kinds of limits: [sandbox limits](#sandbox-limits), which cap the resources a single sandbox can reserve, [organization limits](#organization-limits), which cap how many sandboxes, image builds, volumes, images, snapshots, members, secrets, and API keys an organization can hold, and [rate limits](#rate-limits), which cap how many API requests a project can make within a time window. For information on spending and wallet management, see [billing](/docs/billing). ## Sandbox limits [#sandbox-limits] Sandbox limits cap the CPU, memory, and disk a single sandbox can reserve. The limits apply per sandbox, not as a shared pool across the organization. | **Resource** | **Unit** | **Default** | **Minimum** | **Maximum** | | ------------ | -------- | ----------- | --------------------------------- | ------------ | | CPU | Cores | `0.5` | **`0.125`** (when set explicitly) | **`16`** | | Memory | MiB | `1024` | **`512`** (when set explicitly) | **`32768`** | | Disk | MiB | `512` | **`10240`** (when set explicitly) | **`262144`** | A create request that reserves more than the maximum on any axis is rejected with a 400 error that names the exceeded cap. Requests below the minimum are raised to the minimum. The minimums apply once a create sets any of CPU, memory, or disk; a create that sets none keeps the defaults. A request raised above a limit set in the same create is rejected with a 400 error. Guaranteed CPU is also raised to at least one core per 8 GiB of guaranteed memory. A sandbox may additionally set per-sandbox limits on cores (a multiple of 0.5, between 0.5 and 16), memory in MiB (between 256 and 32768), and disk in MiB (between 512 and 262144), which can only lower the boot shape below the platform maximum. See [sandbox resources](/docs/sandboxes#resources). The [plan](/docs/billing#get-the-plan) of the organization can cap the cores and memory of a Linux sandbox below the platform maximum: | **Plan** | **Cores** | **Memory (MiB)** | | ---------- | ------------ | ---------------- | | Starter | **`4`** | **`16384`** | | Team | **`8`** | **`32768`** | | Enterprise | **`64`** | **`262144`** | The Enterprise caps are above the platform maximum, so the platform maximum applies. The plan caps apply to both the guarantee and the per-sandbox limits. A request above a plan cap is rejected with a 400 error that names the plan limit, and an omitted per-sandbox limit defaults to the plan cap. The plan response reports the core and memory caps of the organization. ## Organization limits [#organization-limits] Organization limits cap the number of sandboxes, image builds, volumes, images, snapshots, and members across every project in an organization, and the number of secrets and API keys. Each limit is a ceiling, not a reservation: reaching it refuses new work, but nothing is set aside. A request that would exceed a limit is rejected with a 429 error with the code LIMIT_EXCEEDED that names the limit, the current count, and the maximum. | **Limit** | **What it counts** | **Checked on** | **Name in errors** | | ------------------------- | -------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | ----------------------- | | `sandboxes.concurrent` | Sandboxes that hold or are about to hold compute: queued, pending, assigned, booting, running, pausing, stopping, or deleting | Create, fork, snapshot restore, start, resume | `max_concurrent_vms` | | `sandboxes.total` | Concurrent sandboxes plus stopped and paused sandboxes. Deleted, failed, and lost sandboxes do not count | Create, fork, snapshot restore | `max_total_vms` | | `image_builds.concurrent` | Image builds that are pending or building | Image build | `max_concurrent_builds` | | `storage.volumes` | Volumes. Deleted volumes do not count | Volume create | `max_volumes` | | `storage.images` | Captured, built, and imported images. Failed images do not count | Image build, capture, and import | `max_images` | | `storage.snapshots` | Snapshots. Failed snapshots do not count | Snapshot create | `max_snapshots` | | `members` | Organization members. A pending invitation holds a member slot until it is accepted or declined | Member invitation | `max_members` | | `secrets_per_project` | Secrets in one project. The response reports the highest count in any project | Secret create | `secrets_per_project` | | `api_keys_per_project` | Live API keys in one project. Revoked and expired keys do not count. The response reports the highest count in any project | Project API key create | `api_keys_per_project` | | `api_keys_per_organization` | Live organization API keys. Revoked and expired keys do not count | Organization API key create | `api_keys_per_organization` | ### Get organization limits [#get-organization-limits] Daytona provides methods to get the limits of an organization and the current usage counted against each one. Each limit in the response carries the effective cap and the current usage. When no limit applies, the cap is null. An API key reads the limits of its own organization, and its response leaves out the member counts. ```python from daytona import Daytona daytona = Daytona() limits = daytona.v2.get_limits() print(limits.sandboxes.concurrent.usage, limits.sandboxes.concurrent.limit) ``` | **Parameter** | **Type** | **Description** | | ----------------- | -------- | ------------------------------------------------------------------------------------------------------------ | | `organization_id` | str | Sets the organization to read. Defaults to the organization of the API key; required with JWT authentication. | - The request requires the `read:limits` permission with an API key, or the `read:organization` permission when signed in. ```typescript import { Daytona } from '@daytona/sdk' const daytona = new Daytona() const limits = await daytona.v2.getLimits() console.log(limits.sandboxes.concurrent.usage, limits.sandboxes.concurrent.limit) ``` | **Parameter** | **Type** | **Description** | | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------ | | `organizationId` | string | Sets the organization to read. Defaults to the organization of the API key; required with JWT authentication. | - The request requires the `read:limits` permission with an API key, or the `read:organization` permission when signed in. ```bash daytona org limits ``` | **Argument** | **Type** | **Description** | | ------------ | -------- | ------------------------------------------------------------------------------- | | `id\|name` | string | Sets the organization to read by ID or name. The default is the selected organization. | - The request requires the `read:limits` permission with an API key, or the `read:organization` permission when signed in. ```bash curl 'https://api.daytona.com/orgs/YOUR_ORG_ID/limits' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` | **Field** | **Type** | **Description** | | ----------- | -------- | ------------------------------------------------------- | | `org_id` | string | Identifies the organization to read. Path parameter. | - The request requires the `read:limits` permission with an API key, or the `read:organization` permission when signed in. ## Rate limits [#rate-limits] Rate limits control how many API requests you can make within a fixed 60 second window. Requests authenticated with an [API key](/docs/api-keys) are counted per project: every API key in a project draws on the same budget, so adding keys does not raise the limit. Requests are counted per organization with an [organization API key](/docs/api-keys#organization-api-keys), per user from the Daytona Dashboard, and per sandbox with a sandbox-scoped token. Daytona also blocks a client IP address for a window after repeated requests with invalid credentials. Requests that carry a valid API key are not affected by this block. ### Rate limit headers [#rate-limit-headers] When Daytona enforces the request rate limit, it includes rate limit information in the response headers of every authenticated request. A response without these headers was not counted against the request rate limit. The header names carry an authenticated suffix, which identifies the rate limit bucket: | **Header** | **Description** | | -------------------------------------- | ---------------------------------------------------------------------------- | | `X-RateLimit-Limit-authenticated` | Maximum number of requests allowed in the time window | | `X-RateLimit-Remaining-authenticated` | Number of requests remaining in the current window | | `X-RateLimit-Reset-authenticated` | Time in seconds until the rate limit window resets | | `Retry-After` | Time in seconds to wait before retrying. Sent on `429` responses except `LIMIT_EXCEEDED`, and on some `503` responses | ### Rate limit errors [#rate-limit-errors] Daytona returns HTTP 429 Too Many Requests for the following conditions. The code field in the response body identifies the condition. Use it, not the presence of headers, to decide how to react. | **`code`** | **Cause** | **Retry** | | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | | `RATE_LIMITED` | The request rate limit for the project, organization, user, or sandbox was exceeded | Wait for the seconds in `Retry-After`, then retry | | `RATE_LIMITED` | Too many requests with invalid credentials from the same IP address; the message is `too many failed authentication attempts` | Fix the credentials; the block lifts after the seconds in `Retry-After` | | `OVERLOADED` | The sandbox creation queue or the organization's admission queue is at capacity (returned by sandbox create, fork, start, resume, and image build) | Wait for the seconds in `Retry-After`, then retry | | `LIMIT_EXCEEDED` | An [organization limit](#organization-limits) is reached | Free capacity under the named limit, for example stop or delete sandboxes, wait for builds to finish, or delete volumes, images, or snapshots; the response carries no `Retry-After` | | `TOO_MANY_REQUESTS` | A generic `429` with no more specific code | Wait for the seconds in `Retry-After` when present, then retry | The error response is a JSON object with the following properties: | **Property** | **Description** | | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | **`code`** | The error code. | | **`message`** | The error message. | | **`source`** | The component that produced the error, `DAYTONA_API`. | | **`retry_after_seconds`** | Seconds to wait before retrying, also sent as the `Retry-After` header. Present on `RATE_LIMITED` and `OVERLOADED` responses. | | **`limit`** | On `LIMIT_EXCEEDED` responses, the limit hit, such as `max_concurrent_vms`. | | **`current`** | The organization's current count for `limit`. Present on `LIMIT_EXCEEDED` responses. | | **`max`** | The organization's value for `limit`. Present on `LIMIT_EXCEEDED` responses. | | **`trace_id`** | The request trace ID. | ```json { "code": "RATE_LIMITED", "message": "request rate limit exceeded; retry after the indicated delay", "source": "DAYTONA_API", "retry_after_seconds": 42, "trace_id": "0af7651916cd43dd8448eb211c80319c" } ``` The [Python](/docs/python-sdk) and [TypeScript](/docs/typescript-sdk) SDKs raise or throw a rate limit error for every 429 response, including the overloaded condition. A response for an exceeded limit raises a subclass of the rate limit error that also exposes the limit, the current usage, and the maximum. All SDK errors expose the HTTP status code, the error code, and the message: ```python from daytona import Daytona from daytona.v2 import LimitExceededError, RateLimitError daytona = Daytona() try: daytona.v2.create_from_snapshot("my-snapshot") except LimitExceededError as e: print(e.limit, e.current, e.max) except RateLimitError as e: print(e.status_code, e.code, e.message) ``` - The SDK does not retry a 429 response. - On rate limited and overloaded errors, read `retry_after_seconds` on the error for the seconds to wait before retrying. ```typescript import { Daytona } from '@daytona/sdk' import { LimitExceededError, RateLimitError } from '@daytona/sdk/v2' const daytona = new Daytona() try { await daytona.v2.createFromSnapshot('my-snapshot') } catch (error) { if (error instanceof LimitExceededError) { console.log(error.limit, error.current, error.max) } else if (error instanceof RateLimitError) { console.log(error.statusCode, error.code, error.message) } } ``` - The SDK does not retry a 429 response. - On rate limited and overloaded errors, read `retryAfterSeconds` on the error for the seconds to wait before retrying. ```bash # Rate limit headers are returned while the request rate limit is enforced curl -i 'https://api.daytona.com/sandboxes' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` ```text HTTP/1.1 200 OK x-ratelimit-limit-authenticated: 100 x-ratelimit-remaining-authenticated: 97 x-ratelimit-reset-authenticated: 42 ``` ```text HTTP/1.1 429 Too Many Requests retry-after: 42 x-ratelimit-limit-authenticated: 100 x-ratelimit-remaining-authenticated: 0 x-ratelimit-reset-authenticated: 42 ``` ## Best practices [#best-practices] Best practices keep a client within its limits and help it recover when a request is refused. - **Wait before retrying a 429 response.** Wait for the number of seconds in the `Retry-After` header, or in the `retry_after_seconds` field of the body, before retrying. If a retry is rejected again, back off exponentially (1s, 2s, 4s, 8s, and so on) instead of retrying at a fixed interval. - **Monitor rate limit headers.** The [rate limit headers](#rate-limit-headers) `X-RateLimit-Remaining-authenticated` and `X-RateLimit-Reset-authenticated` track how much of the budget is left in the current window. Throttle the client before it reaches the limit, and do not treat a response without these headers as an error. - **Distinguish `RATE_LIMITED` from `OVERLOADED`.** A `RATE_LIMITED` response means the project, organization, user, or sandbox sent too many requests; slow down the caller. An `OVERLOADED` response means the sandbox creation queue or the organization's admission queue is full; retry after the delay without reducing your request rate elsewhere. - **Do not retry `LIMIT_EXCEEDED` on a timer.** The request succeeds only after the count for the named `limit` drops below `max`. Stopping or deleting sandboxes frees concurrent slots once the sandbox leaves the stopping or deleting state; only deleting sandboxes frees `max_total_vms` slots. Build slots free when image builds finish. Deleting volumes, images, or snapshots frees their slots. - **Cache API responses.** Cache responses that change infrequently, such as [sandbox lists](/docs/sandboxes#list-sandboxes), [available regions](/docs/regions), and [snapshot information](/docs/snapshots), to avoid unnecessary requests. - **Avoid tight polling loops.** Poll for state changes at an interval within the remaining budget, and monitor your logs for `429` errors to catch rate limiting before it affects users. ## Permissions [#permissions] Organization limits can be read with a project API key or by a signed-in member. Every role includes the organization read permission. | **Permission** | **Grants** | | ----------------------- | ---------------------------------------------- | | **`read:limits`** | Get organization limits with a project API key | | **`read:organization`** | Get organization limits when signed in | # Billing (/docs/billing) Daytona provides an overview of your organization's [wallet](#wallet) and [spending](#spending). Daytona uses a pay-as-you-go billing model where you are charged for the resources your sandboxes use, with the guaranteed resources you reserve as a floor. For information on sandbox resource limits and rate limits, see [limits](/docs/limits). Billing is scoped to the organization. ## Sandbox billing [#sandbox-billing] Daytona meters each sandbox per second for three resources, from the moment the sandbox starts until it is stopped, paused, or deleted. Each resource is priced per hour. macOS sandboxes are not metered; their [Mac reservation](/docs/macos-sandboxes#mac-reservations) is charged instead. | **Resource** | **Unit** | **Billed quantity** | | ------------ | --------- | -------------------------------------------------------------------------------------------- | | **CPU** | core-hour | The greater of measured CPU time and the guaranteed `cpu` reservation over the same window | | **Memory** | GiB-hour | The greater of measured memory and the guaranteed `memory_mib` reservation over the same window | | **Disk** | GiB-hour | Measured disk in use | CPU and memory usage within the guarantee is billed at the guarantee; usage above it, up to the sandbox's [resource limits](/docs/limits#sandbox-limits), is billed as measured. A sandbox with a fixed shape, where every limit equals its request, is billed for its full CPU and memory reservation, since usage never exceeds it. Disk is always billed as measured. Stopped, paused, and deleted sandboxes are not metered for CPU, memory, or disk. [Bucket volume](/docs/volumes) traffic is billed per uploaded GiB, downloaded GiB, and 1,000 requests, independent of sandbox class. ### Pricing dimensions [#pricing-dimensions] The price of each resource depends on what you requested at create time. Each dimension applies a multiplier to the base price; the multipliers compound. The CPU type multiplier applies to CPU usage only. | **Dimension** | **Parameter** | **Values** | | ----------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | Region | `region` | Each region's own multiplier; `earth` (`1.0`) is the base price. See [region price multipliers](/docs/regions#list-region-price-multipliers) | | Spot | `spot` | `false` (`1.0`), `true` (`0.7`) | | CPU type | `cpu_type` | Not requested, `zen3`, `arrowlake1`, `graviton`, `graviton3`, `graviton4` (`1.0`); `zen4`, `arrowlake2` (`1.6667`); `zen5`, `zen5c` (`2.3313`) | A sandbox that omits a hardware preference is billed at the baseline for that dimension, even if placement lands on premium hardware. Forked and restored sandboxes inherit the preferences of their source. See [Linux sandbox parameters](/docs/linux-sandboxes#create-a-linux-sandbox) for how to set these values. ## Plan [#plan] ### Get the plan [#get-the-plan] Get the plan: the organization's current plan, its limits and entitlements, and any pending change. The plan catalog lists the plans an organization can choose. ```bash daytona billing plan get --org ORGANIZATION_ID # Plan catalog daytona billing plan list --org ORGANIZATION_ID ``` ```bash curl 'https://api.daytona.com/orgs/ORGANIZATION_ID/billing/plan' \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' # Plan catalog curl 'https://api.daytona.com/orgs/ORGANIZATION_ID/billing/plans' \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' ``` ### Change the plan [#change-the-plan] Change the plan. Self-serve changes move an organization between the Starter and Team plans; the Enterprise plan is arranged with sales. The Team plan has a monthly fee of $250, billed in advance, and includes $100 of credits each month that expire at the end of the billing period. A change to Team applies immediately; a pre-paid organization needs a payment method on file first. A change from Team to Starter takes effect at the end of the billing period and shows as pending until then. ```bash # starter or team daytona billing plan set team --org ORGANIZATION_ID ``` ```bash curl 'https://api.daytona.com/orgs/ORGANIZATION_ID/billing/plan' \ --request PUT \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "plan": "team" }' ``` | **Field** | **Type** | **Description** | | --------- | -------- | --------------- | | `plan` | string | Sets the plan: `starter` or `team`. The value `enterprise` returns `400` with `contact_sales`. A change to `team` for a pre-paid organization requires a payment method. | ## Wallet [#wallet] [Daytona Wallet ↗](https://app.daytona.com/dashboard/billing/wallet) is the central hub for managing your organization's wallet, including balances, credit consumption, and payment methods. New organizations are provisioned with the billing provider within a few minutes of creation; until then the wallet shows a provisioning notice. ### Redeem coupon [#redeem-coupon] Redeem a coupon to add free credits to your wallet. Each coupon can be redeemed once per organization. Coupon credits may carry an expiration date, shown in [credit balances](#credit-balances). 1. Go to [Daytona Wallet ↗](https://app.daytona.com/dashboard/billing/wallet) 2. Navigate to the **Redeem coupon** section 3. Enter the coupon code 4. Click ```bash daytona billing coupon redeem COUPON_CODE --org ORGANIZATION_ID ``` ```bash curl 'https://api.daytona.com/orgs/ORGANIZATION_ID/billing/coupons/redeem' \ --request POST \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "code": "COUPON_CODE" }' ``` ### Balance [#balance] Balance displays the credit balances available to your organization. | **Field** | **Description** | | ------------------------- | ------------------------------------------------------------------------- | | **Total balance** | The sum of free and paid credits. | | **Free credits** | The amount of granted credits, such as coupons or card-connected credits. | | **Paid credits** | The amount of purchased credits. | | **Spent this month** | Usage charged in the current billing period. | | **Amount due this month** | The open amount of the current invoice, shown only when non-zero. | Daytona consumes free credits before paid credits. When both balances are exhausted, the paid balance shows the amount due as a negative number. 1. Go to [Daytona Wallet ↗](https://app.daytona.com/dashboard/billing/wallet) 2. Navigate to the **Balance** section ```bash daytona billing wallet --org ORGANIZATION_ID ``` ```bash curl 'https://api.daytona.com/orgs/ORGANIZATION_ID/billing/wallet' \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' ``` ```json { "balance_cents": 12500, "free_credits_balance_cents": 2500, "paid_credits_balance_cents": 10000, "total_spent_this_month_cents": 4321, "total_amount_due_this_month_cents": 0, "currency": "usd", "billing_type": "pre-paid", "automatic_top_up": { "enabled": true, "threshold_cents": 2000, "target_cents": 10000, "currency": "usd" } } ``` ### Credit balances [#credit-balances] Credit balances itemizes every credit grant and top-up. | **Field** | **Description** | | -------------- | ------------------------------------ | | **Name** | The grant or top-up. | | **Type** | Free or paid. | | **Remaining** | The unspent amount. | | **Granted** | The original amount. | | **Expires** | The expiration date, if any. | | **Applies to** | The products the credit can pay for. | 1. Go to [Daytona Wallet ↗](https://app.daytona.com/dashboard/billing/wallet) 2. Navigate to the **Credit Balances** section 3. Click ```bash # Paginated; pass the returned next_cursor as --cursor for more rows, or --all for every page daytona billing balances --org ORGANIZATION_ID --limit 25 ``` | **Flag** | **Type** | **Description** | | --------- | -------- | --------------------------------------------------------------- | | `--limit` | int | Sets the maximum number of rows. The default is `25`. | ```bash # Paginated; follow next_cursor for more rows curl 'https://api.daytona.com/orgs/ORGANIZATION_ID/billing/balances?limit=25' \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' ``` | **Field** | **Type** | **Description** | | ----------- | --------- | -------------------------------------------------------------------- | | `limit` | integer | Sets the maximum number of items, from `1` to `200`. The default is `100`. | | `cursor` | string | Pass the `next_cursor` value of the previous response to read the next page. | ### Balance notification [#balance-notification] Balance notification emails the organization's billing contact when the wallet balance drops below a threshold, or the creator's email when no billing contact is set. The threshold is in cents, from 500 to 5,000,000. 1. Go to [Daytona Wallet ↗](https://app.daytona.com/dashboard/billing/wallet) 2. Navigate to the **Balance notification** section 3. Enable the notification and set the threshold 4. Click ```bash # Threshold in cents daytona billing balance-notification set --threshold-cents 1000 --org ORGANIZATION_ID # Billing contact for notifications and receipts daytona billing contact set --email finance@example.com --org ORGANIZATION_ID # Read the current rule daytona billing balance-notification get --org ORGANIZATION_ID # Read the billing contact daytona billing contact get --org ORGANIZATION_ID # Turn off the notification daytona billing balance-notification delete --org ORGANIZATION_ID ``` - Reading the notification and the billing contact requires the `read:billing` permission. - Setting or removing them requires the `write:billing` permission. ```bash # Threshold in cents curl 'https://api.daytona.com/orgs/ORGANIZATION_ID/billing/balance-notification' \ --request PUT \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "threshold_cents": 1000 }' # Billing contact for notifications and receipts curl 'https://api.daytona.com/orgs/ORGANIZATION_ID/billing/contact' \ --request PUT \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "email": "finance@example.com" }' # Read the current rule: { "enabled": true, "threshold_cents": 1000, "currency": "usd" } curl 'https://api.daytona.com/orgs/ORGANIZATION_ID/billing/balance-notification' \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' # Read the billing contact. effective_email is the address mail goes to: email, or the creator's email when unset curl 'https://api.daytona.com/orgs/ORGANIZATION_ID/billing/contact' \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' # Turn off the notification curl 'https://api.daytona.com/orgs/ORGANIZATION_ID/billing/balance-notification' \ --request DELETE \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' ``` - Reading the notification and the billing contact requires the `read:billing` permission. - Setting or removing them requires the `write:billing` permission. ### Billing information [#billing-information] Billing information displays the name, email, phone number, and address on file with the payment provider. It is read-only in the dashboard; edit it through the billing portal. 1. Go to [Daytona Wallet ↗](https://app.daytona.com/dashboard/billing/wallet) 2. Navigate to the **Billing info** section 3. Click to open the billing portal ```bash daytona billing profile --org ORGANIZATION_ID ``` ```bash curl 'https://api.daytona.com/orgs/ORGANIZATION_ID/billing/profile' \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' ``` ### Payment method [#payment-method] Payment method connects your wallet to a card, allowing you to add funds to your balance and pay invoices. Payment methods are managed through the hosted billing portal. Personal organizations receive a one-time grant of free credits when the first card is connected, and another when the creator verifies their email address. 1. Go to [Daytona Wallet ↗](https://app.daytona.com/dashboard/billing/wallet) 2. Navigate to the **Payment methods** section 3. Click , or if a card is already on file 4. Follow the prompts in the billing portal ```bash daytona billing payment-methods --org ORGANIZATION_ID # Hosted checkout URL for adding a payment method daytona billing payment-method-session --org ORGANIZATION_ID # Hosted billing portal URL for managing payment methods and billing details daytona billing portal-session --org ORGANIZATION_ID ``` - Listing payment methods requires the `read:billing` permission. - Opening a payment method session or a billing portal session requires the `write:billing` permission. ```bash curl 'https://api.daytona.com/orgs/ORGANIZATION_ID/billing/payment-methods' \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' # Hosted checkout URL for adding a payment method curl 'https://api.daytona.com/orgs/ORGANIZATION_ID/billing/payment-method-sessions' \ --request POST \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' # Hosted billing portal URL for managing payment methods and billing details curl 'https://api.daytona.com/orgs/ORGANIZATION_ID/billing/portal-sessions' \ --request POST \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' ``` - Listing payment methods requires the `read:billing` permission. - Opening a payment method session or a billing portal session requires the `write:billing` permission. ### Automatic top-up [#automatic-top-up] Automatic top-up adds credits to your wallet when the balance drops below a threshold. Amounts are in cents: the threshold must be at least 1000 cents ($10), and the target must exceed the threshold by at least 1000 cents. Automatic top-up is available for pre-paid organizations and is disabled automatically after a failed payment; update the payment method and enable it again. 1. Go to [Daytona Wallet ↗](https://app.daytona.com/dashboard/billing/wallet) 2. Navigate to the **Automatic top-up** section 3. Add or update the **when balance is low** and **bring balance to** values 4. Click ```bash # Amounts in cents daytona billing automatic-top-up set --threshold-cents 2000 --target-cents 10000 --org ORGANIZATION_ID # Read the current rule daytona billing automatic-top-up get --org ORGANIZATION_ID # Turn off automatic top-up daytona billing automatic-top-up delete --org ORGANIZATION_ID ``` - Reading the setting requires the `read:billing` permission. - Changing or removing the setting requires the `write:billing` permission. ```bash # Amounts in cents curl 'https://api.daytona.com/orgs/ORGANIZATION_ID/billing/automatic-top-up' \ --request PUT \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "threshold_cents": 2000, "target_cents": 10000 }' # Read the current rule: { "enabled": true, "threshold_cents": 2000, "target_cents": 10000, "currency": "usd" } curl 'https://api.daytona.com/orgs/ORGANIZATION_ID/billing/automatic-top-up' \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' # Turn off automatic top-up curl 'https://api.daytona.com/orgs/ORGANIZATION_ID/billing/automatic-top-up' \ --request DELETE \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' ``` - Reading the setting requires the `read:billing` permission. - Changing or removing the setting requires the `write:billing` permission. ### One time top-up [#one-time-top-up] One time top-up buys wallet credits by card on a hosted checkout page. The minimum is $10 (1000 cents) and the maximum $999,999.99. A payment method must be on file. 1. Go to [Daytona Wallet ↗](https://app.daytona.com/dashboard/billing/wallet) 2. Navigate to the **One-time top-up** section 3. Select a preset amount or enter a custom amount 4. Click 5. Complete the payment on the checkout page ```bash # Amount in cents; returns a checkout URL daytona billing top-up 5000 --org ORGANIZATION_ID ``` ```bash # Amount in cents; returns a checkout URL curl 'https://api.daytona.com/orgs/ORGANIZATION_ID/billing/top-up-sessions' \ --request POST \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "amount_cents": 5000 }' ``` ### Invoices [#invoices] Invoices are generated per billing period and for each top-up. | **Field** | **Description** | | ------------ | -------------------------------- | | **Number** | The invoice identifier. | | **Date** | The date the invoice was issued. | | **Due date** | The date the invoice is due. | | **Total** | The amount of the invoice. | | **Status** | The status of the invoice. | | **Type** | The type of the invoice. | An unpaid invoice shows a warning with a **Pay** button. If a pre-paid organization leaves an invoice unpaid past the grace period, the organization is [suspended](#suspension) until it is paid. Post-paid organizations with a contract are never suspended for unpaid invoices. 1. Go to [Daytona Wallet ↗](https://app.daytona.com/dashboard/billing/wallet) 2. Navigate to the **Invoices** section 3. Click to open the invoice PDF, or for an open invoice ```bash daytona billing invoices --org ORGANIZATION_ID daytona billing invoices --unpaid --org ORGANIZATION_ID daytona billing invoice pdf INVOICE_ID --org ORGANIZATION_ID --out invoice.pdf # Payment URL for an open invoice daytona billing invoice payment-session INVOICE_ID --org ORGANIZATION_ID ``` - Listing invoices and downloading their PDFs requires the `read:billing` permission. - Paying an invoice requires the `write:billing` permission. ```bash curl 'https://api.daytona.com/orgs/ORGANIZATION_ID/billing/invoices' \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' curl 'https://api.daytona.com/orgs/ORGANIZATION_ID/billing/invoices?unpaid=true' \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' curl 'https://api.daytona.com/orgs/ORGANIZATION_ID/billing/invoices/INVOICE_ID/pdf' \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' \ --output invoice.pdf # Payment URL for an open invoice curl 'https://api.daytona.com/orgs/ORGANIZATION_ID/billing/invoices/INVOICE_ID/payment-sessions' \ --request POST \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' ``` - Listing invoices and downloading their PDFs requires the `read:billing` permission. - Paying an invoice requires the `write:billing` permission. ### Charges [#charges] Charges displays all payment attempts on your organization, including failed attempts. A receipt PDF is available for each successful charge. | **Field** | **Description** | | --------------- | ---------------------------------- | | **Date** | The date the charge was attempted. | | **Description** | The description of the charge. | | **Amount** | The amount of the charge. | | **Status** | The status of the charge. | ```bash daytona billing charges --org ORGANIZATION_ID ``` ```bash curl 'https://api.daytona.com/orgs/ORGANIZATION_ID/billing/charges' \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' curl 'https://api.daytona.com/orgs/ORGANIZATION_ID/billing/charges/CHARGE_ID/pdf' \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' \ --output receipt.pdf ``` ## Spending [#spending] [Daytona Spending ↗](https://app.daytona.com/dashboard/spending) provides a summary of resource usage for the selected project and the organization's billing periods. Reading usage requires the spending read [permission](/docs/api-keys#scopes). ### Resource usage [#resource-usage] Resource usage summarizes the selected project's measured usage over a date range. | **Metric** | **Description** | | --------------- | -------------------------------- | | **CPU** | Total CPU time, in core-seconds. | | **Memory** | Total memory, in GiB-hours. | | **Network** | Total bytes sent and received. | | **Disk (peak)** | The highest disk usage observed. | 1. Go to [Daytona Spending ↗](https://app.daytona.com/dashboard/spending) 2. Select a project and a date range ```bash # Hourly usage for the project over the last day (default) curl 'https://api.daytona.com/usage/report' \ --header 'Authorization: Bearer YOUR_API_KEY' # Daily usage for a date range curl 'https://api.daytona.com/usage/report?start_at=2026-09-01T00:00:00Z&end_at=2026-09-08T00:00:00Z&resolution=day' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` | **Field** | **Type** | **Description** | | ------------ | -------- | ---------------------------------------------------------------------------------------------------------------- | | `start_at` | string | Sets the inclusive start of the window as an RFC 3339 timestamp. The default is 24 hours before `end_at`. | | `end_at` | string | Sets the exclusive end of the window as an RFC 3339 timestamp. The default is now. | | `resolution` | string | Sets the resolution, `hour` or `day`. The default is `hour`. | ### Usage timeline [#usage-timeline] Usage timeline charts one metric over the selected range: CPU, memory, or network. ### Per-sandbox usage [#per-sandbox-usage] Per-sandbox usage displays the same measurements broken down by sandbox: **Sandbox**, **CPU core-s**, **Memory GiB-h**, **Network**, and **Disk (peak)**. ```bash # Live usage for one sandbox daytona sandbox usage SANDBOX_ID # Usage history for one sandbox, per minute; the CLI has no hourly resolution daytona sandbox usage SANDBOX_ID --history ``` ```bash # Live usage for one sandbox curl 'https://api.daytona.com/sandboxes/SANDBOX_ID/usage' \ --header 'Authorization: Bearer YOUR_API_KEY' # Usage history for one sandbox, per minute or per hour curl 'https://api.daytona.com/sandboxes/SANDBOX_ID/usage/history?resolution=hour' \ --header 'Authorization: Bearer YOUR_API_KEY' ``` | **Field** | **Type** | **Description** | | ------------ | -------- | ----------------------------------------------------------------------- | | `resolution` | string | Sets the resolution, `minute` or `hour`. The default is `minute`. | | `start_at` | string | Sets the inclusive start of the window as an RFC 3339 timestamp. The default is 24 hours before `end_at`. | | `end_at` | string | Sets the exclusive end of the window as an RFC 3339 timestamp. The default is now. | ### Billing period [#billing-period] Billing period shows the amount owed per product for the current and past periods. - **Metric**, **Product**, **Units**, **Cost**: the current period's charges per resource and sandbox class - **Period**, **Issued**, **Total**: the closed past periods ```bash # Current billing period daytona billing usage --org ORGANIZATION_ID # Billing periods, newest first daytona billing usage-periods --org ORGANIZATION_ID --limit 3 ``` | **Flag** | **Type** | **Description** | | --------- | -------- | --------------- | | `--limit` | int | Sets the maximum number of periods. The default is `12`. | ```bash # Billing periods, newest first; the open period is the current one curl 'https://api.daytona.com/orgs/ORGANIZATION_ID/billing/usage-periods?limit=3' \ --header 'Authorization: Bearer YOUR_OIDC_TOKEN' ``` ```json { "usage_periods": [ { "status": "open", "start_at": "2026-09-01T00:00:00Z", "end_at": "2026-10-01T00:00:00Z", "issued_at": "2026-10-01T00:00:00Z", "currency": "usd", "amount_cents": 12345, "total_amount_cents": 12400, "taxes_amount_cents": 0, "charges": [ { "name": "CPU · Linux VM", "quantity": 342.9, "total_cents": 12345 } ] } ], "next_cursor": null } ``` | **Field** | **Type** | **Description** | | --------- | --------- | --------------- | | `limit` | integer | Sets the maximum number of periods. | | `cursor` | string | Reads the next page. Pass the `next_cursor` value of the previous response. | ## Suspension [#suspension] Daytona suspends a pre-paid organization when its balance is depleted or when an invoice stays unpaid past the grace period. While suspended, creating, starting, resuming, restoring, and forking sandboxes fails with HTTP 402 and an organization suspended error; already running sandboxes are not affected. The suspension lifts automatically once its cause is resolved: a top-up or coupon that restores the balance, or payment of the unpaid invoice. The dashboard shows the suspension and its reason on the wallet page. ## Permissions [#permissions] Billing is scoped to the organization. Access is governed by two organization permissions, which you can grant through an [organization role](/docs/organizations#roles), and usage reports use the spending permission. Billing requests require a signed-in user token. An [organization API key](/docs/api-keys#organization-api-keys) can hold the billing permissions, but they only authorize it to list the [region price multipliers](/docs/regions#list-region-price-multipliers). Reading the usage of a single sandbox requires the permission to read sandboxes. | **Permission** | **Grants** | | ------------------- | ------------------------------------------------------------------------------------------------------ | | **`read:billing`** | Get the plan, wallet, balances, invoices, charges, payment methods, and billing settings | | **`write:billing`** | Change the plan, redeem coupons, top up, pay invoices, and change payment methods and billing settings | | **`read:spending`** | Read resource usage and the budget of the project | # Python SDK Reference (/docs/python-sdk) The Daytona Python SDK provides two root clients for interacting with Daytona Sandboxes: - `Daytona`: synchronous client; each call blocks until it completes - `AsyncDaytona`: asynchronous client with the same methods; methods are coroutines and must be awaited Every operation goes through a version namespace: `daytona.v2` for the Daytona v2 API, or `daytona.v0` for the Daytona v0 API. The root client is the only way to build a namespace client. Resource types such as `Sandbox` and `ImageBuilder` are imported from `daytona.v2`. ## Installation [#installation] Install the Daytona Python SDK using pip. The SDK requires Python 3.10 or later. ```bash pip install daytona==2.0.0a11 ``` Install the extras for OpenTelemetry request spans or the `daytona.v0` namespace: ```bash pip install 'daytona[otel]==2.0.0a11' pip install 'daytona[v0-sdk]==2.0.0a11' ``` ## Getting Started [#getting-started] ### Create a Sandbox [#create-a-sandbox] Create a Daytona Sandbox to run your code securely in an isolated environment. The following snippet is an example "Hello World" program that runs securely inside a Daytona Sandbox. ```python from daytona import Daytona def main(): # Initialize the SDK (reads DAYTONA_API_KEY from the environment) with Daytona() as daytona: # Create a new sandbox sandbox = daytona.v2.create(wait_seconds=60) # Execute a command result = sandbox.exec("echo 'Hello, World!'") print(result.output) daytona.v2.delete(sandbox) if __name__ == "__main__": main() ``` ```python import asyncio from daytona import AsyncDaytona async def main(): # Initialize the SDK (reads DAYTONA_API_KEY from the environment) async with AsyncDaytona() as daytona: # Create a new sandbox sandbox = await daytona.v2.create(wait_seconds=60) # Execute a command result = await sandbox.exec("echo 'Hello, World!'") print(result.output) await daytona.v2.delete(sandbox) if __name__ == "__main__": asyncio.run(main()) ``` `with Daytona(...)` and `async with AsyncDaytona(...)` release the client's connections when the block ends. Close the root client, not `daytona.v2` directly: a namespace client closed on its own stays cached and fails on later calls. ## Configuration [#configuration] The Daytona SDK can be configured using environment variables or by passing a `DaytonaConfig` to the constructor. Fields left unset are read from the environment. Configure exactly one credential: `api_key`, or `jwt_token` scoped with `project_id` for `daytona.v2` or `organization_id` for `daytona.v0`. - `api_key`: a project API key; falls back to `DAYTONA_API_KEY` - `jwt_token`: a signed-in user's JWT, exchanged for a short-lived project-scoped token; falls back to `DAYTONA_JWT_TOKEN` - `project_id`: scopes `jwt_token` to a project for `daytona.v2`; falls back to `DAYTONA_PROJECT_ID` - `organization_id`: scopes `jwt_token` to an organization for `daytona.v0`; falls back to `DAYTONA_ORGANIZATION_ID` - `request_timeout`: per-request HTTP timeout in seconds for `daytona.v2` - `connection_pool_maxsize`: maximum number of live and keep-alive HTTP connections - `otel_enabled`: emits client spans when `daytona[otel]` is installed; falls back to `DAYTONA_OTEL_ENABLED` `DaytonaConfig` has no API URL or region field, and passing `api_url` or `toolbox_url` raises a `TypeError`. Pass `region=` to each `daytona.v2` create. `DAYTONA_V2_API_URL`, else `DAYTONA_API_URL`, overrides the `daytona.v2` API endpoint; `daytona.v0` ignores both. The `target` field is deprecated and applies only to `daytona.v0`. ```python from daytona import Daytona, DaytonaConfig # Using environment variables (DAYTONA_API_KEY) with Daytona() as daytona: sandbox = daytona.v2.create() # Using explicit configuration config = DaytonaConfig( api_key="YOUR_API_KEY", request_timeout=30, ) with Daytona(config) as daytona: sandbox = daytona.v2.create(region="us") ``` ```python import asyncio from daytona import AsyncDaytona, DaytonaConfig async def main(): # Using environment variables (DAYTONA_API_KEY) async with AsyncDaytona() as daytona: sandbox = await daytona.v2.create() # Using explicit configuration config = DaytonaConfig( api_key="YOUR_API_KEY", request_timeout=30, ) async with AsyncDaytona(config) as daytona: sandbox = await daytona.v2.create(region="us") if __name__ == "__main__": asyncio.run(main()) ``` For more information on configuring the Daytona SDK, see [authentication](/docs/authentication). See the [`DaytonaConfig` reference](/docs/python-sdk/daytona#daytonaconfig) for details. # Daytona (/docs/python-sdk/daytona) ## DaytonaConfig [#daytonaconfig] ```python @dataclass class DaytonaConfig() ``` Configuration shared by every API version. One credential serves both namespaces: `api_key` (`DAYTONA_API_KEY`) or `jwt_token` (`DAYTONA_JWT_TOKEN`). A JWT is scoped by `organization_id` for v0 and `project_id` for v2. Fields left unset are read from the environment by each namespace. There is no region or API URL field here. Pass `region=` to a v2 create; `DAYTONA_V2_API_URL`, else `DAYTONA_API_URL`, selects the v2 API endpoint and never reaches v0. `target` is deprecated and applies to `.v0` only (the v0 client's default region). Pass `target` to each v0 sandbox create (`CreateSandboxFromSnapshotParams(target=...)`) or `region_id` to each v0 snapshot create instead. Setting it still works and emits a `DeprecationWarning`. `request_timeout` (seconds), `connection_pool_maxsize` and `otel_enabled` tune the v2 client's HTTP transport; `connection_pool_maxsize` and `otel_enabled` reach v0 too. `shared_hub` and `events` (`daytona.v2.SandboxEventsConfig`) configure the v2 client's sandbox-state events hub; v0 has no such hub. **Attributes**: - `api_key` _Optional\[str\] = field(default=None, repr=False)_ - `jwt_token` _Optional\[str\] = field(default=None, kw_only=True, repr=False)_ - `organization_id` _Optional\[str\] = field(default=None, kw_only=True)_ - `project_id` _Optional\[str\] = field(default=None, kw_only=True)_ - `target` _Optional\[str\] = field(default=None, kw_only=True)_ - `request_timeout` _Optional\[float\] = field(default=None, kw_only=True)_ - `connection_pool_maxsize` _Optional\[int\] = field(default=None, kw_only=True)_ - `otel_enabled` _Optional\[bool\] = field(default=None, kw_only=True)_ - `shared_hub` _bool = field(default=True, kw_only=True)_ - `events` _Optional\[SandboxEventsConfig\] = field(default=None, kw_only=True)_ ## Daytona [#daytona] ```python class Daytona(_Root) ``` The synchronous client: `Daytona().v0` and `Daytona().v2`. Every operation goes through a version namespace; the root itself only holds the shared configuration. `with Daytona() as d:` (or `close()`) closes whichever namespace clients were built. #### Daytona.\_\_init\_\_ [#daytona__init__] ```python def __init__(config: Optional[DaytonaConfig] = None) -> None ``` #### Daytona.v2 [#daytonav2] ```python @property def v2() -> _DaytonaV2 ``` The v2 client (v2's synchronous client), built on first access. Owned by the root: close the root, not this client (a closed v2 client stays cached and its calls fail). #### Daytona.v0 [#daytonav0] ```python @property def v0() -> _DaytonaV0 ``` The v0 client (the bundled 0.x `Daytona`), built on first access. Needs the `v0-sdk` extra (`pip install "daytona[v0-sdk]"`); raises `ImportError` naming it otherwise. #### Daytona.close [#daytonaclose] ```python def close() -> None ``` Close the namespace clients built so far. Idempotent. Closes the v2 client and the v0 client. The bundled 0.x sync `Daytona` has no `close()`, so the root releases its event socket (and tracer provider) directly. ## AsyncDaytona [#asyncdaytona] ```python class AsyncDaytona(_Root) ``` The asynchronous client: `AsyncDaytona().v0` and `AsyncDaytona().v2`. Same shape as `Daytona`; the namespace clients are the async ones. `async with AsyncDaytona() as d:` (or `await close()`) closes whichever namespace clients were built. #### AsyncDaytona.\_\_init\_\_ [#asyncdaytona__init__] ```python def __init__(config: Optional[DaytonaConfig] = None) -> None ``` #### AsyncDaytona.v2 [#asyncdaytonav2] ```python @property def v2() -> _AsyncDaytonaV2 ``` The v2 client (v2's asynchronous client), built on first access. Owned by the root: close the root, not this client (a closed v2 client stays cached and its calls fail). #### AsyncDaytona.v0 [#asyncdaytonav0] ```python @property def v0() -> _AsyncDaytonaV0 ``` The v0 client (the bundled 0.x `AsyncDaytona`), built on first access. Needs the `v0-sdk` extra (`pip install "daytona[v0-sdk]"`); raises `ImportError` naming it otherwise. #### AsyncDaytona.close [#asyncdaytonaclose] ```python async def close() -> None ``` Close the namespace clients built so far. Idempotent. ## DaytonaV2Client [#daytonav2client] ```python class DaytonaV2Client() ``` The v2 Daytona client. #### DaytonaV2Client.images [#daytonav2clientimages] ```python @property def images() -> ImageService ``` #### DaytonaV2Client.snapshots [#daytonav2clientsnapshots] ```python @property def snapshots() -> SnapshotService ``` #### DaytonaV2Client.volume [#daytonav2clientvolume] ```python @property def volume() -> VolumeService ``` #### DaytonaV2Client.secret [#daytonav2clientsecret] ```python @property def secret() -> SecretService ``` #### DaytonaV2Client.secrets [#daytonav2clientsecrets] ```python @property def secrets() -> SecretService ``` #### DaytonaV2Client.reservations [#daytonav2clientreservations] ```python @property def reservations() -> ReservationService ``` #### DaytonaV2Client.mac\_models [#daytonav2clientmac_models] ```python @property def mac_models() -> MacModelService ``` #### DaytonaV2Client.close [#daytonav2clientclose] ```python def close() -> None ``` Close HTTP resources, then stop the bridge loop. Idempotent; safe from any thread. #### DaytonaV2Client.create [#daytonav2clientcreate] ```python def create(image: Optional[str] = None, /, *, 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[PortMapping]] = None, volumes: Optional[Sequence[VolumeMount]] = None, secrets: Optional[Sequence[str]] = None, spot: Optional[bool] = None, lifecycle_policy: Optional[LifecyclePolicyConfig] = None, network_policy: NetworkPolicyInput | None | _UnsetNetworkPolicy = _UNSET_NETWORK_POLICY, cpu_arch: Optional[str] = None, cpu_type: Optional[str] = None, region: Optional[str] = None, toolbox_url: Optional[str] = None, idempotency_key: Optional[str] = None, wait_seconds: int = 60, create_timeout_seconds: Optional[int] = None) -> Sandbox ``` Create from a registered image name or `img_…` id. #### DaytonaV2Client.create\_from\_build [#daytonav2clientcreate_from_build] ```python def create_from_build(builder: ImageBuilder, /, *, idle_expiry_seconds: Optional[int] = None, network_policy: NetworkPolicyInput | None | _UnsetNetworkPolicy = _UNSET_NETWORK_POLICY, **kwargs) -> Sandbox ``` Build an anonymous image first, then create the sandbox from it. #### DaytonaV2Client.create\_from\_snapshot [#daytonav2clientcreate_from_snapshot] ```python def create_from_snapshot(snapshot: str, /, *, name: Optional[str] = None, labels: Optional[Dict[str, str]] = None, lifecycle_policy: Optional[LifecyclePolicyConfig] = None, ports: Optional[Sequence[PortMapping]] = None, region: Optional[str] = None, toolbox_url: Optional[str] = None, idempotency_key: Optional[str] = None, wait_seconds: int = 60, create_timeout_seconds: Optional[int] = None) -> Sandbox ``` Create a sandbox from a snapshot. #### DaytonaV2Client.create\_macos [#daytonav2clientcreate_macos] ```python def create_macos(image: str, /, *, cpu: Optional[int] = None, memory: Optional[float] = None, disk: Optional[float] = None, name: Optional[str] = None, env: Optional[Dict[str, str]] = None, labels: Optional[Dict[str, str]] = None, secrets: Optional[Sequence[str]] = None, ports: Optional[Sequence[PortMapping]] = None, persistent: Optional[bool] = None, lifecycle_policy: Optional[LifecyclePolicyConfig] = None, volumes: Optional[Sequence[VolumeMount]] = None, reservation: Optional[str] = None, auto_renew: Optional[bool] = None, region: Optional[str] = None, toolbox_url: Optional[str] = None, idempotency_key: Optional[str] = None, wait_seconds: int = 60, create_timeout_seconds: Optional[int] = None, network_policy: NetworkPolicyInput | None | _UnsetNetworkPolicy = _UNSET_NETWORK_POLICY) -> Sandbox ``` Create a macOS sandbox on a reserved Mac from a macOS image name. #### DaytonaV2Client.current\_api\_key [#daytonav2clientcurrent_api_key] ```python def current_api_key() -> ProjectApiKeyWithContext ``` Describe the API key this client authenticates with. #### DaytonaV2Client.delete [#daytonav2clientdelete] ```python def delete(sandbox: Union[Sandbox, str]) -> None ``` Request sandbox deletion. #### DaytonaV2Client.find\_by\_name [#daytonav2clientfind_by_name] ```python def find_by_name(name: str, /, *, region: Optional[str] = None) -> list[Sandbox] ``` Sandboxes created with `name=name`, newest first; `[]` when none. #### DaytonaV2Client.get [#daytonav2clientget] ```python def get(sandbox_id: str, *, toolbox_url: Optional[str] = None) -> Sandbox ``` Fetch a sandbox by id. #### DaytonaV2Client.get\_limits [#daytonav2clientget_limits] ```python def get_limits(*, organization_id: Optional[str] = None) -> OrganizationLimits ``` Return the organization's limits and current usage. #### DaytonaV2Client.get\_network\_policy [#daytonav2clientget_network_policy] ```python def get_network_policy(sandbox: Union[Sandbox, str]) -> NetworkPolicyInfo ``` #### DaytonaV2Client.get\_project\_budget [#daytonav2clientget_project_budget] ```python def get_project_budget() -> ProjectBudget ``` Return the monthly spend budget of the API key's project. #### DaytonaV2Client.get\_sandbox\_secrets [#daytonav2clientget_sandbox_secrets] ```python def get_sandbox_secrets(sandbox: Union[Sandbox, str]) -> SandboxSecretsInfo ``` Read a sandbox's attached secret names and apply state; see `Sandbox.get_secrets`. #### DaytonaV2Client.iter [#daytonav2clientiter] ```python def iter(*, cursor: Optional[str] = None, limit: Optional[int] = None) -> Iterator[Sandbox] ``` #### DaytonaV2Client.list [#daytonav2clientlist] ```python 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, sandbox_class: Optional[Union[SandboxClass, Sequence[SandboxClass]]] = None, region: Optional[Sequence[str]] = None, image_ref: Optional[str] = None, image_ref_prefix: Optional[str] = None, labels: Optional[Mapping[str, str]] = None, spot: Optional[bool] = None, forked_from: Optional[str] = None, min_cores: Optional[float] = None, max_cores: Optional[float] = None, min_memory_mib: Optional[int] = None, max_memory_mib: Optional[int] = None, min_disk_mib: Optional[int] = None, max_disk_mib: Optional[int] = None, created_start_at: Optional[SearchTimestamp] = None, created_end_at: Optional[SearchTimestamp] = None, updated_start_at: Optional[SearchTimestamp] = None, updated_end_at: Optional[SearchTimestamp] = None, last_activity_start_at: Optional[SearchTimestamp] = None, last_activity_end_at: Optional[SearchTimestamp] = None, sort: Optional[SearchSort] = None, order: Optional[SearchOrder] = None) -> ListResult[Sandbox] ``` List sandboxes as one page `{items, next_cursor}`. #### DaytonaV2Client.list\_audit\_actions [#daytonav2clientlist_audit_actions] ```python def list_audit_actions() -> AuditActionList ``` Return the actions the audit log can record for each target type. #### DaytonaV2Client.pause [#daytonav2clientpause] ```python def pause(sandbox: Union[Sandbox, str], *, timeout: float = 60) -> None ``` Pause a sandbox (accepts a Sandbox or its id); see `Sandbox.pause`. #### DaytonaV2Client.replace\_sandbox\_secrets [#daytonav2clientreplace_sandbox_secrets] ```python def replace_sandbox_secrets(sandbox: Union[Sandbox, str], *, secrets: Sequence[str], if_match: str) -> SandboxSecretsInfo ``` Replace a sandbox's attached secret names; see `Sandbox.replace_secrets`. #### DaytonaV2Client.reset\_network\_policy [#daytonav2clientreset_network_policy] ```python def reset_network_policy(sandbox: Union[Sandbox, str], *, if_match: str) -> NetworkPolicyInfo ``` #### DaytonaV2Client.resume [#daytonav2clientresume] ```python def resume(sandbox: Union[Sandbox, str], *, timeout: float = 60) -> None ``` Resume a sandbox (accepts a Sandbox or its id). #### DaytonaV2Client.search [#daytonav2clientsearch] ```python def search(*, q: Optional[str] = None, name_prefix: Optional[str] = None, id_prefix: Optional[str] = None, status: Optional[Sequence[str]] = None, sandbox_class: Optional[Union[SandboxClass, Sequence[SandboxClass]]] = None, region: Optional[Sequence[str]] = None, image_ref: Optional[str] = None, image_ref_prefix: Optional[str] = None, labels: Optional[Mapping[str, str]] = None, spot: Optional[bool] = None, forked_from: Optional[str] = None, min_cores: Optional[float] = None, max_cores: Optional[float] = None, min_memory_mib: Optional[int] = None, max_memory_mib: Optional[int] = None, min_disk_mib: Optional[int] = None, max_disk_mib: Optional[int] = None, created_start_at: Optional[SearchTimestamp] = None, created_end_at: Optional[SearchTimestamp] = None, updated_start_at: Optional[SearchTimestamp] = None, updated_end_at: Optional[SearchTimestamp] = None, last_activity_start_at: Optional[SearchTimestamp] = None, last_activity_end_at: 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 (`GET /sandboxes/search`). #### DaytonaV2Client.start [#daytonav2clientstart] ```python def start(sandbox: Union[Sandbox, str], *, timeout: float = 60) -> None ``` Start a sandbox (accepts a Sandbox or its id). #### DaytonaV2Client.stop [#daytonav2clientstop] ```python def stop(sandbox: Union[Sandbox, str]) -> None ``` Stop a persistent macOS sandbox (accepts a Sandbox or its id). #### DaytonaV2Client.update\_network\_policy [#daytonav2clientupdate_network_policy] ```python def update_network_policy(sandbox: Union[Sandbox, str], *, network_policy: NetworkPolicyInput, if_match: str) -> NetworkPolicyInfo ``` ## AsyncDaytonaV2Client [#asyncdaytonav2client] ```python class AsyncDaytonaV2Client() ``` The v2 Daytona client. #### AsyncDaytonaV2Client.create [#asyncdaytonav2clientcreate] ```python async def create(image: Optional[str] = None, /, *, 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[PortMapping]] = None, volumes: Optional[Sequence[VolumeMount]] = None, secrets: Optional[Sequence[str]] = None, spot: Optional[bool] = None, lifecycle_policy: Optional[LifecyclePolicyConfig] = None, network_policy: NetworkPolicyInput | None | _UnsetNetworkPolicy = _UNSET_NETWORK_POLICY, cpu_arch: Optional[str] = None, cpu_type: Optional[str] = None, region: Optional[str] = None, toolbox_url: Optional[str] = None, idempotency_key: Optional[str] = None, wait_seconds: int = 60, create_timeout_seconds: Optional[int] = None) -> AsyncSandbox ``` Create from a registered image name or `img_…` id. Omitting `image` boots the platform default image, the Linux image Daytona marks as default (`images.list(platform="true")` shows it with `default=True`); the returned sandbox's `image` names the image the server booted. When no default is configured the create fails with `DEFAULT_IMAGE_NOT_CONFIGURED` (400). An empty or whitespace-only `image` is still an error, raised before any request. Fast path: the server holds this create briefly, so a sandbox that reaches `running` within that hold returns in one round trip. `wait_seconds` and `create_timeout_seconds` are budgets: the SDK long-polls any remainder of `wait_seconds` client-side, and `create_timeout_seconds` 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: 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="example-user")` at one regional API endpoint 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 scoped to a regional API endpoint (creates of one end user that reach two regional API endpoints make two sandboxes; pin them to one region), per class, 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.** Burstable sandboxes start 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. Creating Linux sandboxes requires Linux access enabled for the organization. Otherwise a caller holding `write:sandboxes` gets `403` `FEATURE_NOT_ENABLED` (raised as `FeatureNotEnabledError`). `toolbox_url` overrides the toolbox URL the API returns; the SDK sends the new sandbox's toolbox credential there, so pass only a URL you trust — never one read from stored or user-supplied data. #### AsyncDaytonaV2Client.create\_from\_snapshot [#asyncdaytonav2clientcreate_from_snapshot] ```python async def create_from_snapshot(snapshot: str, /, *, name: Optional[str] = None, labels: Optional[Dict[str, str]] = None, lifecycle_policy: Optional[LifecyclePolicyConfig] = None, ports: Optional[Sequence[PortMapping]] = None, region: Optional[str] = None, toolbox_url: Optional[str] = None, idempotency_key: Optional[str] = None, wait_seconds: int = 60, create_timeout_seconds: Optional[int] = None) -> AsyncSandbox ``` Create a sandbox from a snapshot. Creating Linux sandboxes requires Linux access enabled for the organization. Otherwise a caller holding `write:sandboxes` gets `403` `FEATURE_NOT_ENABLED` (raised as `FeatureNotEnabledError`). `toolbox_url` overrides the toolbox URL the API returns; the SDK sends the new sandbox's toolbox credential there, so pass only a URL you trust — never one read from stored or user-supplied data. #### AsyncDaytonaV2Client.create\_macos [#asyncdaytonav2clientcreate_macos] ```python async def create_macos(image: str, /, *, cpu: Optional[int] = None, memory: Optional[float] = None, disk: Optional[float] = None, name: Optional[str] = None, env: Optional[Dict[str, str]] = None, labels: Optional[Dict[str, str]] = None, secrets: Optional[Sequence[str]] = None, ports: Optional[Sequence[PortMapping]] = None, persistent: Optional[bool] = None, lifecycle_policy: Optional[LifecyclePolicyConfig] = None, volumes: Optional[Sequence[VolumeMount]] = None, reservation: Optional[str] = None, auto_renew: Optional[bool] = None, region: Optional[str] = None, toolbox_url: Optional[str] = None, idempotency_key: Optional[str] = None, wait_seconds: int = 60, create_timeout_seconds: Optional[int] = None, network_policy: NetworkPolicyInput | None | _UnsetNetworkPolicy = _UNSET_NETWORK_POLICY) -> AsyncSandbox ``` Create a macOS sandbox on a reserved Mac from a macOS image name. `cpu`: CPU cores, at least 4; sent as `cores`. A Mac core is one CPU of the Mac (Apple Silicon has no SMT). Omitted uses half of the claiming Mac's cores, rounded down, on a model that runs two sandboxes, or all of them on a model that runs one. `memory`: Memory in GiB, at least 4; sent as memory_mib. memory * 1024 must be an integer. Omitted uses half of the claiming Mac's memory, rounded down, on a model that runs two sandboxes, or all of it on a model that runs one. `disk`: Disk in GiB, at least 80; sent as disk_mib. The whole sandbox disk, macOS included. disk * 1024 must be an integer. Omitted uses half of the claiming Mac's sandbox disk room, rounded down to a whole GiB, on a model that runs two sandboxes, or all of it on a model that runs one. The first successful claim fixes the size, which the sandbox reports from then on. `persistent`: Stop keeps the disk on the same Mac. Start and resume use that Mac. Delete erases the disk. At reservation end, the disk is saved as an anonymous image before the Mac is erased; a lost Mac saves it if it comes back within 7 days. If a Mac restarts before it is declared lost, a running persistent sandbox comes back stopped with its disk, a running ephemeral sandbox is lost, and stopped and paused sandboxes are unchanged. Create a sandbox from an image to continue on another Mac. `volumes` attaches disk volumes read-write. A sandbox with volumes cannot be persistent; bucket volumes and `read_only` are rejected with `BadRequestError`. `reservation` picks the Mac's reservation (`daytona.reservations`): `None` uses any fitting reservation of the organization in the region (or lets the organization's auto-reserve buy one), `"new"` buys a reservation of the cheapest model that fits. A reservation ID targets that reservation at claim. Acceptance does not reserve room; the sandbox can wait for room or time out. `auto_renew` is allowed only with `reservation="new"`. With no reservation to use it raises `ConflictError` (`NO_ACTIVE_RESERVATION`, `NO_FREE_SLOT`, `MAC_DISK_FULL`, `AUTO_RESERVE_LIMIT_REACHED`, `NO_MAC_AVAILABLE`). `name`, `idempotency_key`, `wait_seconds` and `create_timeout_seconds` behave as on `create`. Creating macOS sandboxes requires macOS access enabled for the organization; otherwise the API answers `403` `FEATURE_NOT_ENABLED` (raised as `FeatureNotEnabledError`). `secrets` attaches project secrets by name, as on `create`. Their values are available to HTTPS requests to the secret's allowed domains without entering the sandbox. Attaching needs `read:secrets`. `network_policy` sets the sandbox's egress policy, as on `create`: it applies from the sandbox's first boot. If the policy cannot be enforced, the API answers `503`. Change it later with `AsyncSandbox.update_network_policy`. `toolbox_url` overrides the toolbox URL the API returns; the SDK sends the new sandbox's toolbox credential there, so pass only a URL you trust — never one read from stored or user-supplied data. Find regions and their regional API endpoints with `GET /regions`; discover Mac models and prices with `mac_models.catalog(region="")`. To select a regional API endpoint, set `DAYTONA_V2_API_URL` before creating the client. An API that does not serve the region answers `ConflictError`; the SDK does not reroute. #### AsyncDaytonaV2Client.create\_from\_build [#asyncdaytonav2clientcreate_from_build] ```python async def create_from_build(builder: ImageBuilder, /, *, idle_expiry_seconds: Optional[int] = None, network_policy: NetworkPolicyInput | None | _UnsetNetworkPolicy = _UNSET_NETWORK_POLICY, **kwargs: object) -> AsyncSandbox ``` Build an anonymous image first, then create the sandbox from it. Slow path: `POST /images` followed by `create(image.id, ...)`. `idle_expiry_seconds` describes the anonymous image's idle window; every other keyword goes to `create()`. Docker storage is included. `region` applies to both the image build and the create: a Dockerfile-built image can only boot in its own region, so it is built where the sandbox will run. If the image build fails, this raises `ImageBuildFailedError` and no sandbox exists. #### AsyncDaytonaV2Client.get [#asyncdaytonav2clientget] ```python async def get(sandbox_id: str, *, toolbox_url: Optional[str] = None) -> AsyncSandbox ``` Fetch a sandbox by id. `toolbox_url` overrides the toolbox URL the API returns. The SDK sends this sandbox's toolbox credential there (the API key, a project token, or a minted sandbox token), so pass only a URL you trust — never one read from stored or user-supplied data. #### AsyncDaytonaV2Client.find\_by\_name [#asyncdaytonav2clientfind_by_name] ```python async def find_by_name(name: str, /, *, region: Optional[str] = None) -> list[AsyncSandbox] ``` Sandboxes created with `name=name`, newest first; `[]` when none. Exact match on the `labels["name"]` every `create*(name=…)` stamps, read through sandbox search. 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. A new sandbox becomes searchable shortly after its create. Sandboxes that are `deleted` or `deleting` are left out. A deployment without search raises `SearchNotConfiguredError` (501). `region` scopes the read the way it scopes a create: it is sent as the same `x-daytona-region` selector `create*()` sends, and `"local"` (or omitting it) means the default region — so the lookup uses the same regional API endpoint as the named create. #### AsyncDaytonaV2Client.list\_audit\_actions [#asyncdaytonav2clientlist_audit_actions] ```python async def list_audit_actions() -> AuditActionList ``` Return the actions the audit log can record for each target type. #### AsyncDaytonaV2Client.current\_api\_key [#asyncdaytonav2clientcurrent_api_key] ```python async def current_api_key() -> ProjectApiKeyWithContext ``` 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. #### AsyncDaytonaV2Client.get\_project\_budget [#asyncdaytonav2clientget_project_budget] ```python async def get_project_budget() -> ProjectBudget ``` Return the monthly spend budget of the API key's project. An unset budget is returned with nullable limit and period fields. 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`. #### AsyncDaytonaV2Client.get\_limits [#asyncdaytonav2clientget_limits] ```python async def get_limits(*, organization_id: Optional[str] = None) -> OrganizationLimits ``` Return the organization's limits and current usage. A null `limit` means unlimited. With an API key the organization defaults to the key's own, looked up once and cached; with `jwt_token` authentication pass `organization_id`. The credential needs the `read:limits` permission. Member counts (`members`) are not included: they are served to signed-in members only. #### AsyncDaytonaV2Client.list [#asyncdaytonav2clientlist] ```python 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, sandbox_class: Optional[Union[SandboxClass, Sequence[SandboxClass]]] = None, region: Optional[Sequence[str]] = None, image_ref: Optional[str] = None, image_ref_prefix: Optional[str] = None, labels: Optional[Mapping[str, str]] = None, spot: Optional[bool] = None, forked_from: Optional[str] = None, min_cores: Optional[float] = None, max_cores: Optional[float] = None, min_memory_mib: Optional[int] = None, max_memory_mib: Optional[int] = None, min_disk_mib: Optional[int] = None, max_disk_mib: Optional[int] = None, created_start_at: Optional[SearchTimestamp] = None, created_end_at: Optional[SearchTimestamp] = None, updated_start_at: Optional[SearchTimestamp] = None, updated_end_at: Optional[SearchTimestamp] = None, last_activity_start_at: Optional[SearchTimestamp] = None, last_activity_end_at: Optional[SearchTimestamp] = None, sort: Optional[SearchSort] = None, order: Optional[SearchOrder] = None) -> ListResult[AsyncSandbox] ``` List sandboxes as one page `{items, next_cursor}`. With only `cursor`/`limit` this is the read-your-writes path: one page of `GET /sandboxes`, newest first. A sandbox you just created is in the result; walk further pages with `iter()` or the returned cursor. Use the returned cursor to request the next page. Any other parameter — including `id` / `name` (sent as `id_prefix` / `name_prefix`), `q`, `status`, `sandbox_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 search totals on the result. That path is **eventually consistent**: a recent change may not appear immediately. Results span every region. 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 has search disabled (501, `SearchNotConfiguredError` with `code == "SEARCH_NOT_CONFIGURED"`) or search is unavailable (503, `SearchUnavailableError` with `code == "SEARCH_UNAVAILABLE"`), drop the search parameters to fall back to the `GET /sandboxes` path. #### AsyncDaytonaV2Client.search [#asyncdaytonav2clientsearch] ```python async def search(*, q: Optional[str] = None, name_prefix: Optional[str] = None, id_prefix: Optional[str] = None, status: Optional[Sequence[str]] = None, sandbox_class: Optional[Union[SandboxClass, Sequence[SandboxClass]]] = None, region: Optional[Sequence[str]] = None, image_ref: Optional[str] = None, image_ref_prefix: Optional[str] = None, labels: Optional[Mapping[str, str]] = None, spot: Optional[bool] = None, forked_from: Optional[str] = None, min_cores: Optional[float] = None, max_cores: Optional[float] = None, min_memory_mib: Optional[int] = None, max_memory_mib: Optional[int] = None, min_disk_mib: Optional[int] = None, max_disk_mib: Optional[int] = None, created_start_at: Optional[SearchTimestamp] = None, created_end_at: Optional[SearchTimestamp] = None, updated_start_at: Optional[SearchTimestamp] = None, updated_end_at: Optional[SearchTimestamp] = None, last_activity_start_at: Optional[SearchTimestamp] = None, last_activity_end_at: Optional[SearchTimestamp] = None, sort: Optional[SearchSort] = None, order: Optional[SearchOrder] = None, limit: Optional[int] = None, cursor: Optional[str] = None) -> SearchResult[AsyncSandbox] ``` Search sandboxes across every region (`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`, `sandbox_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_*` bounds are inclusive, `*_start_at` timestamp bounds are inclusive, and `*_end_at` bounds are exclusive. Timestamps accept 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 `AsyncSandbox` handles `list` returns. Consistency: search is **eventually consistent**. Results may be briefly stale after a create, update or delete, 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. 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 reflects current results, so a sandbox whose sort field (`status`, `name`, `memory_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`/`sandbox_class`/`sort` value, a non-object `labels` or a `min` above its `max`; 501 (`SearchNotConfiguredError` with `code == "SEARCH_NOT_CONFIGURED"`) when the API has search disabled; 503 (`SearchUnavailableError` with `code == "SEARCH_UNAVAILABLE"`) when search is unavailable. 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 does not use search. #### AsyncDaytonaV2Client.iter [#asyncdaytonav2clientiter] ```python async def iter(*, cursor: Optional[str] = None, limit: Optional[int] = None) -> AsyncIterator[AsyncSandbox] ``` #### AsyncDaytonaV2Client.start [#asyncdaytonav2clientstart] ```python async def start(sandbox: Union[AsyncSandbox, str], *, timeout: float = 60) -> None ``` Start a sandbox (accepts a Sandbox or its id). #### AsyncDaytonaV2Client.stop [#asyncdaytonav2clientstop] ```python async def stop(sandbox: Union[AsyncSandbox, str]) -> None ``` Stop a persistent macOS sandbox (accepts a Sandbox or its id). #### AsyncDaytonaV2Client.pause [#asyncdaytonav2clientpause] ```python async def pause(sandbox: Union[AsyncSandbox, str], *, timeout: float = 60) -> None ``` Pause a sandbox (accepts a Sandbox or its id); see `Sandbox.pause`. #### AsyncDaytonaV2Client.resume [#asyncdaytonav2clientresume] ```python async def resume(sandbox: Union[AsyncSandbox, str], *, timeout: float = 60) -> None ``` Resume a sandbox (accepts a Sandbox or its id). #### AsyncDaytonaV2Client.delete [#asyncdaytonav2clientdelete] ```python async def delete(sandbox: Union[AsyncSandbox, str]) -> None ``` Request sandbox deletion. Image deletion may still return 409 after this call returns, even if the sandbox reports `destroyed` or a subsequent read returns 404. #### AsyncDaytonaV2Client.get\_network\_policy [#asyncdaytonav2clientget_network_policy] ```python async def get_network_policy(sandbox: Union[AsyncSandbox, str]) -> NetworkPolicyInfo ``` #### AsyncDaytonaV2Client.update\_network\_policy [#asyncdaytonav2clientupdate_network_policy] ```python async def update_network_policy(sandbox: Union[AsyncSandbox, str], *, network_policy: NetworkPolicyInput, if_match: str) -> NetworkPolicyInfo ``` #### AsyncDaytonaV2Client.reset\_network\_policy [#asyncdaytonav2clientreset_network_policy] ```python async def reset_network_policy(sandbox: Union[AsyncSandbox, str], *, if_match: str) -> NetworkPolicyInfo ``` #### AsyncDaytonaV2Client.get\_sandbox\_secrets [#asyncdaytonav2clientget_sandbox_secrets] ```python async def get_sandbox_secrets(sandbox: Union[AsyncSandbox, str]) -> SandboxSecretsInfo ``` Read a sandbox's attached secret names and apply state; see `AsyncSandbox.get_secrets`. #### AsyncDaytonaV2Client.replace\_sandbox\_secrets [#asyncdaytonav2clientreplace_sandbox_secrets] ```python async def replace_sandbox_secrets(sandbox: Union[AsyncSandbox, str], *, secrets: Sequence[str], if_match: str) -> SandboxSecretsInfo ``` Replace a sandbox's attached secret names; see `AsyncSandbox.replace_secrets`. #### AsyncDaytonaV2Client.close [#asyncdaytonav2clientclose] ```python async def close() -> None ``` Close HTTP resources. ## AuditActionGroup [#auditactiongroup] ```python class AuditActionGroup(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='The resource type the actions apply to. It matches `target_type` on an audit log entry.')_ - `additional_properties` _Dict\[str, Any\] = \{\}_ ##### model\_config [#model_config] ```python model_config = ConfigDict(populate_by_name=True, validate_assignment=True, protected_namespaces=()) ``` #### AuditActionGroup.to\_str [#auditactiongroupto_str] ```python def to_str() -> str ``` Returns the string representation of the model using alias #### AuditActionGroup.to\_json [#auditactiongroupto_json] ```python def to_json() -> str ``` Returns the JSON representation of the model using alias #### AuditActionGroup.from\_json [#auditactiongroupfrom_json] ```python @classmethod def from_json(json_str: str) -> Optional[Self] ``` Create an instance of AuditActionGroup from a JSON string #### AuditActionGroup.to\_dict [#auditactiongroupto_dict] ```python 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. #### AuditActionGroup.from\_dict [#auditactiongroupfrom_dict] ```python @classmethod def from_dict(obj: Optional[Dict[str, Any]]) -> Optional[Self] ``` Create an instance of AuditActionGroup from a dict ## AuditActionList [#auditactionlist] ```python class AuditActionList(BaseModel) ``` The supported audit actions, grouped by target type. **Attributes**: - `targets` _List\[AuditActionGroup\] = Field(description='One entry per target type, sorted by target type.')_ - `additional_properties` _Dict\[str, Any\] = \{\}_ ##### model\_config [#model_config-1] ```python model_config = ConfigDict(populate_by_name=True, validate_assignment=True, protected_namespaces=()) ``` #### AuditActionList.to\_str [#auditactionlistto_str] ```python def to_str() -> str ``` Returns the string representation of the model using alias #### AuditActionList.to\_json [#auditactionlistto_json] ```python def to_json() -> str ``` Returns the JSON representation of the model using alias #### AuditActionList.from\_json [#auditactionlistfrom_json] ```python @classmethod def from_json(json_str: str) -> Optional[Self] ``` Create an instance of AuditActionList from a JSON string #### AuditActionList.to\_dict [#auditactionlistto_dict] ```python 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. #### AuditActionList.from\_dict [#auditactionlistfrom_dict] ```python @classmethod def from_dict(obj: Optional[Dict[str, Any]]) -> Optional[Self] ``` Create an instance of AuditActionList from a dict ## ProjectApiKeyWithContext [#projectapikeywithcontext] ```python class ProjectApiKeyWithContext(BaseModel) ``` A project API key together with its tenant context. **Attributes**: - `created_at` _datetime = Field(description='When the API key was created.')_ - `created_by` _Optional\[StrictStr\] = Field(default=None, description='The user who created the API key, when visible.')_ - `expires_at` _Optional\[datetime\] = Field(default=None, description='When the API key expires, or null when it does not expire.')_ - `id` _StrictStr = Field(description='The API key ID.')_ - `imported_from` _Optional\[StrictStr\] = Field(default=None, description='`"v0"` when the key was created on Daytona v0 and imported by the v0 ↔ v2 key sync; `null` for a key created on this platform.')_ - `key_prefix` _Optional\[StrictStr\] = Field(default=None, description='The recognizable leading token characters, when available.')_ - `key_suffix` _Optional\[StrictStr\] = Field(default=None, description='The recognizable trailing token characters, when available.')_ - `last_used_at` _Optional\[datetime\] = Field(default=None, description='When the API key was last used, or null when unknown.')_ - `name` _StrictStr = Field(description='The API key name.')_ - `project_id` _StrictStr = Field(description='The project ID.')_ - `project_permissions` _List\[StrictStr\] = Field(description='The project permissions granted to the API key.')_ - `revoked_at` _Optional\[datetime\] = Field(default=None, description='When the API key was revoked, or null while active.')_ - `service_account_id` _Optional\[StrictStr\] = Field(default=None, description='The service account that owns the API key, when applicable.')_ - `service_account_name` _Optional\[StrictStr\] = Field(default=None, description='The service account name, when applicable and available.')_ - `sync_to_v0` _StrictBool = Field(description="Whether the v0 ↔ v2 key sync copies this key to Daytona v0 (for an organization that is kept in sync with Daytona v0). `true` for a live key a person minted in the organization's `default` project unless it was opted out by updating the API key, and always for a live key imported from Daytona v0. `false` for every key the sync never copies: keys in other projects, service-account keys, the dashboard's own key named `default`, and revoked or expired keys. A Daytona v0 copy can read every sandbox, snapshot and registry of the organization on Daytona v0, which has no read permissions.")_ - `sync_to_v1` _StrictBool = Field(description='Deprecated: use `sync_to_v0`, which carries the same value.')_ - `context` _ProjectApiKeyContext_ - `additional_properties` _Dict\[str, Any\] = \{\}_ ##### model\_config [#model_config-2] ```python model_config = ConfigDict(populate_by_name=True, validate_assignment=True, protected_namespaces=()) ``` #### ProjectApiKeyWithContext.to\_str [#projectapikeywithcontextto_str] ```python def to_str() -> str ``` Returns the string representation of the model using alias #### ProjectApiKeyWithContext.to\_json [#projectapikeywithcontextto_json] ```python def to_json() -> str ``` Returns the JSON representation of the model using alias #### ProjectApiKeyWithContext.from\_json [#projectapikeywithcontextfrom_json] ```python @classmethod def from_json(json_str: str) -> Optional[Self] ``` Create an instance of ProjectApiKeyWithContext from a JSON string #### ProjectApiKeyWithContext.to\_dict [#projectapikeywithcontextto_dict] ```python 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. #### ProjectApiKeyWithContext.from\_dict [#projectapikeywithcontextfrom_dict] ```python @classmethod def from_dict(obj: Optional[Dict[str, Any]]) -> Optional[Self] ``` Create an instance of ProjectApiKeyWithContext from a dict ## ProjectBudget [#projectbudget] ```python class ProjectBudget(BaseModel) ``` A project's monthly spend budget and its current state. **Attributes**: - `created_at` _Optional\[datetime\] = Field(description='When the budget was first set, or null when no budget is set.')_ - `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` _Optional\[StrictInt\] = Field(description='The monthly budget, in US cents, or null when no budget is set.')_ - `period_start_date` _Optional\[date\] = Field(description='The first day of the current budget period (the calendar month in UTC), as `YYYY-MM-DD`.')_ - `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 the budget grace period ends: `exceeded_at` plus the grace period. Running sandboxes may then be stopped or deleted; macOS sandboxes on prepaid reservations keep running. Null when there is no active hold or the deadline falls on or after the next UTC month, when the hold expires.')_ - `updated_at` _Optional\[datetime\] = Field(description='When a member last set the budget, or null when no budget is set. Spend evaluations do not change it.')_ - `additional_properties` _Dict\[str, Any\] = \{\}_ ##### model\_config [#model_config-3] ```python model_config = ConfigDict(populate_by_name=True, validate_assignment=True, protected_namespaces=()) ``` #### ProjectBudget.to\_str [#projectbudgetto_str] ```python def to_str() -> str ``` Returns the string representation of the model using alias #### ProjectBudget.to\_json [#projectbudgetto_json] ```python def to_json() -> str ``` Returns the JSON representation of the model using alias #### ProjectBudget.from\_json [#projectbudgetfrom_json] ```python @classmethod def from_json(json_str: str) -> Optional[Self] ``` Create an instance of ProjectBudget from a JSON string #### ProjectBudget.to\_dict [#projectbudgetto_dict] ```python 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 [#projectbudgetfrom_dict] ```python @classmethod def from_dict(obj: Optional[Dict[str, Any]]) -> Optional[Self] ``` Create an instance of ProjectBudget from a dict ## LifecyclePolicyConfig [#lifecyclepolicyconfig] ```python class LifecyclePolicyConfig(TypedDict, total=False) ``` Per-sandbox lifecycle policy: a wall-clock timeout and an idle timeout, each paired with the action it fires. `timeout_seconds` (`>= 1`, never disabled) fires `on_timeout` that many seconds after create, after a `daytona.v2.Sandbox.update_lifecycle_policy` that supplies it, and again after every accepted transition to running (start, resume) — the full budget re-arms each time. Omitted `on_timeout` resolves to the server's class default. `idle_expiry_seconds` 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_expiry_seconds` from nothing requires it. At Linux create, each field you omit is inherited from the project's lifecycle defaults (set in the dashboard's project settings), then — for `timeout_seconds` only — from the platform default timeout when enabled. macOS creates use platform defaults, not project defaults. An action follows its own interval: a `timeout_seconds` you pass without `on_timeout` gets the class default, not the project's action. Pass `DISABLED` as `idle_expiry_seconds` to opt out of an inherited idle timeout. Project defaults apply to new sandboxes only; `daytona.v2.Sandbox.update_lifecycle_policy` never consults them. Settings unavailable for the sandbox's class and persistence are rejected before sending the request. Linux supports `delete`; persistent macOS sandboxes also support `stop`. Pause macOS explicitly with `daytona.v2.Sandbox.pause`. **Attributes**: - `timeout_seconds` _int_ - `on_timeout` _LifecycleAction_ - `idle_expiry_seconds` _int_ - `on_idle_timeout` _LifecycleAction_ ## ListResult [#listresult] ```python @dataclass(frozen=True) class ListResult(Generic[T]) ``` Cursor-paginated list result. `total` and `total_relation` are only populated when the result came from search (`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\[SearchTotalRelation\] = None_ - `raw_total_relation` _Optional\[str\] = None_ ## Resources [#resources] ```python @dataclass(frozen=True) class Resources() ``` Sandbox resource request; CPU is cores (1 core = 2 vCPUs), 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. `cpu_max` is a multiple of 0.5 cores: the sandbox boots `cpu_max * 2` vCPUs. **Attributes**: - `cpu` _Optional\[float\] = None_ - `cpu_max` _Optional\[float\] = None_ - `memory` _Optional\[int\] = None_ - `memory_max` _Optional\[float\] = None_ - `disk` _Optional\[int\] = None_ - `disk_max` _Optional\[float\] = None_ ## NetworkPolicyInput [#networkpolicyinput] ```python class NetworkPolicyInput(TypedDict, total=False) ``` **Attributes**: - `block_all` _bool \| None_ - `allow_cidrs` _Sequence\[str\]_ - `allow_domains` _Optional\[Sequence\[str\]\]_ ## NetworkPolicy [#networkpolicy] ```python @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 [#networkpolicyinfo] ```python @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_start_id` _Optional\[str\] = None_ - `status` _Optional\[str\] = None_ - `error` _Optional\[str\] = None_ ## SnapshotRef [#snapshotref] ```python @dataclass(frozen=True, slots=True) class SnapshotRef() ``` **Attributes**: - `id` _str_ - `name` _Optional\[str\] = None_ ## ListSandboxesQuery [#listsandboxesquery] ```python @dataclass(frozen=True) class ListSandboxesQuery(SandboxSearchFilters) ``` Every `Daytona.list()` parameter. `cursor`/`limit`/`id`/`name` remain the only positional parameters, in that order. `cursor`/`limit` alone read `GET /sandboxes`; `id`/`name` and any inherited (keyword-only) search filter route the call to `/sandboxes/search`. **Attributes**: - `cursor` _Optional\[str\] = None_ - `limit` _Optional\[int\] = None_ - `id` _Optional\[str\] = None_ - `name` _Optional\[str\] = None_ ## OrganizationLimits [#organizationlimits] ```python class OrganizationLimits(BaseModel) ``` OrganizationLimits **Attributes**: - `api_keys_per_organization` _UsageLimit_ - `api_keys_per_project` _UsageLimit_ - `image_builds` _ImageBuildLimits_ - `members` _Optional\[MemberLimits\] = None_ - `sandbox_resources` _Optional\[SandboxResourceLimits\] = None_ - `sandboxes` _SandboxLimits_ - `secrets_per_project` _UsageLimit_ - `storage` _StorageLimits_ - `additional_properties` _Dict\[str, Any\] = \{\}_ ##### model\_config [#model_config-4] ```python model_config = ConfigDict(populate_by_name=True, validate_assignment=True, protected_namespaces=()) ``` #### OrganizationLimits.to\_str [#organizationlimitsto_str] ```python def to_str() -> str ``` Returns the string representation of the model using alias #### OrganizationLimits.to\_json [#organizationlimitsto_json] ```python def to_json() -> str ``` Returns the JSON representation of the model using alias #### OrganizationLimits.from\_json [#organizationlimitsfrom_json] ```python @classmethod def from_json(json_str: str) -> Optional[Self] ``` Create an instance of OrganizationLimits from a JSON string #### OrganizationLimits.to\_dict [#organizationlimitsto_dict] ```python 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. #### OrganizationLimits.from\_dict [#organizationlimitsfrom_dict] ```python @classmethod def from_dict(obj: Optional[Dict[str, Any]]) -> Optional[Self] ``` Create an instance of OrganizationLimits from a dict #### idempotency\_key\_for\_name [#idempotency_key_for_name] ```python 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 retries from either SDK use the same key within a regional API endpoint: use it to recover or inspect the key behind a named create. ## V0\_API\_URL: `Final[str]` [#v0_api_url-finalstr] ```python V0_API_URL = 'https://app.daytona.io/api' ``` ## DEFAULT\_V2\_API\_URL: `Final[str]` [#default_v2_api_url-finalstr] ```python DEFAULT_V2_API_URL = 'https://api.daytona.com' ``` ## NAME\_LABEL: `Final` [#name_label-final] ```python NAME_LABEL = 'name' ``` ## SnapshotDetail [#snapshotdetail] ```python SnapshotDetail = _gen.api.Snapshot ``` ## SnapshotKind [#snapshotkind] ```python SnapshotKind = Literal['full', 'unknown'] ``` ## LifecycleAction [#lifecycleaction] ```python LifecycleAction = Literal['stop', 'pause', 'delete'] ``` The action a lifecycle trigger fires: `on_timeout` / `on_idle_timeout`. Available actions depend on the sandbox's class and persistence; unsupported settings are rejected before sending the request. ## DISABLED: `int` [#disabled-int] ```python DISABLED = -1 ``` Clears `LifecyclePolicyConfig.idle_expiry_seconds` — and only that field. `idle_expiry_seconds` value space, identical at create and on `daytona.v2.Sandbox.update_lifecycle_policy`: omitted = unchanged (update) / 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_seconds` does NOT accept it: the timeout cannot be disabled, so `timeout_seconds` must be `>= 1` (`-1` and `0` are rejected). # Sandbox (/docs/python-sdk/sandbox) ## Sandbox [#sandbox] ```python class Sandbox() ``` Serializable sandbox handle with process/fs/git/interpreter/pty namespaces. #### Sandbox.\_\_init\_\_ [#sandbox__init__] ```python def __init__(impl: AsyncSandbox, bridge: SyncBridge) -> None ``` #### Sandbox.id [#sandboxid] ```python @property def id() -> str ``` #### Sandbox.name [#sandboxname] ```python @property def name() -> str | None ``` #### Sandbox.state [#sandboxstate] ```python @property def state() -> Literal['queued', 'creating', 'starting', 'started', 'pausing', 'paused', 'stopping', 'stopped', 'destroying', 'destroyed', 'error', 'unknown'] ``` #### Sandbox.image\_build\_id [#sandboximage_build_id] ```python @property def image_build_id() -> str | None ``` #### Sandbox.image [#sandboximage] ```python @property def image() -> ImageRef | None ``` #### Sandbox.snapshot [#sandboxsnapshot] ```python @property def snapshot() -> SnapshotRef | None ``` #### Sandbox.target [#sandboxtarget] ```python @property def target() -> str | None ``` #### Sandbox.region [#sandboxregion] ```python @property def region() -> Optional[str] ``` #### Sandbox.labels [#sandboxlabels] ```python @property def labels() -> Dict[str, str] ``` #### Sandbox.cpu [#sandboxcpu] ```python @property def cpu() -> Optional[float] ``` #### Sandbox.cpu\_max [#sandboxcpu_max] ```python @property def cpu_max() -> Optional[float] ``` #### Sandbox.memory [#sandboxmemory] ```python @property def memory() -> Optional[float] ``` #### Sandbox.memory\_max [#sandboxmemory_max] ```python @property def memory_max() -> Optional[float] ``` #### Sandbox.disk [#sandboxdisk] ```python @property def disk() -> Optional[float] ``` #### Sandbox.disk\_max [#sandboxdisk_max] ```python @property def disk_max() -> Optional[float] ``` #### Sandbox.sandbox\_class [#sandboxsandbox_class] ```python @property def sandbox_class() -> Optional[SandboxClass] ``` #### Sandbox.persistent [#sandboxpersistent] ```python @property def persistent() -> Optional[bool] ``` #### Sandbox.spot [#sandboxspot] ```python @property def spot() -> Optional[bool] ``` #### Sandbox.spot\_evicted\_at [#sandboxspot_evicted_at] ```python @property def spot_evicted_at() -> Optional[str] ``` #### Sandbox.lifecycle\_policy [#sandboxlifecycle_policy] ```python @property def lifecycle_policy() -> Optional[SandboxLifecycle] ``` #### Sandbox.forked\_from [#sandboxforked_from] ```python @property def forked_from() -> Optional[str] ``` #### Sandbox.reservation\_id [#sandboxreservation_id] ```python @property def reservation_id() -> Optional[str] ``` #### Sandbox.user [#sandboxuser] ```python @property def user() -> Optional[str] ``` #### Sandbox.error [#sandboxerror] ```python @property def error() -> Optional[str] ``` #### Sandbox.error\_reason [#sandboxerror_reason] ```python @property def error_reason() -> Optional[str] ``` #### Sandbox.access\_token [#sandboxaccess_token] ```python @property def access_token() -> str | None ``` #### Sandbox.access\_token\_expires\_at [#sandboxaccess_token_expires_at] ```python @property def access_token_expires_at() -> str | None ``` #### Sandbox.toolbox\_proxy\_url [#sandboxtoolbox_proxy_url] ```python @property def toolbox_proxy_url() -> str | None ``` #### Sandbox.build\_logs [#sandboxbuild_logs] ```python def build_logs() -> str ``` Return retained build output as one-shot text, not a live follower. #### Sandbox.create\_access\_token [#sandboxcreate_access_token] ```python def create_access_token(*, operations: Optional[Sequence[str]] = None, ports: Optional[Sequence[int]] = None, ttl_seconds: Optional[int] = None) -> SandboxAccessToken ``` Mint a scoped, short-lived access token for THIS sandbox. #### Sandbox.create\_snapshot [#sandboxcreate_snapshot] ```python def create_snapshot(name: str) -> Snapshot ``` #### Sandbox.delete [#sandboxdelete] ```python def delete() -> None ``` Request sandbox deletion. #### Sandbox.entrypoint\_logs [#sandboxentrypoint_logs] ```python def entrypoint_logs() -> str ``` Return the sandbox entrypoint-session log as text. #### Sandbox.exec [#sandboxexec] ```python def exec(command: Optional[str] = None, *, argv: Optional[Sequence[str]] = None, cwd: Optional[str] = None, env: Optional[Mapping[str, str]] = None, user: Optional[str] = None, shell: Optional[str] = None, login: Optional[bool] = None, stdin: StdinMode = 'closed', timeout: Optional[float] = None, execution_timeout: Optional[float] = None, name: Optional[str] = None, terminal: Optional[TerminalSize] = None, keep_logs: Optional[KeepLogs] = None) -> ProcessResult ``` Run a command, wait for its shell to exit, and collect its output. #### Sandbox.follow\_build\_logs [#sandboxfollow_build_logs] ```python def follow_build_logs(*, on_logs: _LogsCallback, on_event: Optional[_EventCallback] = None, cursor: Optional[str] = None, timeout: Optional[float] = None) -> BuildLogFollowResult ``` Observe this sandbox's build without changing its execution lifetime. #### Sandbox.fork [#sandboxfork] ```python def fork(*, name: Optional[str] = None, memory: Optional[bool] = None, timeout: Optional[float] = None) -> Sandbox ``` Fork this sandbox. #### Sandbox.get\_network\_policy [#sandboxget_network_policy] ```python def get_network_policy() -> NetworkPolicyInfo ``` #### Sandbox.get\_secrets [#sandboxget_secrets] ```python def get_secrets() -> SandboxSecretsInfo ``` Read this sandbox's attached secret names and their apply state (`GET /sandboxes/{id}/secrets`). #### Sandbox.metrics [#sandboxmetrics] ```python def metrics() -> SystemMetrics ``` #### Sandbox.pause [#sandboxpause] ```python def pause(*, timeout: float = 60) -> None ``` Pause a macOS sandbox, preserving its memory. #### Sandbox.refresh\_data [#sandboxrefresh_data] ```python def refresh_data(*, timeout: Optional[float] = None, wait: SandboxWaitState | None = None, wait_timeout_ms: int | None = None) -> None ``` Refresh sandbox fields from the API. #### Sandbox.replace\_secrets [#sandboxreplace_secrets] ```python def replace_secrets(*, secrets: Sequence[str], if_match: str) -> SandboxSecretsInfo ``` Replace the full set of project secrets attached to this sandbox (`PUT /sandboxes/{id}/secrets`). #### Sandbox.reset\_idle\_timer [#sandboxreset_idle_timer] ```python def reset_idle_timer() -> SandboxLifecycle ``` Reset this sandbox's idle timer (an explicit out-of-band keepalive). #### Sandbox.reset\_network\_policy [#sandboxreset_network_policy] ```python def reset_network_policy(*, if_match: str) -> NetworkPolicyInfo ``` #### Sandbox.resume [#sandboxresume] ```python def resume(*, timeout: float = 60) -> None ``` Resume a paused macOS sandbox and wait for started. #### Sandbox.rotate\_signing\_key [#sandboxrotate_signing_key] ```python def rotate_signing_key() -> None ``` Rotate the sandbox's signing key, invalidating existing pre-signed URLs. #### Sandbox.run\_code [#sandboxrun_code] ```python def run_code(code: str, *, language: str = 'python', context: Optional[InterpreterContext] = None, isolated: bool = False, timeout: Optional[float] = None, cwd: Optional[str] = None, env: Optional[Mapping[str, str]] = None) -> InterpreterResult ``` #### Sandbox.set\_labels [#sandboxset_labels] ```python def set_labels(*, labels: Mapping[str, str]) -> Dict[str, str] ``` Replace the sandbox label set; pass `{}` to clear all labels. #### Sandbox.snapshot\_filesystem [#sandboxsnapshot_filesystem] ```python def snapshot_filesystem(*, name: Optional[str] = None, idle: Optional[int] = None) -> Image ``` Snapshot this sandbox's filesystem as a new `Image` (`POST /sandboxes/{id}/images`). #### Sandbox.start [#sandboxstart] ```python def start(*, timeout: float = 60) -> None ``` Start a stopped sandbox, or resume a paused one, and wait for started. #### Sandbox.stop [#sandboxstop] ```python def stop() -> None ``` Stop a persistent macOS sandbox. #### Sandbox.to\_json [#sandboxto_json] ```python def to_json() -> Dict[str, JsonValue] ``` The sandbox's data as JSON, without any toolbox URL; resume a stored sandbox with `get(info["sandboxId"])`. #### Sandbox.update\_env [#sandboxupdate_env] ```python def update_env(env: Optional[Mapping[str, str]] = None, *, unset: Sequence[str] = ()) -> None ``` Update SDK-managed environment entries for new processes, PTYs, and sessions. #### Sandbox.update\_lifecycle\_policy [#sandboxupdate_lifecycle_policy] ```python def update_lifecycle_policy(*, timeout_seconds: Optional[int] = None, on_timeout: Optional[LifecycleAction] = None, idle_expiry_seconds: Optional[int] = None, on_idle_timeout: Optional[LifecycleAction] = None) -> SandboxLifecycle ``` Update this sandbox's lifecycle policy; omitted knobs stay unchanged. #### Sandbox.update\_network\_policy [#sandboxupdate_network_policy] ```python def update_network_policy(*, network_policy: NetworkPolicyInput, if_match: str) -> NetworkPolicyInfo ``` #### Sandbox.wait [#sandboxwait] ```python def wait(*, until: SandboxWaitState = 'started', timeout: Optional[float] = 60) -> Self ``` Wait for one public sandbox state and return `self`. #### Sandbox.wait\_for\_state [#sandboxwait_for_state] ```python def wait_for_state(states: Sequence[SandboxWaitState], terminal_states: Sequence[SandboxState] = DEFAULT_SANDBOX_TERMINAL_STATES, *, timeout: Optional[float] = None) -> None ``` Wait until the sandbox reaches one of `states`. #### Sandbox.computer\_use [#sandboxcomputer_use] ```python @property def computer_use() -> ComputerUseService ``` #### Sandbox.docker [#sandboxdocker] ```python @property def docker() -> DockerService ``` Docker Engine status inside the sandbox; see `DockerService`. #### Sandbox.fs [#sandboxfs] ```python @property def fs() -> FileSystemService ``` #### Sandbox.git [#sandboxgit] ```python @property def git() -> GitService ``` #### Sandbox.interpreter [#sandboxinterpreter] ```python @property def interpreter() -> InterpreterService ``` #### Sandbox.lsp [#sandboxlsp] ```python @property def lsp() -> LspService ``` #### Sandbox.mac\_boot\_mode [#sandboxmac_boot_mode] ```python @property def mac_boot_mode() -> Optional[MacBootMode] ``` macOS only: how the sandbox resumed, as reported by the API, or None. #### Sandbox.ports [#sandboxports] ```python @property def ports() -> PortsService ``` #### Sandbox.process [#sandboxprocess] ```python @property def process() -> ProcessService ``` #### Sandbox.pty [#sandboxpty] ```python @property def pty() -> PtyService ``` #### Sandbox.raw\_state [#sandboxraw_state] ```python @property def raw_state() -> str ``` Wire status string exactly as the server sent it. #### Sandbox.volumes [#sandboxvolumes] ```python @property def volumes() -> SandboxVolumesService ``` ## AsyncSandbox [#asyncsandbox] ```python class AsyncSandbox() ``` Serializable sandbox handle with process/fs/git/interpreter/pty namespaces. #### AsyncSandbox.\_\_init\_\_ [#asyncsandbox__init__] ```python def __init__(info: SandboxInfo, api: Optional[AsyncTransport], toolbox: Optional[AsyncTransport], *, toolbox_owner: Optional[AsyncTransport] = None, toolbox_url: Optional[str] = None, language: Optional[str] = None, access_token: Optional[str] = None, toolbox_base_url: Optional[str] = None, toolbox_token: Optional[str] = None, direct_toolbox_url: Optional[str] = None, request_timeout: Optional[float] = None, access_token_expires_at: Optional[str] = None, access_token_caller_supplied: Optional[bool] = None, hub: Optional[WaitHub] = None, hub_provider: Optional[Callable[[], Optional[WaitHub]]] = None) -> None ``` #### AsyncSandbox.raw\_state [#asyncsandboxraw_state] ```python @property def raw_state() -> str ``` Wire status string exactly as the server sent it. Informational only — the SDK never branches on this value. Use `state` for all flow-control logic; `raw_state` is useful for logging when `state == "unknown"` (the SDK does not recognize the value). #### AsyncSandbox.from\_api [#asyncsandboxfrom_api] ```python @classmethod def from_api(sandbox_data: SandboxDto | SandboxListItem | Mapping[str, JsonValue], api: Optional[AsyncTransport], toolbox: Optional[AsyncTransport], *, toolbox_owner: Optional[AsyncTransport] = None, toolbox_url: Optional[str] = None, language: Optional[str] = None, access_token: Optional[str] = None, toolbox_base_url: Optional[str] = None, toolbox_token: Optional[str] = None, direct_toolbox_url: Optional[str] = None, request_timeout: Optional[float] = None, access_token_expires_at: Optional[str] = None, access_token_caller_supplied: Optional[bool] = None, hub: Optional[WaitHub] = None, hub_provider: Optional[Callable[[], Optional[WaitHub]]] = None) -> AsyncSandbox ``` Create a sandbox handle from an API response. An explicitly passed `access_token` is treated as caller-supplied (never silently replaced by a minted one) unless `access_token_caller_supplied=False` marks it as the SDK-owned create-response credential. A `toolbox_proxy_url` inside `sandbox_data` is ignored unless the SDK's own refresh/fork paths mark it as a fresh API response, so stored data never chooses where a credential goes. Pass `toolbox` or `toolbox_url` to set the toolbox explicitly — the toolbox credential goes there, so pass only a URL you trust. #### AsyncSandbox.mac\_boot\_mode [#asyncsandboxmac_boot_mode] ```python @property def mac_boot_mode() -> Optional[MacBootMode] ``` macOS only: how the sandbox resumed, as reported by the API, or None. #### AsyncSandbox.process [#asyncsandboxprocess] ```python @property def process() -> AsyncProcessService ``` #### AsyncSandbox.fs [#asyncsandboxfs] ```python @property def fs() -> AsyncFileSystemService ``` #### AsyncSandbox.git [#asyncsandboxgit] ```python @property def git() -> AsyncGitService ``` #### AsyncSandbox.interpreter [#asyncsandboxinterpreter] ```python @property def interpreter() -> AsyncInterpreterService ``` #### AsyncSandbox.pty [#asyncsandboxpty] ```python @property def pty() -> AsyncPtyService ``` #### AsyncSandbox.computer\_use [#asyncsandboxcomputer_use] ```python @property def computer_use() -> AsyncComputerUseService ``` #### AsyncSandbox.docker [#asyncsandboxdocker] ```python @property def docker() -> AsyncDockerService ``` Docker Engine status inside the sandbox; see `AsyncDockerService`. #### AsyncSandbox.ports [#asyncsandboxports] ```python @property def ports() -> AsyncPortsService ``` #### AsyncSandbox.lsp [#asyncsandboxlsp] ```python @property def lsp() -> AsyncLspService ``` #### AsyncSandbox.volumes [#asyncsandboxvolumes] ```python @property def volumes() -> AsyncSandboxVolumesService ``` #### AsyncSandbox.metrics [#asyncsandboxmetrics] ```python async def metrics() -> SystemMetrics ``` #### AsyncSandbox.exec [#asyncsandboxexec] ```python async def exec(command: Optional[str] = None, *, argv: Optional[Sequence[str]] = None, cwd: Optional[str] = None, env: Optional[Mapping[str, str]] = None, user: Optional[str] = None, shell: Optional[str] = None, login: Optional[bool] = None, stdin: StdinMode = 'closed', timeout: Optional[float] = None, execution_timeout: Optional[float] = None, name: Optional[str] = None, terminal: Optional[TerminalSize] = None, keep_logs: Optional[KeepLogs] = None) -> ProcessResult ``` Run a command, wait for its shell to exit, and collect its output. A convenience alias for `process.run` — identical behaviour, same parameters, same return value. **Shell selection.** Passing a string `command` runs it through the sandbox shell: `bash` when the image has it, else `sh`. Pass `shell=` to pin another interpreter, and quote globs and brackets (`pip install -e '.[test]'`) so the command means the same under any shell. Use `argv=` to bypass the shell entirely, which is the safe form for untrusted arguments. For persistent shell state, use `process.create_session`. **Background processes.** The call returns when the shell exits. If the command launches a background child that holds output open (e.g. `python3 -m http.server 8000 &`), the call waits at most ~2 seconds for output to drain and then returns; output the child writes later is not part of the result. For a long-running server use `process.start`, which returns a `ProcessHandle` immediately (logs, wait, kill). Alternatively redirect: `nohup cmd > server.log 2>&1 &`. :param command: Shell command string; mutually exclusive with `argv`. :param argv: Argument vector for shell-free execution. :param cwd: Working directory inside the sandbox. :param env: Extra environment variables merged into the process environment. :param shell: Shell binary to use (e.g. `"bash"`); overrides auto-detection. :param timeout: Caller wait budget in seconds. Omit to wait until the process ends. Does not kill the process; use `execution_timeout` for that. :param execution_timeout: Server-side deadline in seconds. The sandbox kills the process tree when this expires. :returns: `daytona.v2.types.ProcessResult` with `stdout`, `stderr`, `output`, `exit_code`, and `reason`. #### AsyncSandbox.run\_code [#asyncsandboxrun_code] ```python async def run_code(code: str, *, language: str = 'python', context: Optional[AsyncInterpreterContext] = None, isolated: bool = False, timeout: Optional[float] = None, cwd: Optional[str] = None, env: Optional[Mapping[str, str]] = None) -> InterpreterResult ``` #### AsyncSandbox.to\_json [#asyncsandboxto_json] ```python def to_json() -> Dict[str, JsonValue] ``` The sandbox's data as JSON, without any toolbox URL; resume a stored sandbox with `get(info["sandboxId"])`. #### AsyncSandbox.set\_labels [#asyncsandboxset_labels] ```python async def set_labels(*, labels: Mapping[str, str]) -> Dict[str, str] ``` Replace the sandbox label set; pass `{}` to clear all labels. #### AsyncSandbox.entrypoint\_logs [#asyncsandboxentrypoint_logs] ```python async def entrypoint_logs() -> str ``` Return the sandbox entrypoint-session log as text. #### AsyncSandbox.update\_env [#asyncsandboxupdate_env] ```python async def update_env(env: Optional[Mapping[str, str]] = None, *, unset: Sequence[str] = ()) -> None ``` Update SDK-managed environment entries for new processes, PTYs, and sessions. Processes, PTYs, and sessions started after this call inherit the updated environment. Running processes and already-running session kernels keep their current environment unchanged. `unset` removes only values previously set through `update_env()`; image-level environment entries remain untouched. #### AsyncSandbox.refresh\_data [#asyncsandboxrefresh_data] ```python async def refresh_data(*, timeout: Optional[float] = None, wait: SandboxWaitState | None = None, wait_timeout_ms: int | None = None) -> None ``` Refresh sandbox fields from the API. #### AsyncSandbox.wait\_for\_state [#asyncsandboxwait_for_state] ```python async def wait_for_state(states: Sequence[SandboxWaitState], terminal_states: Sequence[SandboxState] = DEFAULT_SANDBOX_TERMINAL_STATES, *, timeout: Optional[float] = None) -> None ``` Wait until the sandbox reaches one of `states`. `timeout` is the caller wait budget in seconds; `None` and `0` wait unbounded. If the sandbox reaches a terminal state before any target state, a typed conflict error is raised with the observed public sandbox state attached as `error.state`. #### AsyncSandbox.wait [#asyncsandboxwait] ```python async def wait(*, until: SandboxWaitState = 'started', timeout: Optional[float] = 60) -> Self ``` Wait for one public sandbox state and return `self`. `timeout` is a caller wait budget in seconds. The default is 60; `None` and `0` wait without a deadline. Timeout raises `RequestTimeoutError` and a terminal state before `until` raises `SandboxTerminalStateError`. #### AsyncSandbox.start [#asyncsandboxstart] ```python async def start(*, timeout: float = 60) -> None ``` Start a stopped sandbox, or resume a paused one, and wait for started. #### AsyncSandbox.pause [#asyncsandboxpause] ```python async def pause(*, timeout: float = 60) -> None ``` Pause a macOS sandbox, preserving its memory. macOS waits up to `timeout` for `paused` and raises `SandboxTerminalStateError` if the pause fails. A paused macOS sandbox keeps its Mac slot but does not keep its reservation renewing. #### AsyncSandbox.resume [#asyncsandboxresume] ```python async def resume(*, timeout: float = 60) -> None ``` Resume a paused macOS sandbox and wait for started. A macOS resume the Mac cannot finish ends `stopped`; this then raises `SandboxTerminalStateError`. #### AsyncSandbox.stop [#asyncsandboxstop] ```python async def stop() -> None ``` Stop a persistent macOS sandbox. #### AsyncSandbox.fork [#asyncsandboxfork] ```python async def fork(*, name: Optional[str] = None, memory: Optional[bool] = None, timeout: Optional[float] = None) -> AsyncSandbox ``` Fork this sandbox. By default the fork continues from the source's memory (running processes included). `memory=False` copies only the disk, and the fork boots fresh. Linux forks are created from running sandboxes and start automatically. A macOS fork copies the disk only: omit `memory` or pass `memory=False` (`memory=True` is refused with `NOT_SUPPORTED_FOR_CLASS`). A fork of a running macOS sandbox boots with a fresh machine identity; a fork of a paused or stopped one rests `stopped`. A fork needs available capacity for its size; insufficient capacity can answer `NO_FREE_SLOT` or `MAC_DISK_FULL`. With `timeout` (seconds; `0` waits without a deadline), wait for the state the fork settles in: `started` for a Linux fork, and `started` or `stopped` for a macOS fork. Without it, return as soon as the server accepts the fork. #### AsyncSandbox.delete [#asyncsandboxdelete] ```python async def delete() -> None ``` Request sandbox deletion. Returning, a `destroyed` state, or a subsequent 404 does not guarantee that the image can already be deleted. Image deletion may still return 409. #### AsyncSandbox.update\_lifecycle\_policy [#asyncsandboxupdate_lifecycle_policy] ```python async def update_lifecycle_policy(*, timeout_seconds: Optional[int] = None, on_timeout: Optional[LifecycleAction] = None, idle_expiry_seconds: Optional[int] = None, on_idle_timeout: Optional[LifecycleAction] = None) -> SandboxLifecycle ``` Update this sandbox's lifecycle policy; omitted knobs stay unchanged. `timeout_seconds` re-anchors the deadline from now (`>= 1`; the timeout cannot be disabled). `idle_expiry_seconds=DISABLED` clears the idle pair; arming it on a sandbox with no idle policy requires `on_idle_timeout`. Setting either action to `"delete"` — or touching a pair whose current or resulting action is `"delete"` — requires the API key to hold `delete:sandboxes` in addition to `write:sandboxes`. #### AsyncSandbox.reset\_idle\_timer [#asyncsandboxreset_idle_timer] ```python async def reset_idle_timer() -> SandboxLifecycle ``` Reset this sandbox's idle timer (an explicit out-of-band keepalive). For work the platform cannot see: bumps the sandbox's activity clock (`last_activity_at`, attributed server-side to the `api` source), which restarts the idle countdown — `idle_timeout_at` re-anchors to now + `idle_expiry_seconds`. The wall-clock `timeout_at` is NOT affected. Succeeds whether or not an idle timeout is armed (an unarmed sandbox echoes `idle_timeout_at=None`), and in any state — a never-started sandbox already carries its creation-time activity stamp, which the reset advances. The echo is the full post-reset lifecycle, the same shape `update_lifecycle_policy` returns. Advance-only: a newer concurrent activity bump keeps the clock, and what comes back is the state that won. #### AsyncSandbox.get\_network\_policy [#asyncsandboxget_network_policy] ```python async def get_network_policy() -> NetworkPolicyInfo ``` #### AsyncSandbox.update\_network\_policy [#asyncsandboxupdate_network_policy] ```python async def update_network_policy(*, network_policy: NetworkPolicyInput, if_match: str) -> NetworkPolicyInfo ``` #### AsyncSandbox.reset\_network\_policy [#asyncsandboxreset_network_policy] ```python async def reset_network_policy(*, if_match: str) -> NetworkPolicyInfo ``` #### AsyncSandbox.get\_secrets [#asyncsandboxget_secrets] ```python async def get_secrets() -> SandboxSecretsInfo ``` Read this sandbox's attached secret names and their apply state (`GET /sandboxes/{id}/secrets`). Returns names and revisions only, never values. `etag` is the `If-Match` value for `replace_secrets`; `status` is `pending` until the sandbox has applied `desired_revision`. #### AsyncSandbox.replace\_secrets [#asyncsandboxreplace_secrets] ```python async def replace_secrets(*, secrets: Sequence[str], if_match: str) -> SandboxSecretsInfo ``` Replace the full set of project secrets attached to this sandbox (`PUT /sandboxes/{id}/secrets`). `secrets` names project secrets; unchanged names remain attached. `if_match` is the `etag` of the last read; a stale one raises `PreconditionFailedError`. The change applies asynchronously: poll `get_secrets` until `status` is `applied`. Running processes keep their environment; processes started afterwards see the new names. #### AsyncSandbox.snapshot\_filesystem [#asyncsandboxsnapshot_filesystem] ```python async def snapshot_filesystem(*, name: Optional[str] = None, idle: Optional[int] = None) -> Image ``` Snapshot this sandbox's filesystem as a new `Image` (`POST /sandboxes/{id}/images`). The result boots new sandboxes (`daytona.create(image.id)`); a Linux sandbox keeps running. A macOS sandbox must be persistent and stopped; it cannot start until the snapshot is `ready`. `name` makes the image named and permanent. `idle` (seconds) is the idle-retention window of an ANONYMOUS capture: it is deleted once that long has passed without a sandbox being created from it (every create restarts the clock). Same rule as `images.build`: omitted or `-1` ⇒ the server maximum (7 days by default); above it ⇒ 400. Promote the image to keep it. `idle` with `name` is a 400. #### AsyncSandbox.create\_snapshot [#asyncsandboxcreate_snapshot] ```python async def create_snapshot(name: str) -> Snapshot ``` #### AsyncSandbox.build\_logs [#asyncsandboxbuild_logs] ```python async def build_logs() -> str ``` Return retained build output as one-shot text, not a live follower. The body includes a state line and the currently available build tail. A sandbox with no image build (for example a registry image) raises `NotFoundError`. Retained-tail truncation is indicated in the text. Use `follow_build_logs` for live output and completeness metadata. #### AsyncSandbox.follow\_build\_logs [#asyncsandboxfollow_build_logs] ```python async def follow_build_logs(*, on_logs: _LogsCallback, on_event: Optional[_EventCallback] = None, cursor: Optional[str] = None, timeout: Optional[float] = None) -> BuildLogFollowResult ``` Observe this sandbox's build without changing its execution lifetime. `on_logs` receives decoded output; optional `on_event` receives each typed `BuildLogEvent`. Either callback may return an awaitable, which is awaited before the next event. `timeout` (seconds) bounds this observation only; cancelling the awaiting task closes the stream, not the build. Discovery failures, including a 404 for a sandbox with no image build, raise `BuildLogInterruptedError` with the HTTP status and last cursor. They do not fall back to another log source. #### AsyncSandbox.create\_access\_token [#asyncsandboxcreate_access_token] ```python async def create_access_token(*, operations: Optional[Sequence[str]] = None, ports: Optional[Sequence[int]] = None, ttl_seconds: Optional[int] = None) -> SandboxAccessToken ``` Mint a scoped, short-lived access token for THIS sandbox. The token authorizes sandbox services (toolbox, SSH, desktop, private previews) and the self-service sandbox routes, for exactly the granted `operations` and `ports` — hand it to a collaborator, a CI job, or a browser instead of a project API key. `operations` is the sandbox-operation vocabulary (`toolbox`, `toolbox:exec`, `toolbox:fs`, `toolbox:git`, `toolbox:lsp`, `desktop`, `ssh`, `sandbox:stop`, `sandbox:pause`, `sandbox:delete`); omitted means the minter's full grantable set, and `[]` is a valid ports-only grant. `ports` names the private-preview ports the token may reach (omitted = all, `[]` = none). `ttl_seconds` overrides the deployment's default lifetime, capped server-side; an unknown operation or an over-cap TTL is a 400, never a silent narrowing. The token cannot be refreshed and cannot mint further credentials — mint a fresh one here instead. #### AsyncSandbox.rotate\_signing\_key [#asyncsandboxrotate_signing_key] ```python async def rotate_signing_key() -> None ``` Rotate the sandbox's signing key, invalidating existing pre-signed URLs. Every pre-signed URL minted so far stops working within ~30 s; new URLs from `presigned_download_url` / `presigned_upload_url` use the new key. The key itself is never returned. Like minting, this requires the API-provided toolbox URL or a sandbox-scoped URL template, rather than an arbitrary custom endpoint. ## SandboxEventsConfig [#sandboxeventsconfig] ```python @dataclass(frozen=True) class SandboxEventsConfig() ``` Configuration for the sandbox-state events hub. `enabled` — set to `False` (or `DAYTONA_SANDBOX_EVENTS=0`) to fall back to long-poll for every wait. `reconcile_interval` is in seconds (`0` / `None` disables the timer). `idle_close` (seconds) closes idle sockets; `None` keeps them open indefinitely. **Attributes**: - `enabled` _bool = True_ - `reconcile_interval` _Optional\[float\] = 60.0_ - `idle_close` _Optional\[float\] = None_ ## SandboxSecretsInfo [#sandboxsecretsinfo] ```python @dataclass(frozen=True) class SandboxSecretsInfo() ``` **Attributes**: - `secrets` _List\[str\]_ - `desired_revision` _int_ - `etag` _str_ - `http_status` _int_ - `applied_revision` _Optional\[int\] = None_ - `status` _Optional\[str\] = None_ - `error` _Optional\[str\] = None_ - `capture_status` _Optional\[str\] = None_ - `capture_unresolved_count` _Optional\[int\] = None_ ## SandboxInfo [#sandboxinfo] ```python @dataclass(frozen=True) class SandboxInfo() ``` Serializable sandbox DTO. **Attributes**: - `id` _str_ - `name` _Optional\[str\] = None_ - `state` _SandboxState = 'unknown'_ - `image` _Optional\[ImageRef\] = None_ - `target` _Optional\[str\] = None_ - `snapshot` _Optional\[SnapshotRef\] = None_ - `image_build_id` _Optional\[str\] = None_ - `region` _Optional\[str\] = field(default=None, kw_only=True)_ - `labels` _Dict\[str, str\] = field(default_factory=dict, kw_only=True)_ - `cpu` _Optional\[float\] = field(default=None, kw_only=True)_ - `cpu_max` _Optional\[float\] = field(default=None, kw_only=True)_ - `memory` _Optional\[float\] = field(default=None, kw_only=True)_ - `memory_max` _Optional\[float\] = field(default=None, kw_only=True)_ - `disk` _Optional\[float\] = field(default=None, kw_only=True)_ - `disk_max` _Optional\[float\] = field(default=None, kw_only=True)_ - `sandbox_class` _Optional\[SandboxClass\] = field(default=None, kw_only=True)_ - `persistent` _Optional\[bool\] = field(default=None, kw_only=True)_ - `spot` _Optional\[bool\] = field(default=None, kw_only=True)_ - `spot_evicted_at` _Optional\[str\] = field(default=None, kw_only=True)_ - `lifecycle_policy` _Optional\[SandboxLifecycle\] = field(default=None, kw_only=True)_ - `forked_from` _Optional\[str\] = field(default=None, kw_only=True)_ - `reservation_id` _Optional\[str\] = field(default=None, kw_only=True)_ - `user` _Optional\[str\] = field(default=None, kw_only=True)_ - `error` _Optional\[str\] = field(default=None, kw_only=True)_ #### SandboxInfo.to\_json [#sandboxinfoto_json] ```python def to_json() -> Dict[str, JsonValue] ``` Return a JSON-safe sandbox-info payload. #### SandboxInfo.from\_json [#sandboxinfofrom_json] ```python @classmethod def from_json(value: Mapping[str, JsonValue]) -> Self ``` Rehydrate sandbox info from `to_json` output. ## SandboxLifecycle [#sandboxlifecycle] ```python @dataclass(frozen=True) class SandboxLifecycle() ``` Lifecycle policy as the API reports it. `timeout_seconds` is the timeout duration; `timeout_at` is the current absolute deadline it derives. `idle_timeout_at` is when `on_idle_timeout` becomes eligible to fire — `last_activity_at + idle_expiry_seconds` — and any activity (traffic, SSH, a non-PTY process or code execution started through the process API that is still running — `exec`, `process.start`, `run_code` and interpreter executions included — or `AsyncSandbox.reset_idle_timer`) pushes it; `None` when the idle pair is not armed or the sandbox has never been active. `timeout_at`, `idle_timeout_at`, `last_activity_at` and `last_activity_source` are server-derived and read-only. An action the SDK does not know yet (a newer server) is passed through as its wire string. **Attributes**: - `timeout_seconds` _Optional\[int\] = None_ - `on_timeout` _Optional\[str\] = None_ - `timeout_at` _Optional\[str\] = None_ - `idle_expiry_seconds` _Optional\[int\] = None_ - `on_idle_timeout` _Optional\[str\] = None_ - `idle_timeout_at` _Optional\[str\] = None_ - `last_activity_at` _Optional\[str\] = None_ - `last_activity_source` _Optional\[str\] = None_ ## PreviewEndpoint [#previewendpoint] ```python @dataclass(frozen=True) class PreviewEndpoint() ``` A sandbox HTTP preview endpoint. **Attributes**: - `port` _int_ - `public` _bool_ - `url` _str_ - `created_at` _Optional\[str\] = None_ ## PreviewLink [#previewlink] ```python @dataclass(frozen=True) class PreviewLink() ``` Preview URL plus an access token for one sandbox port. Send `token` in the `X-Daytona-Preview-Token` header to reach a private endpoint; without a credential it answers 401. Public endpoints set `token` to `""` and need no credential. `expires_at` (RFC 3339) is set when the token's expiry is known, else `None`. Example — curl a private endpoint:: link = await sandbox.ports.preview_link(8080) # curl -H "X-Daytona-Preview-Token: \" \ [#curl--h-x-daytona-preview-token-linktoken-linkurl] For a shareable URL that works in a browser without extra headers, use `daytona.v2.ports.AsyncPortsService.signed_preview_link` instead. **Attributes**: - `url` _str = field(repr=False)_ - `token` _str = field(repr=False)_ - `expires_at` _Optional\[str\] = None_ ## SignedPreviewLink [#signedpreviewlink] ```python @dataclass(frozen=True) class SignedPreviewLink() ``` Self-contained signed URL for one sandbox port. The token is embedded in the hostname — no extra headers or credentials are needed. The link expires at `expires_at` (RFC 3339). Revoke it early with `daytona.v2.ports.AsyncPortsService.expire_signed_preview_link`. **Attributes**: - `url` _str = field(repr=False)_ - `token` _str = field(repr=False)_ - `expires_at` _Optional\[str\] = None_ ## SandboxAccessToken [#sandboxaccesstoken] ```python @dataclass(frozen=True) class SandboxAccessToken() ``` A short-lived per-sandbox access token (`POST …/access-token`). `access_token` is a bearer for sandbox services (toolbox, SSH, desktop, private previews) and for the self-service sandbox routes named by `operations` (`sandbox:stop` / `sandbox:pause` / `sandbox:delete`). It expires at `expires_at` (RFC 3339) and cannot be refreshed — mint a fresh one with `daytona.v2.sandbox.AsyncSandbox.create_access_token` instead. `ports` is the granted private-preview port set; `None` means every port. **Attributes**: - `access_token` _str = field(repr=False)_ - `token_type` _str_ - `expires_at` _str_ - `operations` _Sequence\[str\]_ - `ports` _Optional\[Sequence\[int\]\] = None_ ## SandboxSearchFilters [#sandboxsearchfilters] ```python @dataclass(frozen=True, kw_only=True) class SandboxSearchFilters() ``` The `GET /sandboxes/search` filters shared by `Daytona.search()` and `Daytona.list()`. `status`, `sandbox_class` and `region` take a single value or a list; lists are joined with commas on the wire. `labels` is sent as a JSON object string (containment match); timestamp starts are inclusive and ends are exclusive. Every filter is keyword-only; `ListSandboxesQuery` accepts its pagination parameters positionally. **Attributes**: - `q` _Optional\[str\] = None_ - `status` _Optional\[Sequence\[str\]\] = None_ - `sandbox_class` _Optional\[Union\[SandboxClass, Sequence\[SandboxClass\]\]\] = None_ - `region` _Optional\[Sequence\[str\]\] = None_ - `image_ref` _Optional\[str\] = None_ - `image_ref_prefix` _Optional\[str\] = None_ - `labels` _Optional\[Mapping\[str, str\]\] = None_ - `spot` _Optional\[bool\] = None_ - `forked_from` _Optional\[str\] = None_ - `min_cores` _Optional\[float\] = None_ - `max_cores` _Optional\[float\] = None_ - `min_memory_mib` _Optional\[int\] = None_ - `max_memory_mib` _Optional\[int\] = None_ - `min_disk_mib` _Optional\[int\] = None_ - `max_disk_mib` _Optional\[int\] = None_ - `created_start_at` _Optional\[SearchTimestamp\] = None_ - `created_end_at` _Optional\[SearchTimestamp\] = None_ - `updated_start_at` _Optional\[SearchTimestamp\] = None_ - `updated_end_at` _Optional\[SearchTimestamp\] = None_ - `last_activity_start_at` _Optional\[SearchTimestamp\] = None_ - `last_activity_end_at` _Optional\[SearchTimestamp\] = None_ - `sort` _Optional\[SearchSort\] = None_ - `order` _Optional\[SearchOrder\] = None_ ## SandboxStateSnapshot [#sandboxstatesnapshot] ```python SandboxStateSnapshot = _gen.api.SnapshotListItem ``` ## SystemMetrics [#systemmetrics] ```python SystemMetrics = _gen.toolbox.Metrics ``` ## SandboxWaitState [#sandboxwaitstate] ```python SandboxWaitState = Literal['queued', 'starting', 'started', 'pausing', 'paused', 'stopping', 'stopped', 'destroying', 'destroyed'] ``` ## SandboxClass [#sandboxclass] ```python SandboxClass = Literal['linux', 'macos'] ``` ## MacBootMode [#macbootmode] ```python MacBootMode = str ``` # FileSystem (/docs/python-sdk/file-system) ## FileSystemService [#filesystemservice] ```python class FileSystemService() ``` Sandbox filesystem namespace. #### FileSystemService.\_\_init\_\_ [#filesystemservice__init__] ```python def __init__(impl: AsyncFileSystemService, bridge: SyncBridge) -> None ``` #### FileSystemService.chmod [#filesystemservicechmod] ```python def chmod(path: str, *, mode: Optional[str] = None, owner: Optional[str] = None, group: Optional[str] = None) -> None ``` Set file permissions and ownership. #### FileSystemService.download\_file [#filesystemservicedownload_file] ```python def download_file(remote_path: str, local_path: str | os.PathLike[str], *, on_progress: TransferProgressCallback | None = None, cancel: TransferCancelSignal | None = None) -> None ``` #### FileSystemService.glob [#filesystemserviceglob] ```python def glob(path: str, pattern: str) -> ListResult[str] ``` Return the paths of files under `path` whose base name matches the glob `pattern`. #### FileSystemService.grep [#filesystemservicegrep] ```python def grep(path: str, pattern: str) -> ListResult ``` Search file contents under `path` for the literal substring `pattern`. #### FileSystemService.list [#filesystemservicelist] ```python def list(path: str, *, depth: Optional[int] = None) -> ListResult[FileInfo] ``` List directory entries as typed `FileInfo` items (`items`, `next_cursor`). #### FileSystemService.mkdir [#filesystemservicemkdir] ```python def mkdir(path: str, *, mode: str = '755') -> None ``` Create a directory. #### FileSystemService.move [#filesystemservicemove] ```python def move(source: str, destination: str) -> None ``` Move or rename files. #### FileSystemService.presigned\_download\_url [#filesystemservicepresigned_download_url] ```python def presigned_download_url(path: str, *, expires_in_seconds: int = 3600) -> str ``` Return a pre-signed download URL for a sandbox file. #### FileSystemService.presigned\_upload\_url [#filesystemservicepresigned_upload_url] ```python def presigned_upload_url(path: str, *, expires_in_seconds: int = 3600) -> str ``` Return a pre-signed upload URL for a sandbox file. #### FileSystemService.read\_bytes [#filesystemserviceread_bytes] ```python def read_bytes(path: str) -> bytes ``` Read a file as bytes. #### FileSystemService.read\_many [#filesystemserviceread_many] ```python def read_many(paths: Sequence[str]) -> BulkReadResult ``` Read multiple files, buffering each returned file in memory before returning. #### FileSystemService.read\_text [#filesystemserviceread_text] ```python def read_text(path: str) -> str ``` Read a UTF-8 text file. #### FileSystemService.remove [#filesystemserviceremove] ```python def remove(path: str, *, recursive: bool = False) -> None ``` Remove a file, or a directory with `recursive=True`. #### FileSystemService.replace [#filesystemservicereplace] ```python def replace(files: Sequence[str], pattern: str, new_value: str) -> ListResult ``` Replace text in files. #### FileSystemService.stat [#filesystemservicestat] ```python def stat(path: str) -> FileInfo ``` Return file metadata. #### FileSystemService.upload\_file [#filesystemserviceupload_file] ```python def upload_file(local_path: str | os.PathLike[str], remote_path: str, *, on_progress: TransferProgressCallback | None = None, cancel: TransferCancelSignal | None = None, atomic: bool = False) -> None ``` Stream a local file into the sandbox without buffering it whole in memory. #### FileSystemService.watch\_dir [#filesystemservicewatch_dir] ```python def watch_dir(path: str, on_event: Optional[_WatchCallback] = None, *, recursive: bool = False, on_overflow: Optional[_OverflowCallback] = None, on_exit: Optional[_ExitCallback] = None) -> WatchHandle ``` #### FileSystemService.write\_bytes [#filesystemservicewrite_bytes] ```python def write_bytes(path: str, content: bytes, *, atomic: bool = False) -> None ``` Write bytes to a file, optionally via temp-file + rename. #### FileSystemService.write\_many [#filesystemservicewrite_many] ```python def write_many(files: Mapping[str, bytes], *, atomic: bool = False) -> BulkWriteResult ``` Write several files in one request, optionally atomically per file. #### FileSystemService.write\_text [#filesystemservicewrite_text] ```python def write_text(path: str, content: str, *, atomic: bool = False) -> None ``` Write a UTF-8 text file, optionally via temp-file + rename. ## AsyncFileSystemService [#asyncfilesystemservice] ```python class AsyncFileSystemService() ``` Sandbox filesystem namespace. #### AsyncFileSystemService.\_\_init\_\_ [#asyncfilesystemservice__init__] ```python def __init__(transport: AsyncTransport, *, file_url_signer: Optional[FileUrlSigner] = None) -> None ``` #### AsyncFileSystemService.read\_bytes [#asyncfilesystemserviceread_bytes] ```python async def read_bytes(path: str) -> bytes ``` Read a file as bytes. #### AsyncFileSystemService.read\_text [#asyncfilesystemserviceread_text] ```python async def read_text(path: str) -> str ``` Read a UTF-8 text file. #### AsyncFileSystemService.write\_bytes [#asyncfilesystemservicewrite_bytes] ```python async def write_bytes(path: str, content: bytes, *, atomic: bool = False) -> None ``` Write bytes to a file, optionally via temp-file + rename. #### AsyncFileSystemService.write\_text [#asyncfilesystemservicewrite_text] ```python async def write_text(path: str, content: str, *, atomic: bool = False) -> None ``` Write a UTF-8 text file, optionally via temp-file + rename. #### AsyncFileSystemService.presigned\_download\_url [#asyncfilesystemservicepresigned_download_url] ```python async def presigned_download_url(path: str, *, expires_in_seconds: int = 3600) -> str ``` Return a pre-signed download URL for a sandbox file. The signature is minted by the API; `expires_in_seconds` must be between 1 and `SIGNED_FILE_MAX_TTL_SECONDS` (7 days). #### AsyncFileSystemService.presigned\_upload\_url [#asyncfilesystemservicepresigned_upload_url] ```python async def presigned_upload_url(path: str, *, expires_in_seconds: int = 3600) -> str ``` Return a pre-signed upload URL for a sandbox file. The signature is minted by the API; `expires_in_seconds` must be between 1 and `SIGNED_FILE_MAX_TTL_SECONDS` (7 days). #### AsyncFileSystemService.write\_many [#asyncfilesystemservicewrite_many] ```python async def write_many(files: Mapping[str, bytes], *, atomic: bool = False) -> BulkWriteResult ``` Write several files in one request, optionally atomically per file. #### AsyncFileSystemService.upload\_file [#asyncfilesystemserviceupload_file] ```python async def upload_file(local_path: str | os.PathLike[str], remote_path: str, *, on_progress: TransferProgressCallback | None = None, cancel: TransferCancelSignal | None = None, atomic: bool = False) -> None ``` Stream a local file into the sandbox without buffering it whole in memory. #### AsyncFileSystemService.download\_file [#asyncfilesystemservicedownload_file] ```python async def download_file(remote_path: str, local_path: str | os.PathLike[str], *, on_progress: TransferProgressCallback | None = None, cancel: TransferCancelSignal | None = None) -> None ``` #### AsyncFileSystemService.read\_many [#asyncfilesystemserviceread_many] ```python async def read_many(paths: Sequence[str]) -> BulkReadResult ``` Read multiple files, buffering each returned file in memory before returning. Non-200 responses raise the typed SDK error inside the transport; only a 200 multipart body reaches the parser. #### AsyncFileSystemService.list [#asyncfilesystemservicelist] ```python async def list(path: str, *, depth: Optional[int] = None) -> ListResult[FileInfo] ``` List directory entries as typed `FileInfo` items (`items`, `next_cursor`). #### AsyncFileSystemService.stat [#asyncfilesystemservicestat] ```python async def stat(path: str) -> FileInfo ``` Return file metadata. #### AsyncFileSystemService.mkdir [#asyncfilesystemservicemkdir] ```python async def mkdir(path: str, *, mode: str = '755') -> None ``` Create a directory. #### AsyncFileSystemService.remove [#asyncfilesystemserviceremove] ```python async def remove(path: str, *, recursive: bool = False) -> None ``` Remove a file, or a directory with `recursive=True`. #### AsyncFileSystemService.move [#asyncfilesystemservicemove] ```python async def move(source: str, destination: str) -> None ``` Move or rename files. #### AsyncFileSystemService.grep [#asyncfilesystemservicegrep] ```python async def grep(path: str, pattern: str) -> ListResult ``` Search file contents under `path` for the literal substring `pattern`. Returns matches with one-based line numbers. #### AsyncFileSystemService.glob [#asyncfilesystemserviceglob] ```python async def glob(path: str, pattern: str) -> ListResult[str] ``` Return the paths of files under `path` whose base name matches the glob `pattern`. #### AsyncFileSystemService.replace [#asyncfilesystemservicereplace] ```python async def replace(files: Sequence[str], pattern: str, new_value: str) -> ListResult ``` Replace text in files. #### AsyncFileSystemService.chmod [#asyncfilesystemservicechmod] ```python async def chmod(path: str, *, mode: Optional[str] = None, owner: Optional[str] = None, group: Optional[str] = None) -> None ``` Set file permissions and ownership. #### AsyncFileSystemService.watch\_dir [#asyncfilesystemservicewatch_dir] ```python async def watch_dir(path: str, on_event: Optional[_WatchCallback] = None, *, recursive: bool = False, on_overflow: Optional[_OverflowCallback] = None, on_exit: Optional[_ExitCallback] = None) -> AsyncWatchHandle ``` ## WatchHandle [#watchhandle] ```python class WatchHandle() ``` A running directory watch. #### WatchHandle.\_\_init\_\_ [#watchhandle__init__] ```python def __init__(impl: AsyncWatchHandle, bridge: SyncBridge) -> None ``` #### WatchHandle.attach\_reader [#watchhandleattach_reader] ```python def attach_reader(reader: asyncio.Task[None]) -> None ``` #### WatchHandle.get\_new\_events [#watchhandleget_new_events] ```python def get_new_events() -> list[FilesystemEvent] ``` #### WatchHandle.record\_callback\_error [#watchhandlerecord_callback_error] ```python def record_callback_error(error: Exception) -> None ``` #### WatchHandle.record\_exit [#watchhandlerecord_exit] ```python def record_exit(error: Exception | None) -> None ``` #### WatchHandle.record\_overflow [#watchhandlerecord_overflow] ```python def record_overflow() -> None ``` #### WatchHandle.stop [#watchhandlestop] ```python def stop() -> None ``` #### WatchHandle.wait\_for\_exit [#watchhandlewait_for_exit] ```python def wait_for_exit() -> Exception | None ``` #### WatchHandle.exit\_error [#watchhandleexit_error] ```python @property def exit_error() -> Exception | None ``` #### WatchHandle.last\_callback\_error [#watchhandlelast_callback_error] ```python @property def last_callback_error() -> Exception | None ``` #### WatchHandle.overflow\_count [#watchhandleoverflow_count] ```python @property def overflow_count() -> int ``` ## AsyncWatchHandle [#asyncwatchhandle] ```python class AsyncWatchHandle() ``` A running directory watch. Single-task, single-loop: the reader is one `asyncio.Task` and every method runs on the same loop, so the sync version's five locks collapse to plain attributes. Only the exit event survives, because `wait_for_exit` genuinely waits. #### AsyncWatchHandle.\_\_init\_\_ [#asyncwatchhandle__init__] ```python def __init__(stream: _LineStream, events: asyncio.Queue[FilesystemEvent], on_exit: Optional[_ExitCallback] = None) -> None ``` #### AsyncWatchHandle.overflow\_count [#asyncwatchhandleoverflow_count] ```python @property def overflow_count() -> int ``` #### AsyncWatchHandle.attach\_reader [#asyncwatchhandleattach_reader] ```python def attach_reader(reader: asyncio.Task[None]) -> None ``` #### AsyncWatchHandle.exit\_error [#asyncwatchhandleexit_error] ```python @property def exit_error() -> Exception | None ``` #### AsyncWatchHandle.last\_callback\_error [#asyncwatchhandlelast_callback_error] ```python @property def last_callback_error() -> Exception | None ``` #### AsyncWatchHandle.record\_callback\_error [#asyncwatchhandlerecord_callback_error] ```python def record_callback_error(error: Exception) -> None ``` #### AsyncWatchHandle.record\_exit [#asyncwatchhandlerecord_exit] ```python async def record_exit(error: Exception | None) -> None ``` #### AsyncWatchHandle.record\_overflow [#asyncwatchhandlerecord_overflow] ```python def record_overflow() -> None ``` #### AsyncWatchHandle.wait\_for\_exit [#asyncwatchhandlewait_for_exit] ```python async def wait_for_exit() -> Exception | None ``` #### AsyncWatchHandle.get\_new\_events [#asyncwatchhandleget_new_events] ```python def get_new_events() -> list[FilesystemEvent] ``` #### AsyncWatchHandle.stop [#asyncwatchhandlestop] ```python async def stop() -> None ``` ## FileInfo [#fileinfo] ```python class FileInfo(BaseModel) ``` One filesystem entry returned by `/files` and `/files/info`. **Attributes**: - `group` _StrictStr = Field(description='Numeric group id rendered as a string.')_ - `is_dir` _StrictBool = Field(description='Whether the entry is a directory.', alias='isDir')_ - `mod_time` _StrictStr = Field(description='Last modification time as a formatted string. Prefer `modifiedAt` for RFC 3339 formatting.', alias='modTime')_ - `mode` _StrictStr = Field(description='File mode string, for example `-rw-r--r--` or `drwxr-xr-x`.')_ - `modified_at` _StrictStr = Field(description='RFC 3339 UTC timestamp for the last modification time.', alias='modifiedAt')_ - `name` _StrictStr = Field(description='Base name of the entry.')_ - `owner` _StrictStr = Field(description='Numeric owner id rendered as a string.')_ - `path` _StrictStr = Field(description="Absolute path to the entry, using the sandbox's path syntax.")_ - `permissions` _StrictStr = Field(description='Four-digit octal permissions (`0644`, `0755`, …).')_ - `size` _Annotated\[int, Field(strict=True, ge=0)\] = Field(description='Entry size in bytes.')_ - `additional_properties` _Dict\[str, Any\] = \{\}_ ##### model\_config [#model_config] ```python model_config = ConfigDict(populate_by_name=True, validate_assignment=True, protected_namespaces=()) ``` #### FileInfo.to\_str [#fileinfoto_str] ```python def to_str() -> str ``` Returns the string representation of the model using alias #### FileInfo.to\_json [#fileinfoto_json] ```python def to_json() -> str ``` Returns the JSON representation of the model using alias #### FileInfo.from\_json [#fileinfofrom_json] ```python @classmethod def from_json(json_str: str) -> Optional[Self] ``` Create an instance of FileInfo from a JSON string #### FileInfo.to\_dict [#fileinfoto_dict] ```python 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. #### FileInfo.from\_dict [#fileinfofrom_dict] ```python @classmethod def from_dict(obj: Optional[Dict[str, Any]]) -> Optional[Self] ``` Create an instance of FileInfo from a dict ## TransferCancelSignal [#transfercancelsignal] ```python class TransferCancelSignal(Protocol) ``` A cancellation signal for file transfers. `asyncio.Event` and `threading.Event` both satisfy this protocol. #### TransferCancelSignal.is\_set [#transfercancelsignalis_set] ```python def is_set() -> bool ``` ## FilesystemEventType [#filesystemeventtype] ```python class FilesystemEventType(str, Enum) ``` **Attributes**: - `CREATE` _'create'_ - `WRITE` _'write'_ - `REMOVE` _'remove'_ - `RENAME` _'rename'_ - `CHMOD` _'chmod'_ ## SearchResult [#searchresult] ```python @dataclass(frozen=True) class SearchResult(Generic[T]) ``` One page of `GET /sandboxes/search` (`Daytona.search()`). `total` is exact when `total_relation == "eq"` and a lower bound when it is `"gte"` (exact counting is capped at 10 000). **Attributes**: - `items` _List\[T\]_ - `next_cursor` _Optional\[str\] = None_ - `total` _int = 0_ - `total_relation` _SearchTotalRelation = 'eq'_ - `raw_total_relation` _str = 'eq'_ ## FilesystemEvent [#filesystemevent] ```python @dataclass(frozen=True, slots=True) class FilesystemEvent() ``` **Attributes**: - `type` _FilesystemEventType_ - `name` _str_ - `is_dir` _bool_ - `timestamp` _int_ ## BulkWriteFile [#bulkwritefile] ```python @dataclass(frozen=True) class BulkWriteFile() ``` **Attributes**: - `path` _str_ - `bytes` _int_ ## BulkWriteResult [#bulkwriteresult] ```python @dataclass(frozen=True) class BulkWriteResult() ``` **Attributes**: - `files` _List\[BulkWriteFile\]_ - `errors` _List\[str\] = field(default_factory=list)_ ## BulkReadError [#bulkreaderror] ```python @dataclass(frozen=True) class BulkReadError() ``` **Attributes**: - `path` _str_ - `message` _str_ - `code` _Optional\[str\] = None_ - `source` _Optional\[str\] = None_ ## BulkReadResult [#bulkreadresult] ```python @dataclass(frozen=True) class BulkReadResult() ``` **Attributes**: - `files` _Dict\[str, bytes\]_ - `errors` _List\[BulkReadError\] = field(default_factory=list)_ ## SearchSandboxesQuery [#searchsandboxesquery] ```python @dataclass(frozen=True, kw_only=True) class SearchSandboxesQuery(SandboxSearchFilters) ``` Every `Daytona.search()` parameter (`GET /sandboxes/search`); keyword-only. **Attributes**: - `name_prefix` _Optional\[str\] = None_ - `id_prefix` _Optional\[str\] = None_ - `cursor` _Optional\[str\] = None_ - `limit` _Optional\[int\] = None_ ## SIGNED\_FILE\_MAX\_TTL\_SECONDS [#signed_file_max_ttl_seconds] ```python SIGNED_FILE_MAX_TTL_SECONDS = 604800 ``` ## TransferProgressCallback [#transferprogresscallback] ```python TransferProgressCallback = Callable[[int, Optional[int]], None] ``` ## SearchTotalRelation [#searchtotalrelation] ```python SearchTotalRelation = Literal['eq', 'gte', 'unknown'] ``` ## SearchSort [#searchsort] ```python SearchSort = Literal['created_at', 'updated_at', 'last_activity_at', 'name', 'cores', 'memory_mib', 'disk_mib'] ``` ## SearchOrder [#searchorder] ```python SearchOrder = Literal['asc', 'desc'] ``` ## SearchTimestamp [#searchtimestamp] ```python SearchTimestamp = Union[str, datetime] ``` An RFC 3339 string, or a `datetime` (naive values are taken as UTC). # Git (/docs/python-sdk/git) ## GitService [#gitservice] ```python class GitService() ``` Sandbox git namespace. #### GitService.\_\_init\_\_ [#gitservice__init__] ```python def __init__(impl: AsyncGitService, bridge: SyncBridge) -> None ``` #### GitService.add [#gitserviceadd] ```python def add(path: str, files: Sequence[str]) -> None ``` Stage files. #### GitService.add\_remote [#gitserviceadd_remote] ```python def add_remote(path: str, name: str, url: str) -> None ``` #### GitService.checkout\_branch [#gitservicecheckout_branch] ```python def checkout_branch(path: str, branch: str) -> None ``` Checkout a branch. #### GitService.clone [#gitserviceclone] ```python def clone(url: str, path: str, *, branch: Optional[str] = None, commit_id: Optional[str] = None, depth: Optional[int] = None, insecure_skip_tls: bool = False, username: Optional[str] = None, password: Optional[str] = None, timeout: Optional[float] = None) -> None ``` Clone a repository, optionally shallow and with per-call TLS relaxation. #### GitService.commit [#gitservicecommit] ```python def commit(path: str, message: str, *, author: str, email: str, allow_empty: bool = False) -> GitCommitResponse ``` Commit staged changes, optionally allowing an empty commit. #### GitService.create\_branch [#gitservicecreate_branch] ```python def create_branch(path: str, name: str) -> None ``` Create a branch. #### GitService.delete\_branch [#gitservicedelete_branch] ```python def delete_branch(path: str, name: str) -> None ``` Delete a branch. #### GitService.get\_config [#gitserviceget_config] ```python def get_config(key: str, *, path: Optional[str] = None, scope: str = 'global') -> Optional[str] ``` #### GitService.history [#gitservicehistory] ```python def history(path: str) -> ListResult ``` List commits, newest first. #### GitService.init [#gitserviceinit] ```python def init(path: str, *, bare: bool = False, initial_branch: Optional[str] = None) -> None ``` #### GitService.list\_branches [#gitservicelist_branches] ```python def list_branches(path: str) -> ListResult ``` List branch names as \{items, next_cursor\}. #### GitService.list\_remotes [#gitservicelist_remotes] ```python def list_remotes(path: str) -> ListResult[JsonObject] ``` #### GitService.pull [#gitservicepull] ```python def pull(path: str, *, username: Optional[str] = None, password: Optional[str] = None, branch: Optional[str] = None, remote: Optional[str] = None, timeout: Optional[float] = None) -> None ``` Pull from the configured or named remote. #### GitService.push [#gitservicepush] ```python def push(path: str, *, username: Optional[str] = None, password: Optional[str] = None, branch: Optional[str] = None, remote: Optional[str] = None, set_upstream: bool = False, timeout: Optional[float] = None) -> None ``` Push to the configured or named remote. #### GitService.reset [#gitservicereset] ```python def reset(path: str, *, mode: Optional[str] = None, target: Optional[str] = None, files: Optional[Sequence[str]] = None) -> None ``` #### GitService.restore [#gitservicerestore] ```python def restore(path: str, files: Sequence[str], *, staged: Optional[bool] = None, worktree: Optional[bool] = None, source: Optional[str] = None) -> None ``` #### GitService.set\_config [#gitserviceset_config] ```python def set_config(key: str, value: str, *, path: Optional[str] = None, scope: str = 'global') -> None ``` #### GitService.status [#gitservicestatus] ```python def status(path: str) -> GitStatus ``` Return git status. ## AsyncGitService [#asyncgitservice] ```python class AsyncGitService() ``` Sandbox git namespace. #### AsyncGitService.\_\_init\_\_ [#asyncgitservice__init__] ```python def __init__(transport: AsyncTransport) -> None ``` #### AsyncGitService.clone [#asyncgitserviceclone] ```python async def clone(url: str, path: str, *, branch: Optional[str] = None, commit_id: Optional[str] = None, depth: Optional[int] = None, insecure_skip_tls: bool = False, username: Optional[str] = None, password: Optional[str] = None, timeout: Optional[float] = None) -> None ``` Clone a repository, optionally shallow and with per-call TLS relaxation. #### AsyncGitService.init [#asyncgitserviceinit] ```python async def init(path: str, *, bare: bool = False, initial_branch: Optional[str] = None) -> None ``` #### AsyncGitService.status [#asyncgitservicestatus] ```python async def status(path: str) -> GitStatus ``` Return git status. #### AsyncGitService.list\_branches [#asyncgitservicelist_branches] ```python async def list_branches(path: str) -> ListResult ``` List branch names as \{items, next_cursor\}. #### AsyncGitService.list\_remotes [#asyncgitservicelist_remotes] ```python async def list_remotes(path: str) -> ListResult[JsonObject] ``` #### AsyncGitService.history [#asyncgitservicehistory] ```python async def history(path: str) -> ListResult ``` List commits, newest first. #### AsyncGitService.create\_branch [#asyncgitservicecreate_branch] ```python async def create_branch(path: str, name: str) -> None ``` Create a branch. #### AsyncGitService.add\_remote [#asyncgitserviceadd_remote] ```python async def add_remote(path: str, name: str, url: str) -> None ``` #### AsyncGitService.delete\_branch [#asyncgitservicedelete_branch] ```python async def delete_branch(path: str, name: str) -> None ``` Delete a branch. #### AsyncGitService.checkout\_branch [#asyncgitservicecheckout_branch] ```python async def checkout_branch(path: str, branch: str) -> None ``` Checkout a branch. #### AsyncGitService.add [#asyncgitserviceadd] ```python async def add(path: str, files: Sequence[str]) -> None ``` Stage files. #### AsyncGitService.reset [#asyncgitservicereset] ```python async def reset(path: str, *, mode: Optional[str] = None, target: Optional[str] = None, files: Optional[Sequence[str]] = None) -> None ``` #### AsyncGitService.restore [#asyncgitservicerestore] ```python async def restore(path: str, files: Sequence[str], *, staged: Optional[bool] = None, worktree: Optional[bool] = None, source: Optional[str] = None) -> None ``` #### AsyncGitService.commit [#asyncgitservicecommit] ```python async def commit(path: str, message: str, *, author: str, email: str, allow_empty: bool = False) -> GitCommitResponse ``` Commit staged changes, optionally allowing an empty commit. #### AsyncGitService.pull [#asyncgitservicepull] ```python async def pull(path: str, *, username: Optional[str] = None, password: Optional[str] = None, branch: Optional[str] = None, remote: Optional[str] = None, timeout: Optional[float] = None) -> None ``` Pull from the configured or named remote. #### AsyncGitService.push [#asyncgitservicepush] ```python async def push(path: str, *, username: Optional[str] = None, password: Optional[str] = None, branch: Optional[str] = None, remote: Optional[str] = None, set_upstream: bool = False, timeout: Optional[float] = None) -> None ``` Push to the configured or named remote. #### AsyncGitService.get\_config [#asyncgitserviceget_config] ```python async def get_config(key: str, *, path: Optional[str] = None, scope: str = 'global') -> Optional[str] ``` #### AsyncGitService.set\_config [#asyncgitserviceset_config] ```python async def set_config(key: str, value: str, *, path: Optional[str] = None, scope: str = 'global') -> None ``` ## GitCommitResponse [#gitcommitresponse] ```python GitCommitResponse = _gen.toolbox.CommitResponse ``` ## GitStatus [#gitstatus] ```python GitStatus = _gen.toolbox.StatusResponse ``` # Process (/docs/python-sdk/process) ## ProcessHandle [#processhandle] ```python class ProcessHandle() ``` Serializable handle for one sandbox process. #### ProcessHandle.\_\_init\_\_ [#processhandle__init__] ```python def __init__(impl: AsyncProcessHandle, bridge: SyncBridge) -> None ``` #### ProcessHandle.sandbox\_id [#processhandlesandbox_id] ```python @property def sandbox_id() -> str ``` #### ProcessHandle.process\_id [#processhandleprocess_id] ```python @property def process_id() -> str ``` #### ProcessHandle.id [#processhandleid] ```python @property def id() -> str ``` #### ProcessHandle.kind [#processhandlekind] ```python @property def kind() -> Literal['exec', 'pty', 'code', 'session'] | None ``` #### ProcessHandle.close\_stdin [#processhandleclose_stdin] ```python def close_stdin() -> None ``` Close the stdin of an exec or PTY process (EOF). #### ProcessHandle.delete [#processhandledelete] ```python def delete() -> None ``` Delete the process record and retained logs, stopping it first. #### ProcessHandle.from\_json [#processhandlefrom_json] ```python @classmethod def from_json(value: Mapping[str, str]) -> ProcessHandle ``` Rehydrate a handle identity without making a network request. #### ProcessHandle.get [#processhandleget] ```python def get() -> ProcessInfo ``` Fetch current process metadata. #### ProcessHandle.kill [#processhandlekill] ```python def kill(*, signal: SignalName = 'TERM', escalate_after: Optional[float] = None, escalate_to: SignalName = 'KILL') -> None ``` Send a signal and optional escalation signal. #### ProcessHandle.logs [#processhandlelogs] ```python def logs(*, cursor: Optional[str] = None, limit: Optional[int] = None, encoding: LogEncoding = 'text') -> LogPage ``` Read a cursor-replayable process log page. #### ProcessHandle.ref [#processhandleref] ```python def ref() -> ProcessHandleRef ``` Return a typed handle identity. #### ProcessHandle.resize [#processhandleresize] ```python def resize(cols: int, rows: int) -> None ``` Resize a PTY process. #### ProcessHandle.stream\_logs [#processhandlestream_logs] ```python def stream_logs(*, cursor: Optional[str] = None, encoding: LogEncoding = 'text') -> Iterator[LogFrame] ``` Follow process logs with SSE while retaining cursor replay semantics. #### ProcessHandle.to\_json [#processhandleto_json] ```python def to_json() -> Dict[str, str] ``` Return a JSON-safe handle identity. #### ProcessHandle.wait [#processhandlewait] ```python def wait(*, timeout: Optional[float] = None) -> WaitResult ``` Wait for terminal state using the process long-poll contract. #### ProcessHandle.write\_stdin [#processhandlewrite_stdin] ```python def write_stdin(data: Union[str, bytes]) -> None ``` Write to the stdin of an exec or PTY process created with stdin='open'. ## AsyncProcessHandle [#asyncprocesshandle] ```python class AsyncProcessHandle() ``` Serializable handle for one sandbox process. #### AsyncProcessHandle.\_\_init\_\_ [#asyncprocesshandle__init__] ```python def __init__(sandbox_id: str, process_id: str, transport: Optional[AsyncTransport] = None, kind: Optional[ProcessKind] = None) -> None ``` #### AsyncProcessHandle.to\_json [#asyncprocesshandleto_json] ```python def to_json() -> Dict[str, str] ``` Return a JSON-safe handle identity. #### AsyncProcessHandle.from\_json [#asyncprocesshandlefrom_json] ```python @classmethod def from_json(value: Mapping[str, str]) -> AsyncProcessHandle ``` Rehydrate a handle identity without making a network request. #### AsyncProcessHandle.ref [#asyncprocesshandleref] ```python def ref() -> ProcessHandleRef ``` Return a typed handle identity. #### AsyncProcessHandle.bind [#asyncprocesshandlebind] ```python def bind(transport: AsyncTransport) -> AsyncProcessHandle ``` Return this handle bound to a transport. #### AsyncProcessHandle.get [#asyncprocesshandleget] ```python async def get() -> ProcessInfo ``` Fetch current process metadata. #### AsyncProcessHandle.wait [#asyncprocesshandlewait] ```python async def wait(*, timeout: Optional[float] = None) -> WaitResult ``` Wait for terminal state using the process long-poll contract. `timeout` is the caller wait budget in seconds; `0` waits unbounded. #### AsyncProcessHandle.logs [#asyncprocesshandlelogs] ```python async def logs(*, cursor: Optional[str] = None, limit: Optional[int] = None, encoding: LogEncoding = 'text') -> LogPage ``` Read a cursor-replayable process log page. #### AsyncProcessHandle.stream\_logs [#asyncprocesshandlestream_logs] ```python async def stream_logs(*, cursor: Optional[str] = None, encoding: LogEncoding = 'text') -> AsyncIterator[LogFrame] ``` Follow process logs with SSE while retaining cursor replay semantics. #### AsyncProcessHandle.write\_stdin [#asyncprocesshandlewrite_stdin] ```python async def write_stdin(data: Union[str, bytes]) -> None ``` Write to the stdin of an exec or PTY process created with stdin='open'. #### AsyncProcessHandle.close\_stdin [#asyncprocesshandleclose_stdin] ```python async def close_stdin() -> None ``` Close the stdin of an exec or PTY process (EOF). #### AsyncProcessHandle.kill [#asyncprocesshandlekill] ```python async def kill(*, signal: SignalName = 'TERM', escalate_after: Optional[float] = None, escalate_to: SignalName = 'KILL') -> None ``` Send a signal and optional escalation signal. #### AsyncProcessHandle.resize [#asyncprocesshandleresize] ```python async def resize(cols: int, rows: int) -> None ``` Resize a PTY process. #### AsyncProcessHandle.delete [#asyncprocesshandledelete] ```python async def delete() -> None ``` Delete the process record and retained logs, stopping it first. Raises `UnsupportedOperationError` for a running code cell and for a session command that has not stopped within 5 s: delete its session. ## ProcessService [#processservice] ```python class ProcessService() ``` Sandbox process namespace. #### ProcessService.\_\_init\_\_ [#processservice__init__] ```python def __init__(impl: AsyncProcessService, bridge: SyncBridge) -> None ``` #### ProcessService.connect [#processserviceconnect] ```python def connect(process_id: Union[str, Mapping[str, str]]) -> ProcessHandle ``` Create a bound process handle without fetching metadata. #### ProcessService.connect\_session [#processserviceconnect_session] ```python def connect_session(session_id: str | Mapping[str, object]) -> Session ``` Bind a session id or serialized identity without making a request. #### ProcessService.create\_session [#processservicecreate_session] ```python def create_session(*, cwd: Optional[str] = None, env: Optional[Mapping[str, str]] = None, shell: Optional[str] = None, login: Optional[bool] = None, name: Optional[str] = None) -> Session ``` Create one persistent shell; cwd and env apply to all its commands. #### ProcessService.get [#processserviceget] ```python def get(process_id: str) -> ProcessInfo ``` Fetch current process metadata by id or live name alias. #### ProcessService.list [#processservicelist] ```python def list(*, state: Optional[ProcessStateFilter] = None, kind: Optional[ProcessKind] = None, session_id: Optional[str] = None, name: Optional[str] = None, pid: Optional[int] = None) -> ListResult[ProcessInfo] ``` #### ProcessService.run [#processservicerun] ```python def run(command: Optional[str] = None, *, argv: Optional[Sequence[str]] = None, cwd: Optional[str] = None, env: Optional[Mapping[str, str]] = None, user: Optional[str] = None, shell: Optional[str] = None, login: Optional[bool] = None, stdin: StdinMode = 'closed', timeout: Optional[float] = None, execution_timeout: Optional[float] = None, name: Optional[str] = None, terminal: Optional[TerminalSize] = None, keep_logs: Optional[KeepLogs] = None) -> ProcessResult ``` Start a process, wait for its shell to exit, and collect its output. #### ProcessService.start [#processservicestart] ```python def start(command: Optional[str] = None, *, argv: Optional[Sequence[str]] = None, name: Optional[str] = None, cwd: Optional[str] = None, env: Optional[Mapping[str, str]] = None, user: Optional[str] = None, shell: Optional[str] = None, login: Optional[bool] = None, stdin: StdinMode = 'closed', execution_timeout: Optional[float] = None, terminal: Optional[TerminalSize] = None, keep_logs: Optional[KeepLogs] = None) -> ProcessHandle ``` Start a detached process and return a handle immediately. ## AsyncProcessService [#asyncprocessservice] ```python class AsyncProcessService() ``` Sandbox process namespace. #### AsyncProcessService.\_\_init\_\_ [#asyncprocessservice__init__] ```python def __init__(sandbox_id: str, transport: AsyncTransport, language: Optional[str] = None) -> None ``` #### AsyncProcessService.create\_session [#asyncprocessservicecreate_session] ```python async def create_session(*, cwd: Optional[str] = None, env: Optional[Mapping[str, str]] = None, shell: Optional[str] = None, login: Optional[bool] = None, name: Optional[str] = None) -> AsyncSession ``` Create one persistent shell; cwd and env apply to all its commands. `shell` must be a POSIX shell (bash, sh, dash, zsh, ksh) on Linux and macOS; another shell is refused when the session is created. #### AsyncProcessService.connect\_session [#asyncprocessserviceconnect_session] ```python def connect_session(session_id: str | Mapping[str, object]) -> AsyncSession ``` Bind a session id or serialized identity without making a request. #### AsyncProcessService.start [#asyncprocessservicestart] ```python async def start(command: Optional[str] = None, *, argv: Optional[Sequence[str]] = None, name: Optional[str] = None, cwd: Optional[str] = None, env: Optional[Mapping[str, str]] = None, user: Optional[str] = None, shell: Optional[str] = None, login: Optional[bool] = None, stdin: StdinMode = 'closed', execution_timeout: Optional[float] = None, terminal: Optional[TerminalSize] = None, keep_logs: Optional[KeepLogs] = None) -> AsyncProcessHandle ``` Start a detached process and return a handle immediately. Unlike `run`, this returns as soon as the sandbox has started the process. Use the returned `ProcessHandle` to stream logs (`handle.stream_logs()`), wait for exit (`handle.wait()`), or kill (`handle.kill()`). This is the right choice for long-running servers — call `start()` once, then poll the port or stream logs to confirm the server is ready. **Shell selection.** A string `command` runs through the sandbox shell (`bash`, else `sh`; pin another with `shell=`). Quote globs and brackets (`pip install -e '.[test]'`). Use `argv=` to bypass the shell for untrusted input. For persistent shell state, use `create_session`. :param command: Shell command string; mutually exclusive with `argv`. :param argv: Argument vector for shell-free execution. :param cwd: Working directory inside the sandbox. :param env: Extra environment variables merged into the process environment. :param shell: Shell binary to use (e.g. `"bash"`); overrides auto-detection. :param execution_timeout: Server-side deadline in seconds. The sandbox kills the process tree when this expires. :returns: Bound `ProcessHandle` — logs, wait, and kill are available immediately. Example — start an HTTP server and wait for it to be ready:: handle = await sandbox.process.start("python3 -m http.server 8000") # poll or stream logs; the process keeps running in the background [#poll-or-stream-logs-the-process-keeps-running-in-the-background] #### AsyncProcessService.run [#asyncprocessservicerun] ```python async def run(command: Optional[str] = None, *, argv: Optional[Sequence[str]] = None, cwd: Optional[str] = None, env: Optional[Mapping[str, str]] = None, user: Optional[str] = None, shell: Optional[str] = None, login: Optional[bool] = None, stdin: StdinMode = 'closed', timeout: Optional[float] = None, execution_timeout: Optional[float] = None, name: Optional[str] = None, terminal: Optional[TerminalSize] = None, keep_logs: Optional[KeepLogs] = None) -> ProcessResult ``` Start a process, wait for its shell to exit, and collect its output. The common case is one round trip: the sandbox starts the process, holds the request until it exits (or `timeout` expires), and returns the output inline. A process that outlives the wait window or produces more output than fits in one page falls back to split calls automatically. The result holds the output available when the call returns: its per-process log is bounded, so very large output loses its oldest frames, and a result that timed out collects only the first few log pages. **Shell selection.** A string `command` runs through the sandbox shell (`bash`, else `sh`; pin another with `shell=`). Quote globs and brackets (`pip install -e '.[test]'`) so the command means the same under any shell. Use `argv=` to bypass the shell entirely, which is the safe form for untrusted arguments. For persistent shell state, use `create_session`. **Background processes.** The call returns when the shell exits. If the command forks a background child that holds its output descriptors open (e.g. `python3 -m http.server 8000 &`), the call waits at most ~2 seconds for output to drain and then returns; output the child writes later is not part of the result. For a long-running server prefer `start`, which returns a `ProcessHandle` immediately, or redirect: `nohup cmd > server.log 2>&1 &`. :param command: Shell command string; mutually exclusive with `argv`. :param argv: Argument vector for shell-free execution. :param cwd: Working directory inside the sandbox. :param env: Extra environment variables merged into the process environment. :param shell: Shell binary to use (e.g. `"bash"`); overrides auto-detection. :param timeout: Caller wait budget in seconds. Omit to wait until the process ends. Does not kill the process on expiry. :param execution_timeout: Server-side deadline in seconds. The sandbox kills the process tree when this expires. :returns: `daytona.v2.types.ProcessResult` with `stdout`, `stderr`, `output`, `exit_code`, and `reason`. Example:: result = await sandbox.process.run("pip install httpx") if result.exit_code != 0: raise RuntimeError(result.stderr) #### AsyncProcessService.connect [#asyncprocessserviceconnect] ```python def connect(process_id: Union[str, Mapping[str, str]]) -> AsyncProcessHandle ``` Create a bound process handle without fetching metadata. #### AsyncProcessService.get [#asyncprocessserviceget] ```python async def get(process_id: str) -> ProcessInfo ``` Fetch current process metadata by id or live name alias. #### AsyncProcessService.list [#asyncprocessservicelist] ```python async def list(*, state: Optional[ProcessStateFilter] = None, kind: Optional[ProcessKind] = None, session_id: Optional[str] = None, name: Optional[str] = None, pid: Optional[int] = None) -> ListResult[ProcessInfo] ``` ## PtyService [#ptyservice] ```python class PtyService() ``` PTY convenience namespace. #### PtyService.\_\_init\_\_ [#ptyservice__init__] ```python def __init__(impl: AsyncPtyService, bridge: SyncBridge) -> None ``` #### PtyService.connect [#ptyserviceconnect] ```python def connect(process_id: str) -> ProcessHandle ``` Create a bound PTY handle. #### PtyService.delete [#ptyservicedelete] ```python def delete(process_id: str) -> None ``` #### PtyService.list [#ptyservicelist] ```python def list() -> ListResult[ProcessInfo] ``` #### PtyService.start [#ptyservicestart] ```python def start(command: Optional[str] = None, *, cols: int = 80, rows: int = 24, cwd: Optional[str] = None, env: Optional[Mapping[str, str]] = None, name: Optional[str] = None) -> ProcessHandle ``` Start a detached PTY process. ## AsyncPtyService [#asyncptyservice] ```python class AsyncPtyService() ``` PTY convenience namespace. #### AsyncPtyService.\_\_init\_\_ [#asyncptyservice__init__] ```python def __init__(process: AsyncProcessService) -> None ``` #### AsyncPtyService.start [#asyncptyservicestart] ```python async def start(command: Optional[str] = None, *, cols: int = 80, rows: int = 24, cwd: Optional[str] = None, env: Optional[Mapping[str, str]] = None, name: Optional[str] = None) -> AsyncProcessHandle ``` Start a detached PTY process. #### AsyncPtyService.connect [#asyncptyserviceconnect] ```python def connect(process_id: str) -> AsyncProcessHandle ``` Create a bound PTY handle. #### AsyncPtyService.list [#asyncptyservicelist] ```python async def list() -> ListResult[ProcessInfo] ``` #### AsyncPtyService.delete [#asyncptyservicedelete] ```python async def delete(process_id: str) -> None ``` ## Session [#session] ```python class Session() ``` One persistent shell whose commands run one at a time, in order. #### Session.\_\_init\_\_ [#session__init__] ```python def __init__(impl: AsyncSession, bridge: SyncBridge) -> None ``` #### Session.sandbox\_id [#sessionsandbox_id] ```python @property def sandbox_id() -> str ``` #### Session.id [#sessionid] ```python @property def id() -> str ``` #### Session.delete [#sessiondelete] ```python def delete() -> None ``` End this shell and remove it and all its commands. #### Session.from\_json [#sessionfrom_json] ```python @classmethod def from_json(value: Mapping[str, object]) -> Session ``` Rehydrate an unbound identity without making a request. #### Session.get [#sessionget] ```python def get() -> ProcessInfo ``` Fetch session metadata, including the shell's live cwd. #### Session.run [#sessionrun] ```python def run(command: str, *, stdin: StdinMode = 'closed', timeout: Optional[float] = None, execution_timeout: Optional[float] = None, name: Optional[str] = None, keep_logs: Optional[KeepLogs] = None) -> ProcessResult ``` Run a command in this shell and collect output; timeouts are seconds. #### Session.start [#sessionstart] ```python def start(command: str, *, stdin: StdinMode = 'closed', execution_timeout: Optional[float] = None, name: Optional[str] = None, keep_logs: Optional[KeepLogs] = None) -> ProcessHandle ``` Queue a command and return its handle without waiting for exit. #### Session.to\_json [#sessionto_json] ```python def to_json() -> _SessionIdentity ``` Return a JSON-safe identity for `process.connect_session()`. ## AsyncSession [#asyncsession] ```python class AsyncSession() ``` One persistent shell whose commands run one at a time, in order. Directory changes, exports and functions carry over between commands. Set cwd and env when calling `process.create_session()`. Interrupt a running command with `handle.kill(signal="INT")`; the session survives. Sessions do not survive a sandbox stop/start. After `set -x` or `set -v`, later commands' stderr also includes the session's command execution traces. #### AsyncSession.\_\_init\_\_ [#asyncsession__init__] ```python def __init__(sandbox_id: str, session_id: str, transport: Optional[AsyncTransport] = None) -> None ``` #### AsyncSession.to\_json [#asyncsessionto_json] ```python def to_json() -> _SessionIdentity ``` Return a JSON-safe identity for `process.connect_session()`. #### AsyncSession.from\_json [#asyncsessionfrom_json] ```python @classmethod def from_json(value: Mapping[str, object]) -> AsyncSession ``` Rehydrate an unbound identity without making a request. #### AsyncSession.run [#asyncsessionrun] ```python async def run(command: str, *, stdin: StdinMode = 'closed', timeout: Optional[float] = None, execution_timeout: Optional[float] = None, name: Optional[str] = None, keep_logs: Optional[KeepLogs] = None) -> ProcessResult ``` Run a command in this shell and collect output; timeouts are seconds. `timeout` bounds the caller's wait without stopping the command; `execution_timeout` stops the command without ending the session. A command that has not stopped 5 s after its timeout (the shell could not interrupt it and it runs no process to kill) ends the session instead. In dash, BusyBox `sh` and mksh an interrupt leaves only the innermost shell function or sourced file, as it does in bash older than 4.4 (macOS's `/bin/bash`) when a DEBUG trap is set. #### AsyncSession.start [#asyncsessionstart] ```python async def start(command: str, *, stdin: StdinMode = 'closed', execution_timeout: Optional[float] = None, name: Optional[str] = None, keep_logs: Optional[KeepLogs] = None) -> AsyncProcessHandle ``` Queue a command and return its handle without waiting for exit. Interrupt it with `handle.kill(signal="INT")`; the shell survives. `execution_timeout` is a server-side deadline in seconds; the clock starts when the command starts, after any queued commands ahead of it. #### AsyncSession.get [#asyncsessionget] ```python async def get() -> ProcessInfo ``` Fetch session metadata, including the shell's live cwd. #### AsyncSession.delete [#asyncsessiondelete] ```python async def delete() -> None ``` End this shell and remove it and all its commands. ## ProcessInfo [#processinfo] ```python @dataclass(frozen=True) class ProcessInfo() ``` Serializable process information. **Attributes**: - `id` _str_ - `kind` _ProcessInfoKind_ - `state` _ProcessState_ - `name` _Optional\[str\] = None_ - `pid` _Optional\[int\] = None_ - `system` _bool = False_ - `session_id` _Optional\[str\] = None_ - `shell_command` _Optional\[str\] = None_ - `argv` _Optional\[List\[str\]\] = None_ - `code` _Optional\[str\] = None_ - `language` _Optional\[str\] = None_ - `shell` _Optional\[str\] = None_ - `resolved_shell` _Optional\[str\] = None_ - `login` _Optional\[bool\] = None_ - `cwd` _Optional\[str\] = None_ - `user` _Optional\[str\] = None_ - `stdin` _Optional\[ProcessStdinMode\] = None_ - `execution_timeout` _Optional\[float\] = None_ - `terminal` _Optional\[TerminalSize\] = None_ - `keep_logs` _Optional\[ProcessKeepLogs\] = None_ - `exit_code` _Optional\[int\] = None_ - `signal` _Optional\[str\] = None_ - `reason` _Optional\[WaitReason\] = None_ - `created_at` _Optional\[str\] = None_ - `started_at` _Optional\[str\] = None_ - `exited_at` _Optional\[str\] = None_ - `truncated_head` _bool = False_ - `first_available_cursor` _Optional\[str\] = None_ - `last_cursor` _Optional\[str\] = None_ - `raw_kind` _Optional\[str\] = None_ - `raw_state` _Optional\[str\] = None_ - `raw_stdin` _Optional\[str\] = None_ - `raw_keep_logs` _Optional\[str\] = None_ - `raw_reason` _Optional\[str\] = None_ ## ProcessHandleRef [#processhandleref-1] ```python @dataclass(frozen=True) class ProcessHandleRef() ``` JSON-safe process handle identity. **Attributes**: - `sandbox_id` _str_ - `process_id` _str_ - `kind` _Optional\[ProcessKind\] = None_ ## WaitResult [#waitresult] ```python @dataclass(frozen=True) class WaitResult() ``` Result returned by process wait. **Attributes**: - `exit_code` _Optional\[int\] = None_ - `signal` _Optional\[str\] = None_ - `reason` _Optional\[WaitReason\] = None_ - `raw_reason` _Optional\[str\] = None_ ## LogFrame [#logframe] ```python @dataclass(frozen=True) class LogFrame() ``` One replayable process event. **Attributes**: - `cursor` _str_ - `channel` _str_ - `data` _str_ - `timestamp` _Optional\[int\] = None_ ## LogPage [#logpage] ```python @dataclass(frozen=True) class LogPage() ``` A cursor-addressed process log page. **Attributes**: - `items` _List\[LogFrame\]_ - `next_cursor` _Optional\[str\] = None_ - `truncated_head` _bool = False_ - `first_available_cursor` _Optional\[str\] = None_ ## ProcessResult [#processresult] ```python @dataclass(frozen=True) class ProcessResult() ``` Process run result with collected output. **Attributes**: - `process_id` _str_ - `exit_code` _Optional\[int\]_ - `signal` _Optional\[str\]_ - `reason` _Optional\[WaitReason\]_ - `stdout` _str = ''_ - `stderr` _str = ''_ - `output` _str = ''_ - `raw_reason` _Optional\[str\] = None_ ## TerminalSize [#terminalsize] ```python @dataclass(frozen=True) class TerminalSize() ``` PTY terminal dimensions. **Attributes**: - `cols` _int_ - `rows` _int_ ## ProcessKind [#processkind] ```python ProcessKind = Literal['exec', 'pty', 'code', 'session'] ``` ## ProcessInfoKind [#processinfokind] ```python ProcessInfoKind = Literal['exec', 'pty', 'code', 'session', 'unknown'] ``` ## ProcessStateFilter [#processstatefilter] ```python ProcessStateFilter = Literal['running', 'terminal', 'all'] ``` ## ProcessState [#processstate] ```python ProcessState = Literal['starting', 'provisioning', 'running', 'terminal', 'unknown'] ``` ## KeepLogs [#keeplogs] ```python KeepLogs = Literal['until_cleanup', 'on_exit_ttl', 'none'] ``` ## StdinMode [#stdinmode] ```python StdinMode = Literal['closed', 'open'] ``` ## ProcessKeepLogs [#processkeeplogs] ```python ProcessKeepLogs = Literal['until_cleanup', 'on_exit_ttl', 'none', 'unknown'] ``` ## ProcessStdinMode [#processstdinmode] ```python ProcessStdinMode = Literal['closed', 'open', 'unknown'] ``` ## WaitReason [#waitreason] ```python WaitReason = Literal['exited', 'signaled', 'timed_out', 'lost', 'failed', 'unknown'] ``` # Interpreter (/docs/python-sdk/interpreter) ## InterpreterService [#interpreterservice] ```python class InterpreterService() ``` Synchronous InterpreterService. #### InterpreterService.\_\_init\_\_ [#interpreterservice__init__] ```python def __init__(impl: AsyncInterpreterService, bridge: SyncBridge) -> None ``` #### InterpreterService.connect\_context [#interpreterserviceconnect_context] ```python def connect_context(context: str | InterpreterContext | InterpreterContextJSON, *, language: str | None = None) -> InterpreterContext ``` #### InterpreterService.create\_context [#interpreterservicecreate_context] ```python def create_context(*, language: str, context_id: Optional[str] = None, cwd: Optional[str] = None, env: Optional[Mapping[str, str]] = None, request_timeout: Optional[float] = None) -> InterpreterContext ``` #### InterpreterService.delete\_context [#interpreterservicedelete_context] ```python def delete_context(context: InterpreterContext | InterpreterContextJSON | str) -> None ``` #### InterpreterService.get\_context [#interpreterserviceget_context] ```python def get_context(context: str | InterpreterContext | InterpreterContextJSON, *, language: str | None = None) -> InterpreterContext ``` #### InterpreterService.list\_contexts [#interpreterservicelist_contexts] ```python def list_contexts() -> list[InterpreterContext] ``` #### InterpreterService.run [#interpreterservicerun] ```python def run(code: str, *, language: str = 'python', context: Optional[InterpreterContext] = None, isolated: bool = False, timeout: Optional[float] = None, cwd: Optional[str] = None, env: Optional[Mapping[str, str]] = None) -> InterpreterResult ``` Execute code and return the parsed interpreter result. ## AsyncInterpreterService [#asyncinterpreterservice] ```python class AsyncInterpreterService() ``` #### AsyncInterpreterService.\_\_init\_\_ [#asyncinterpreterservice__init__] ```python def __init__(sandbox_id: str, transport: AsyncTransport, process: AsyncProcessService) -> None ``` #### AsyncInterpreterService.create\_context [#asyncinterpreterservicecreate_context] ```python async def create_context(*, language: str, context_id: Optional[str] = None, cwd: Optional[str] = None, env: Optional[Mapping[str, str]] = None, request_timeout: Optional[float] = None) -> AsyncInterpreterContext ``` #### AsyncInterpreterService.connect\_context [#asyncinterpreterserviceconnect_context] ```python def connect_context(context: str | AsyncInterpreterContext | InterpreterContextJSON, *, language: str | None = None) -> AsyncInterpreterContext ``` #### AsyncInterpreterService.get\_context [#asyncinterpreterserviceget_context] ```python def get_context(context: str | AsyncInterpreterContext | InterpreterContextJSON, *, language: str | None = None) -> AsyncInterpreterContext ``` #### AsyncInterpreterService.list\_contexts [#asyncinterpreterservicelist_contexts] ```python async def list_contexts() -> list[AsyncInterpreterContext] ``` #### AsyncInterpreterService.delete\_context [#asyncinterpreterservicedelete_context] ```python async def delete_context(context: AsyncInterpreterContext | InterpreterContextJSON | str) -> None ``` #### AsyncInterpreterService.run [#asyncinterpreterservicerun] ```python async def run(code: str, *, language: str = 'python', context: Optional[AsyncInterpreterContext] = None, isolated: bool = False, timeout: Optional[float] = None, cwd: Optional[str] = None, env: Optional[Mapping[str, str]] = None) -> InterpreterResult ``` Execute code and return the parsed interpreter result. A rehydrated `kind='code'` process handle can still replay logs and wait/kill, but it does not reconstruct this decomposed result on another worker. A vanished explicit context surfaces the API's typed `SESSION_NOT_FOUND` error; callers decide whether to recreate the context and what to rerun. `timeout` is the caller wait budget in seconds; `0` waits unbounded. ## InterpreterContext [#interpretercontext] ```python class InterpreterContext() ``` Serializable interpreter context handle. #### InterpreterContext.\_\_init\_\_ [#interpretercontext__init__] ```python def __init__(impl: AsyncInterpreterContext, bridge: SyncBridge) -> None ``` #### InterpreterContext.sandbox\_id [#interpretercontextsandbox_id] ```python @property def sandbox_id() -> str ``` #### InterpreterContext.context\_id [#interpretercontextcontext_id] ```python @property def context_id() -> str ``` #### InterpreterContext.language [#interpretercontextlanguage] ```python @property def language() -> str ``` #### InterpreterContext.close [#interpretercontextclose] ```python def close() -> None ``` #### InterpreterContext.run [#interpretercontextrun] ```python def run(code: str, *, cwd: Optional[str] = None, env: Optional[Mapping[str, str]] = None, timeout: Optional[float] = None) -> InterpreterResult ``` Execute code inside this explicit interpreter context. ## AsyncInterpreterContext [#asyncinterpretercontext] ```python @dataclass(frozen=True) class AsyncInterpreterContext() ``` Serializable interpreter context handle. **Attributes**: - `sandbox_id` _str_ - `context_id` _str_ - `language` _str_ #### AsyncInterpreterContext.bind [#asyncinterpretercontextbind] ```python def bind(runner: Callable[[str, Optional[str], Optional[Mapping[str, str]], Optional[float]], Awaitable[InterpreterResult]], closer: Callable[[], Awaitable[None]]) -> Self ``` #### AsyncInterpreterContext.run [#asyncinterpretercontextrun] ```python async def run(code: str, *, cwd: Optional[str] = None, env: Optional[Mapping[str, str]] = None, timeout: Optional[float] = None) -> InterpreterResult ``` Execute code inside this explicit interpreter context. If the named context vanished, the API's typed `SESSION_NOT_FOUND` error surfaces unchanged so the caller can recreate the context and decide what code, if any, is safe to rerun. `timeout` is the caller wait budget in seconds; `0` waits unbounded. #### AsyncInterpreterContext.close [#asyncinterpretercontextclose] ```python async def close() -> None ``` ## InterpreterContextJSON [#interpretercontextjson] ```python class InterpreterContextJSON(TypedDict) ``` **Attributes**: - `sandbox_id` _str_ - `context_id` _str_ - `language` _str_ ## InterpreterDisplay [#interpreterdisplay] ```python @dataclass(frozen=True) class InterpreterDisplay() ``` One rich interpreter output bundle. **Attributes**: - `mime` _str_ - `data` _str_ ## InterpreterProcess [#interpreterprocess] ```python @dataclass(frozen=True) class InterpreterProcess() ``` **Attributes**: - `process_id` _str_ - `exit_code` _Optional\[int\]_ - `signal` _Optional\[str\]_ - `reason` _Optional\[WaitReason\]_ - `raw_reason` _Optional\[str\] = None_ ## InterpreterLogs [#interpreterlogs] ```python @dataclass(frozen=True) class InterpreterLogs() ``` **Attributes**: - `stdout` _str = ''_ - `stderr` _str = ''_ ## InterpreterError [#interpretererror] ```python @dataclass(frozen=True) class InterpreterError() ``` **Attributes**: - `name` _str_ - `value` _str_ - `traceback` _List\[str\] = field(default_factory=list)_ ## InterpreterOutput [#interpreteroutput] ```python @dataclass(frozen=True) class InterpreterOutput() ``` **Attributes**: - `data` _JsonObject_ - `is_main_result` _bool_ - `text` _Optional\[str\] = None_ - `html` _Optional\[str\] = None_ - `png` _Optional\[str\] = None_ - `svg` _Optional\[str\] = None_ - `json` _Optional\[JsonValue\] = None_ ## InterpreterResult [#interpreterresult] ```python @dataclass(frozen=True) class InterpreterResult() ``` Interpreter run result. **Attributes**: - `process` _InterpreterProcess_ - `results` _List\[InterpreterOutput\] = field(default_factory=list)_ - `logs` _InterpreterLogs = field(default_factory=InterpreterLogs)_ - `error` _Optional\[InterpreterError\] = None_ # ComputerUse (/docs/python-sdk/computer-use) ## ComputerUseService [#computeruseservice] ```python class ComputerUseService() ``` Synchronous ComputerUseService. #### ComputerUseService.\_\_init\_\_ [#computeruseservice__init__] ```python def __init__(impl: AsyncComputerUseService, bridge: SyncBridge) -> None ``` #### ComputerUseService.service [#computeruseserviceservice] ```python @property def service() -> AddonProcessesService ``` #### ComputerUseService.mouse [#computeruseservicemouse] ```python @property def mouse() -> MouseService ``` #### ComputerUseService.keyboard [#computeruseservicekeyboard] ```python @property def keyboard() -> KeyboardService ``` #### ComputerUseService.screen [#computeruseservicescreen] ```python @property def screen() -> ScreenService ``` #### ComputerUseService.display [#computeruseservicedisplay] ```python @property def display() -> DisplayService ``` #### ComputerUseService.a11y [#computeruseservicea11y] ```python @property def a11y() -> A11yService ``` #### ComputerUseService.recording [#computeruseservicerecording] ```python @property def recording() -> RecordingService ``` #### ComputerUseService.restart [#computeruseservicerestart] ```python def restart() -> ComputerUseRestartResponse ``` #### ComputerUseService.start [#computeruseservicestart] ```python def start() -> ComputerUseLifecycleResult ``` #### ComputerUseService.status [#computeruseservicestatus] ```python def status() -> ComputerUseStatusResponse ``` #### ComputerUseService.stop [#computeruseservicestop] ```python def stop() -> ComputerUseLifecycleResult ``` ## AsyncComputerUseService [#asynccomputeruseservice] ```python class AsyncComputerUseService() ``` #### AsyncComputerUseService.\_\_init\_\_ [#asynccomputeruseservice__init__] ```python def __init__(transport: AsyncTransport) -> None ``` #### AsyncComputerUseService.status [#asynccomputeruseservicestatus] ```python async def status() -> ComputerUseStatusResponse ``` #### AsyncComputerUseService.start [#asynccomputeruseservicestart] ```python async def start() -> ComputerUseLifecycleResult ``` #### AsyncComputerUseService.stop [#asynccomputeruseservicestop] ```python async def stop() -> ComputerUseLifecycleResult ``` #### AsyncComputerUseService.restart [#asynccomputeruseservicerestart] ```python async def restart() -> ComputerUseRestartResponse ``` ## A11yService [#a11yservice] ```python class A11yService() ``` Synchronous A11yService. #### A11yService.\_\_init\_\_ [#a11yservice__init__] ```python def __init__(impl: AsyncA11yService, bridge: SyncBridge) -> None ``` #### A11yService.find [#a11yservicefind] ```python def find(*, scope: ComputerUseA11yScope, pid: int | None = None, role: str | None = None, name: str | None = None, name_match: ComputerUseA11yNameMatch | None = None, states: Sequence[str] | None = None, limit: int | None = None) -> ComputerUseA11yFindResult ``` #### A11yService.focus [#a11yservicefocus] ```python def focus(*, id: str) -> None ``` #### A11yService.invoke [#a11yserviceinvoke] ```python def invoke(*, id: str, action: str | None = None) -> None ``` #### A11yService.set\_value [#a11yserviceset_value] ```python def set_value(*, id: str, value: str) -> None ``` #### A11yService.tree [#a11yservicetree] ```python def tree(*, scope: ComputerUseA11yScope, pid: int | None = None, max_depth: int | None = None) -> ComputerUseA11yTree ``` ## AsyncA11yService [#asynca11yservice] ```python class AsyncA11yService() ``` #### AsyncA11yService.\_\_init\_\_ [#asynca11yservice__init__] ```python def __init__(transport: AsyncTransport) -> None ``` #### AsyncA11yService.tree [#asynca11yservicetree] ```python async def tree(*, scope: ComputerUseA11yScope, pid: int | None = None, max_depth: int | None = None) -> ComputerUseA11yTree ``` #### AsyncA11yService.find [#asynca11yservicefind] ```python async def find(*, scope: ComputerUseA11yScope, pid: int | None = None, role: str | None = None, name: str | None = None, name_match: ComputerUseA11yNameMatch | None = None, states: Sequence[str] | None = None, limit: int | None = None) -> ComputerUseA11yFindResult ``` #### AsyncA11yService.focus [#asynca11yservicefocus] ```python async def focus(*, id: str) -> None ``` #### AsyncA11yService.invoke [#asynca11yserviceinvoke] ```python async def invoke(*, id: str, action: str | None = None) -> None ``` #### AsyncA11yService.set\_value [#asynca11yserviceset_value] ```python async def set_value(*, id: str, value: str) -> None ``` ## AddonProcessesService [#addonprocessesservice] ```python class AddonProcessesService() ``` Synchronous AddonProcessesService. #### AddonProcessesService.\_\_init\_\_ [#addonprocessesservice__init__] ```python def __init__(impl: AsyncAddonProcessesService, bridge: SyncBridge) -> None ``` #### AddonProcessesService.errors [#addonprocessesserviceerrors] ```python def errors(name: str) -> ComputerUseProcessErrors ``` #### AddonProcessesService.logs [#addonprocessesservicelogs] ```python def logs(name: str) -> ComputerUseProcessLogs ``` #### AddonProcessesService.restart [#addonprocessesservicerestart] ```python def restart(name: str) -> ComputerUseProcessRestartResult ``` #### AddonProcessesService.status [#addonprocessesservicestatus] ```python @overload def status() -> dict[str, ComputerUseProcessStatus] ``` #### AddonProcessesService.status [#addonprocessesservicestatus-1] ```python @overload def status(name: str) -> ComputerUseProcessRunningStatus ``` ## AsyncAddonProcessesService [#asyncaddonprocessesservice] ```python class AsyncAddonProcessesService() ``` #### AsyncAddonProcessesService.\_\_init\_\_ [#asyncaddonprocessesservice__init__] ```python def __init__(transport: AsyncTransport) -> None ``` #### AsyncAddonProcessesService.status [#asyncaddonprocessesservicestatus] ```python @overload async def status() -> dict[str, ComputerUseProcessStatus] ``` #### AsyncAddonProcessesService.status [#asyncaddonprocessesservicestatus-1] ```python @overload async def status(name: str) -> ComputerUseProcessRunningStatus ``` #### AsyncAddonProcessesService.restart [#asyncaddonprocessesservicerestart] ```python async def restart(name: str) -> ComputerUseProcessRestartResult ``` #### AsyncAddonProcessesService.logs [#asyncaddonprocessesservicelogs] ```python async def logs(name: str) -> ComputerUseProcessLogs ``` #### AsyncAddonProcessesService.errors [#asyncaddonprocessesserviceerrors] ```python async def errors(name: str) -> ComputerUseProcessErrors ``` ## DisplayService [#displayservice] ```python class DisplayService() ``` Synchronous DisplayService. #### DisplayService.\_\_init\_\_ [#displayservice__init__] ```python def __init__(impl: AsyncDisplayService, bridge: SyncBridge) -> None ``` #### DisplayService.info [#displayserviceinfo] ```python def info() -> ComputerUseDisplayInfo ``` #### DisplayService.windows [#displayservicewindows] ```python def windows() -> ComputerUseDisplayWindows ``` ## AsyncDisplayService [#asyncdisplayservice] ```python class AsyncDisplayService() ``` #### AsyncDisplayService.\_\_init\_\_ [#asyncdisplayservice__init__] ```python def __init__(transport: AsyncTransport) -> None ``` #### AsyncDisplayService.info [#asyncdisplayserviceinfo] ```python async def info() -> ComputerUseDisplayInfo ``` #### AsyncDisplayService.windows [#asyncdisplayservicewindows] ```python async def windows() -> ComputerUseDisplayWindows ``` ## KeyboardService [#keyboardservice] ```python class KeyboardService() ``` Synchronous KeyboardService. #### KeyboardService.\_\_init\_\_ [#keyboardservice__init__] ```python def __init__(impl: AsyncKeyboardService, bridge: SyncBridge) -> None ``` #### KeyboardService.hotkey [#keyboardservicehotkey] ```python def hotkey(*, keys: str) -> None ``` #### KeyboardService.key [#keyboardservicekey] ```python def key(*, key: str, modifiers: Sequence[ComputerUseKeyboardModifier] | None = None) -> None ``` #### KeyboardService.type [#keyboardservicetype] ```python def type(*, text: str, delay: int | None = None) -> None ``` ## AsyncKeyboardService [#asynckeyboardservice] ```python class AsyncKeyboardService() ``` #### AsyncKeyboardService.\_\_init\_\_ [#asynckeyboardservice__init__] ```python def __init__(transport: AsyncTransport) -> None ``` #### AsyncKeyboardService.type [#asynckeyboardservicetype] ```python async def type(*, text: str, delay: int | None = None) -> None ``` #### AsyncKeyboardService.key [#asynckeyboardservicekey] ```python async def key(*, key: str, modifiers: Sequence[ComputerUseKeyboardModifier] | None = None) -> None ``` #### AsyncKeyboardService.hotkey [#asynckeyboardservicehotkey] ```python async def hotkey(*, keys: str) -> None ``` ## MouseService [#mouseservice] ```python class MouseService() ``` Synchronous MouseService. #### MouseService.\_\_init\_\_ [#mouseservice__init__] ```python def __init__(impl: AsyncMouseService, bridge: SyncBridge) -> None ``` #### MouseService.click [#mouseserviceclick] ```python def click(*, x: int, y: int, button: ComputerUseMouseButton | None = None, double: bool | None = None) -> ComputerUsePoint ``` #### MouseService.drag [#mouseservicedrag] ```python def drag(*, start_x: int, start_y: int, end_x: int, end_y: int, button: ComputerUseMouseButton | None = None) -> ComputerUsePoint ``` #### MouseService.move [#mouseservicemove] ```python def move(*, x: int, y: int) -> ComputerUsePoint ``` #### MouseService.position [#mouseserviceposition] ```python def position() -> ComputerUsePoint ``` #### MouseService.scroll [#mouseservicescroll] ```python def scroll(*, x: int, y: int, direction: ComputerUseScrollDirection, amount: int | None = None) -> ComputerUseScrollResult ``` ## AsyncMouseService [#asyncmouseservice] ```python class AsyncMouseService() ``` #### AsyncMouseService.\_\_init\_\_ [#asyncmouseservice__init__] ```python def __init__(transport: AsyncTransport) -> None ``` #### AsyncMouseService.position [#asyncmouseserviceposition] ```python async def position() -> ComputerUsePoint ``` #### AsyncMouseService.move [#asyncmouseservicemove] ```python async def move(*, x: int, y: int) -> ComputerUsePoint ``` #### AsyncMouseService.click [#asyncmouseserviceclick] ```python async def click(*, x: int, y: int, button: ComputerUseMouseButton | None = None, double: bool | None = None) -> ComputerUsePoint ``` #### AsyncMouseService.drag [#asyncmouseservicedrag] ```python async def drag(*, start_x: int, start_y: int, end_x: int, end_y: int, button: ComputerUseMouseButton | None = None) -> ComputerUsePoint ``` #### AsyncMouseService.scroll [#asyncmouseservicescroll] ```python async def scroll(*, x: int, y: int, direction: ComputerUseScrollDirection, amount: int | None = None) -> ComputerUseScrollResult ``` ## RecordingService [#recordingservice] ```python class RecordingService() ``` Synchronous RecordingService. #### RecordingService.\_\_init\_\_ [#recordingservice__init__] ```python def __init__(impl: AsyncRecordingService, bridge: SyncBridge) -> None ``` #### RecordingService.delete [#recordingservicedelete] ```python def delete(id: str) -> None ``` #### RecordingService.download [#recordingservicedownload] ```python def download(id: str) -> bytes ``` #### RecordingService.get [#recordingserviceget] ```python def get(id: str) -> ComputerUseRecording ``` #### RecordingService.list [#recordingservicelist] ```python def list() -> ComputerUseRecordingList ``` #### RecordingService.start [#recordingservicestart] ```python def start(*, label: str | None = None) -> ComputerUseRecording ``` #### RecordingService.stop [#recordingservicestop] ```python def stop(*, id: str) -> ComputerUseRecording ``` ## AsyncRecordingService [#asyncrecordingservice] ```python class AsyncRecordingService() ``` #### AsyncRecordingService.\_\_init\_\_ [#asyncrecordingservice__init__] ```python def __init__(transport: AsyncTransport) -> None ``` #### AsyncRecordingService.start [#asyncrecordingservicestart] ```python async def start(*, label: str | None = None) -> ComputerUseRecording ``` #### AsyncRecordingService.stop [#asyncrecordingservicestop] ```python async def stop(*, id: str) -> ComputerUseRecording ``` #### AsyncRecordingService.list [#asyncrecordingservicelist] ```python async def list() -> ComputerUseRecordingList ``` #### AsyncRecordingService.get [#asyncrecordingserviceget] ```python async def get(id: str) -> ComputerUseRecording ``` #### AsyncRecordingService.download [#asyncrecordingservicedownload] ```python async def download(id: str) -> bytes ``` #### AsyncRecordingService.delete [#asyncrecordingservicedelete] ```python async def delete(id: str) -> None ``` ## ScreenService [#screenservice] ```python class ScreenService() ``` Synchronous ScreenService. #### ScreenService.\_\_init\_\_ [#screenservice__init__] ```python def __init__(impl: AsyncScreenService, bridge: SyncBridge) -> None ``` #### ScreenService.screenshot [#screenservicescreenshot] ```python def screenshot(*, region: ComputerUseRegion | None = None, format: ComputerUseScreenshotFormat | None = None, quality: int | None = None, scale: float | None = None, show_cursor: bool | None = None) -> ComputerUseScreenshot ``` Capture the screen, or `region` of it. ## AsyncScreenService [#asyncscreenservice] ```python class AsyncScreenService() ``` #### AsyncScreenService.\_\_init\_\_ [#asyncscreenservice__init__] ```python def __init__(transport: AsyncTransport) -> None ``` #### AsyncScreenService.screenshot [#asyncscreenservicescreenshot] ```python async def screenshot(*, region: ComputerUseRegion | None = None, format: ComputerUseScreenshotFormat | None = None, quality: int | None = None, scale: float | None = None, show_cursor: bool | None = None) -> ComputerUseScreenshot ``` Capture the screen, or `region` of it. Setting any of `format`, `quality` or `scale` returns a compressed image. ## ComputerUseDesktopFailure [#computerusedesktopfailure] ```python @dataclass(frozen=True, slots=True) class ComputerUseDesktopFailure() ``` **Attributes**: - `code` _ComputerUseDesktopFailureCode_ - `message` _str_ - `extra_fields` _Optional\[Dict\[str, JsonValue\]\] = None_ - `raw_code` _Optional\[str\] = None_ ## ComputerUseNotStartedStatus [#computerusenotstartedstatus] ```python @dataclass(frozen=True, slots=True) class ComputerUseNotStartedStatus() ``` **Attributes**: - `status` _Literal\['inactive'\] = 'inactive'_ - `desktop` _Literal\['not_started'\] = 'not_started'_ - `cause` _None = None_ - `extra_fields` _Optional\[Dict\[str, JsonValue\]\] = None_ ## ComputerUseStartingStatus [#computerusestartingstatus] ```python @dataclass(frozen=True, slots=True) class ComputerUseStartingStatus() ``` **Attributes**: - `status` _Literal\['inactive'\] = 'inactive'_ - `desktop` _Literal\['starting'\] = 'starting'_ - `cause` _None = None_ - `extra_fields` _Optional\[Dict\[str, JsonValue\]\] = None_ ## ComputerUseReadyStatus [#computerusereadystatus] ```python @dataclass(frozen=True, slots=True) class ComputerUseReadyStatus() ``` **Attributes**: - `status` _Literal\['active'\] = 'active'_ - `desktop` _Literal\['ready'\] = 'ready'_ - `cause` _None = None_ - `extra_fields` _Optional\[Dict\[str, JsonValue\]\] = None_ ## ComputerUseFailedStatus [#computerusefailedstatus] ```python @dataclass(frozen=True, slots=True) class ComputerUseFailedStatus() ``` **Attributes**: - `cause` _ComputerUseDesktopFailure_ - `status` _Literal\['inactive'\] = 'inactive'_ - `desktop` _Literal\['failed'\] = 'failed'_ - `extra_fields` _Optional\[Dict\[str, JsonValue\]\] = None_ ## ComputerUseUnknownStatus [#computeruseunknownstatus] ```python @dataclass(frozen=True, slots=True) class ComputerUseUnknownStatus() ``` A (status, desktop) pair this SDK release does not recognize. raw_status / raw_desktop carry the API values or combination; the recognized variants need no raw sibling, since their typed values are the wire values. cause is the failure the API attached to the unrecognized state, when it sent one. **Attributes**: - `raw_status` _str_ - `raw_desktop` _str_ - `status` _Literal\['unknown'\] = 'unknown'_ - `desktop` _Literal\['unknown'\] = 'unknown'_ - `cause` _Optional\[ComputerUseDesktopFailure\] = None_ - `extra_fields` _Optional\[Dict\[str, JsonValue\]\] = None_ ## ComputerUseRestartResponse [#computeruserestartresponse] ```python @dataclass(frozen=True, slots=True) class ComputerUseRestartResponse() ``` **Attributes**: - `message` _str_ - `status` _Literal\['active'\] = 'active'_ - `desktop` _Literal\['ready'\] = 'ready'_ - `extra_fields` _Optional\[Dict\[str, JsonValue\]\] = None_ ## ComputerUseProcessStatus [#computeruseprocessstatus] ```python @dataclass(frozen=True, slots=True) class ComputerUseProcessStatus() ``` **Attributes**: - `running` _Optional\[bool\] = None_ - `priority` _Optional\[int\] = None_ - `auto_restart` _Optional\[bool\] = None_ - `pid` _Optional\[int\] = None_ - `failed` _Optional\[bool\] = None_ - `restart_attempts` _Optional\[int\] = None_ - `restart_backoff_ms` _Optional\[int\] = None_ - `status` _Optional\[str\] = None_ - `extra_fields` _Optional\[Dict\[str, JsonValue\]\] = None_ ## ComputerUseProcessRunningStatus [#computeruseprocessrunningstatus] ```python @dataclass(frozen=True, slots=True) class ComputerUseProcessRunningStatus() ``` **Attributes**: - `process_name` _str_ - `running` _bool_ ## ComputerUsePoint [#computerusepoint] ```python @dataclass(frozen=True, slots=True) class ComputerUsePoint() ``` **Attributes**: - `x` _int_ - `y` _int_ ## ComputerUseRegion [#computeruseregion] ```python @dataclass(frozen=True, slots=True) class ComputerUseRegion() ``` A screen rectangle for `screen.screenshot(region=...)`. **Attributes**: - `x` _int_ - `y` _int_ - `width` _int_ - `height` _int_ ## ComputerUseDisplay [#computerusedisplay] ```python @dataclass(frozen=True, slots=True) class ComputerUseDisplay() ``` **Attributes**: - `id` _int_ - `x` _int_ - `y` _int_ - `width` _int_ - `height` _int_ - `is_active` _bool_ ## ComputerUseWindow [#computerusewindow] ```python @dataclass(frozen=True, slots=True) class ComputerUseWindow() ``` **Attributes**: - `id` _int_ - `title` _str_ - `x` _int_ - `y` _int_ - `width` _int_ - `height` _int_ - `is_active` _bool_ ## ComputerUseAccessibilityBounds [#computeruseaccessibilitybounds] ```python @dataclass(frozen=True, slots=True) class ComputerUseAccessibilityBounds() ``` **Attributes**: - `x` _int_ - `y` _int_ - `width` _int_ - `height` _int_ ## ComputerUseAccessibilityNode [#computeruseaccessibilitynode] ```python @dataclass(frozen=True, slots=True) class ComputerUseAccessibilityNode() ``` **Attributes**: - `id` _str_ - `role` _str_ - `name` _str_ - `bounds` _ComputerUseAccessibilityBounds_ - `states` _List\[str\]_ - `description` _Optional\[str\] = None_ - `actions` _Optional\[List\[str\]\] = None_ - `children` _Optional\[List\[ComputerUseAccessibilityNode\]\] = None_ - `value` _Optional\[str\] = None_ - `value_truncated` _bool = False_ ## ComputerUseRecording [#computeruserecording] ```python @dataclass(frozen=True, slots=True) class ComputerUseRecording() ``` **Attributes**: - `id` _str_ - `file_name` _str_ - `file_path` _str_ - `start_time` _str_ - `status` _str_ - `end_time` _Optional\[str\] = None_ - `duration_seconds` _Optional\[float\] = None_ - `size_bytes` _Optional\[int\] = None_ ## ComputerUseMouseButton [#computerusemousebutton] ```python ComputerUseMouseButton = Literal['left', 'right', 'middle'] ``` ## ComputerUseScrollDirection [#computerusescrolldirection] ```python ComputerUseScrollDirection = Literal['up', 'down'] ``` ## ComputerUseScreenshotFormat [#computerusescreenshotformat] ```python ComputerUseScreenshotFormat = Literal['png', 'jpeg'] ``` ## ComputerUseKeyboardModifier [#computerusekeyboardmodifier] ```python ComputerUseKeyboardModifier = Literal['ctrl', 'alt', 'shift', 'cmd'] ``` ## ComputerUseA11yScope [#computerusea11yscope] ```python ComputerUseA11yScope = Literal['focused', 'pid', 'all'] ``` ## ComputerUseA11yNameMatch [#computerusea11ynamematch] ```python ComputerUseA11yNameMatch = Literal['exact', 'substring', 'regex'] ``` ## ComputerUseActivityStatus [#computeruseactivitystatus] ```python ComputerUseActivityStatus = Literal['active', 'inactive', 'unknown'] ``` ## ComputerUseDesktopState [#computerusedesktopstate] ```python ComputerUseDesktopState = Literal['not_started', 'starting', 'ready', 'failed', 'unknown'] ``` ## ComputerUseDesktopFailureCode [#computerusedesktopfailurecode] ```python ComputerUseDesktopFailureCode = Literal['desktop_exited', 'addon_crashed', 'start_failed', 'start_interrupted', 'session_ended', 'session_replaced', 'state_corrupt', 'state_persistence_failed', 'unknown'] ``` ## ComputerUseStatusResponse [#computerusestatusresponse] ```python ComputerUseStatusResponse = Union[ComputerUseNotStartedStatus, ComputerUseStartingStatus, ComputerUseReadyStatus, ComputerUseFailedStatus, ComputerUseUnknownStatus] ``` ## ComputerUseLifecycleResponse [#computeruselifecycleresponse] ```python ComputerUseLifecycleResponse = ComputerUseLifecycleResult ``` ## ComputerUseProcessRestartResponse [#computeruseprocessrestartresponse] ```python ComputerUseProcessRestartResponse = ComputerUseProcessRestartResult ``` ## ComputerUseProcessLogsResponse [#computeruseprocesslogsresponse] ```python ComputerUseProcessLogsResponse = ComputerUseProcessLogs ``` ## ComputerUseProcessErrorsResponse [#computeruseprocesserrorsresponse] ```python ComputerUseProcessErrorsResponse = ComputerUseProcessErrors ``` ## ComputerUseScreenshotResponse [#computerusescreenshotresponse] ```python ComputerUseScreenshotResponse = ComputerUseScreenshot ``` ## ComputerUseScrollResponse [#computerusescrollresponse] ```python ComputerUseScrollResponse = ComputerUseScrollResult ``` ## ComputerUseDisplayInfoResponse [#computerusedisplayinforesponse] ```python ComputerUseDisplayInfoResponse = ComputerUseDisplayInfo ``` ## ComputerUseDisplayWindowsResponse [#computerusedisplaywindowsresponse] ```python ComputerUseDisplayWindowsResponse = ComputerUseDisplayWindows ``` ## ComputerUseA11yTreeResponse [#computerusea11ytreeresponse] ```python ComputerUseA11yTreeResponse = ComputerUseA11yTree ``` ## ComputerUseA11yFindResponse [#computerusea11yfindresponse] ```python ComputerUseA11yFindResponse = ComputerUseA11yFindResult ``` ## ComputerUseRecordingsResponse [#computeruserecordingsresponse] ```python ComputerUseRecordingsResponse = ComputerUseRecordingList ``` # Lsp (/docs/python-sdk/lsp) ## LspServer [#lspserver] ```python class LspServer() ``` Synchronous LspServer. #### LspServer.\_\_init\_\_ [#lspserver__init__] ```python def __init__(impl: AsyncLspServer, bridge: SyncBridge) -> None ``` #### LspServer.close\_document [#lspserverclose_document] ```python def close_document(uri: str) -> None ``` Notify the server that the document at `uri` was closed. #### LspServer.completions [#lspservercompletions] ```python def completions(uri: str, position: LspPosition | Mapping[str, int], *, context: JsonValue | None = None) -> LspCompletionList ``` #### LspServer.document\_symbols [#lspserverdocument_symbols] ```python def document_symbols(uri: str) -> list[LspSymbol] ``` #### LspServer.open\_document [#lspserveropen_document] ```python def open_document(uri: str) -> None ``` Notify the server that the document at `uri` was opened. #### LspServer.stop [#lspserverstop] ```python def stop() -> None ``` #### LspServer.workspace\_symbols [#lspserverworkspace_symbols] ```python def workspace_symbols(query: str) -> list[LspSymbol] ``` ## AsyncLspServer [#asynclspserver] ```python class AsyncLspServer() ``` #### AsyncLspServer.\_\_init\_\_ [#asynclspserver__init__] ```python def __init__(transport: AsyncTransport, language_id: str, path_to_project: str) -> None ``` #### AsyncLspServer.open\_document [#asynclspserveropen_document] ```python async def open_document(uri: str) -> None ``` Notify the server that the document at `uri` was opened. #### AsyncLspServer.close\_document [#asynclspserverclose_document] ```python async def close_document(uri: str) -> None ``` Notify the server that the document at `uri` was closed. #### AsyncLspServer.completions [#asynclspservercompletions] ```python async def completions(uri: str, position: LspPosition | Mapping[str, int], *, context: JsonValue | None = None) -> LspCompletionList ``` #### AsyncLspServer.document\_symbols [#asynclspserverdocument_symbols] ```python async def document_symbols(uri: str) -> list[LspSymbol] ``` #### AsyncLspServer.workspace\_symbols [#asynclspserverworkspace_symbols] ```python async def workspace_symbols(query: str) -> list[LspSymbol] ``` #### AsyncLspServer.stop [#asynclspserverstop] ```python async def stop() -> None ``` ## LspService [#lspservice] ```python class LspService() ``` Synchronous LspService. #### LspService.\_\_init\_\_ [#lspservice__init__] ```python def __init__(impl: AsyncLspService, bridge: SyncBridge) -> None ``` #### LspService.start [#lspservicestart] ```python def start(language_id: str, path_to_project: str) -> LspServer ``` ## AsyncLspService [#asynclspservice] ```python class AsyncLspService() ``` #### AsyncLspService.\_\_init\_\_ [#asynclspservice__init__] ```python def __init__(transport: AsyncTransport) -> None ``` #### AsyncLspService.start [#asynclspservicestart] ```python async def start(language_id: str, path_to_project: str) -> AsyncLspServer ``` ## LspPosition: `TypeAlias` [#lspposition-typealias] ```python LspPosition = SymbolPosition ``` ## LspRange: `TypeAlias` [#lsprange-typealias] ```python LspRange = SymbolRange ``` ## LspLocation: `TypeAlias` [#lsplocation-typealias] ```python LspLocation = SymbolLocation ``` ## LspSymbol: `TypeAlias` [#lspsymbol-typealias] ```python LspSymbol = SymbolInfo ``` ## LspCompletionItem: `TypeAlias` [#lspcompletionitem-typealias] ```python LspCompletionItem = CompletionItem ``` ## LspCompletionList: `TypeAlias` [#lspcompletionlist-typealias] ```python LspCompletionList = CompletionList ``` # Ports (/docs/python-sdk/ports) ## PortsService [#portsservice] ```python class PortsService() ``` Synchronous PortsService. #### PortsService.\_\_init\_\_ [#portsservice__init__] ```python def __init__(impl: AsyncPortsService, bridge: SyncBridge) -> None ``` #### PortsService.expire\_signed\_preview\_link [#portsserviceexpire_signed_preview_link] ```python def expire_signed_preview_link(port: int, token: str) -> None ``` Revoke a signed preview link before its natural expiry. #### PortsService.expose [#portsserviceexpose] ```python def expose(port: int, *, public: bool = False) -> PreviewEndpoint ``` Register a sandbox port as a preview endpoint. #### PortsService.is\_in\_use [#portsserviceis_in_use] ```python def is_in_use(port: int) -> bool ``` #### PortsService.iter\_endpoints [#portsserviceiter_endpoints] ```python def iter_endpoints(*, cursor: Optional[str] = None, limit: Optional[int] = None) -> Iterator[PreviewEndpoint] ``` #### PortsService.list [#portsservicelist] ```python def list() -> ListResult[int] ``` #### PortsService.list\_endpoints [#portsservicelist_endpoints] ```python def list_endpoints(*, cursor: Optional[str] = None, limit: Optional[int] = None) -> ListResult[PreviewEndpoint] ``` #### PortsService.preview\_link [#portsservicepreview_link] ```python def preview_link(port: int) -> PreviewLink ``` Preview URL plus access token for one sandbox port. #### PortsService.set\_public [#portsserviceset_public] ```python def set_public(port: int, *, public: bool) -> PreviewEndpoint ``` Change the visibility of an exposed port. #### PortsService.signed\_preview\_link [#portsservicesigned_preview_link] ```python def signed_preview_link(port: int, *, expires_in_seconds: Optional[int] = None) -> SignedPreviewLink ``` Return a self-contained signed URL for one sandbox port. #### PortsService.unexpose [#portsserviceunexpose] ```python def unexpose(port: int) -> None ``` ## AsyncPortsService [#asyncportsservice] ```python class AsyncPortsService() ``` #### AsyncPortsService.\_\_init\_\_ [#asyncportsservice__init__] ```python def __init__(transport: Optional[AsyncTransport], api: Optional[AsyncTransport] = None, *, sandbox_id: Optional[str] = None, mint_preview_token: Optional[Callable[[int], Awaitable[Optional[SandboxAccessToken]]]] = None) -> None ``` #### AsyncPortsService.list [#asyncportsservicelist] ```python async def list() -> ListResult[int] ``` #### AsyncPortsService.is\_in\_use [#asyncportsserviceis_in_use] ```python async def is_in_use(port: int) -> bool ``` #### AsyncPortsService.list\_endpoints [#asyncportsservicelist_endpoints] ```python async def list_endpoints(*, cursor: Optional[str] = None, limit: Optional[int] = None) -> ListResult[PreviewEndpoint] ``` #### AsyncPortsService.iter\_endpoints [#asyncportsserviceiter_endpoints] ```python async def iter_endpoints(*, cursor: Optional[str] = None, limit: Optional[int] = None) -> AsyncIterator[PreviewEndpoint] ``` #### AsyncPortsService.expose [#asyncportsserviceexpose] ```python async def expose(port: int, *, public: bool = False) -> PreviewEndpoint ``` Register a sandbox port as a preview endpoint. If the port is already exposed, returns the existing endpoint (updating its visibility if `public` differs from the current value). Public endpoints need no credential. Programmatic access to a private one needs the token from `preview_link` (see `daytona.v2.types.PreviewLink`) or a `signed_preview_link` URL. :param port: TCP port inside the sandbox (1–65535). :param public: When `True` the endpoint is publicly accessible without any credential. :returns: `daytona.v2.types.PreviewEndpoint` with the URL. #### AsyncPortsService.set\_public [#asyncportsserviceset_public] ```python async def set_public(port: int, *, public: bool) -> PreviewEndpoint ``` Change the visibility of an exposed port. The request replaces the port's preview registration in full, so a port that is not exposed yet is exposed with this visibility rather than rejected. Public endpoints need no credential. Programmatic access to a private one needs the token from `preview_link` or a `signed_preview_link` URL. :param port: TCP port inside the sandbox. :param public: `True` to make the endpoint publicly accessible; `False` to restrict it to credentialed callers. :returns: Updated `daytona.v2.types.PreviewEndpoint`. #### AsyncPortsService.preview\_link [#asyncportsservicepreview_link] ```python async def preview_link(port: int) -> PreviewLink ``` Preview URL plus access token for one sandbox port. Callers send the token in the `X-Daytona-Preview-Token` header. Public endpoints need no token (`token == ""`). The returned `daytona.v2.types.PreviewLink` also carries `expires_at` when the token's expiry is known. For private endpoints, a handle permitted to mint gets a short-lived sandbox access token scoped to exactly this port. Otherwise the preview-url token is passed through unchanged. Token contents are not used to infer access permissions. #### AsyncPortsService.signed\_preview\_link [#asyncportsservicesigned_preview_link] ```python async def signed_preview_link(port: int, *, expires_in_seconds: Optional[int] = None) -> SignedPreviewLink ``` Return a self-contained signed URL for one sandbox port. The token is embedded in the hostname, so no extra headers or credentials are needed — the right choice for handing a URL to a browser, a tool, or any client that cannot set request headers. The default lifetime is 60 seconds. Pass a longer `expires_in_seconds` for multi-step use (the deployment caps the maximum, typically 7 days). Revoke the link early with `expire_signed_preview_link`. :param port: TCP port inside the sandbox (1–65535). :param expires_in_seconds: Requested token lifetime in seconds (positive integer). Omit for the server default (60 s). :returns: `daytona.v2.types.SignedPreviewLink` with `url`, `token`, and `expires_at`. Example:: link = await sandbox.ports.signed_preview_link(8080, expires_in_seconds=300) # Hand link.url to a browser or another tool — no headers needed. [#hand-linkurl-to-a-browser-or-another-tool--no-headers-needed] #### AsyncPortsService.expire\_signed\_preview\_link [#asyncportsserviceexpire_signed_preview_link] ```python async def expire_signed_preview_link(port: int, token: str) -> None ``` Revoke a signed preview link before its natural expiry. :param port: TCP port the link was issued for. :param token: The `token` field from `daytona.v2.types.SignedPreviewLink`. #### AsyncPortsService.unexpose [#asyncportsserviceunexpose] ```python async def unexpose(port: int) -> None ``` ## PortMapping [#portmapping] ```python @dataclass(frozen=True) class PortMapping() ``` **Attributes**: - `port` _int_ - `proto` _str = 'tcp'_ # Docker (/docs/python-sdk/docker) ## DockerService [#dockerservice] ```python class DockerService() ``` Read-only Docker Engine status. Nothing here starts or restarts Docker. #### DockerService.\_\_init\_\_ [#dockerservice__init__] ```python def __init__(impl: AsyncDockerService, bridge: SyncBridge) -> None ``` #### DockerService.status [#dockerservicestatus] ```python def status() -> DockerStatus ``` Return the current Docker Engine status for this boot, answered immediately. #### DockerService.wait\_until\_ready [#dockerservicewait_until_ready] ```python def wait_until_ready(*, timeout: float = DOCKER_WAIT_DEFAULT_TIMEOUT_SECONDS) -> DockerStatus ``` Poll the Docker status until it is `ready` and return that status. ## AsyncDockerService [#asyncdockerservice] ```python class AsyncDockerService() ``` Read-only Docker Engine status. Nothing here starts or restarts Docker. A sandbox without Docker status support answers `status` and `wait_until_ready` with a `NotFoundError` (404). #### AsyncDockerService.\_\_init\_\_ [#asyncdockerservice__init__] ```python def __init__(transport: AsyncTransport) -> None ``` #### AsyncDockerService.status [#asyncdockerservicestatus] ```python async def status() -> DockerStatus ``` Return the current Docker Engine status for this boot, answered immediately. Raises `NotFoundError` (404) when the sandbox does not support the route. #### AsyncDockerService.wait\_until\_ready [#asyncdockerservicewait_until_ready] ```python async def wait_until_ready(*, timeout: float = DOCKER_WAIT_DEFAULT_TIMEOUT_SECONDS) -> DockerStatus ``` Poll the Docker status until it is `ready` and return that status. `timeout` is the wait budget in seconds (default 60); `0` waits without a deadline — avoid it for sandboxes whose Docker can stay `deferred`. Each poll asks the server to hold for up to one second while Docker is `starting`; answers that come back sooner are spaced 0.5 s apart. Raises `DockerNotReadyError` as soon as Docker settles in a state that cannot become `ready` (`failed`, `not_present`, `disabled`, `unmanaged`, or `unsupported`), and `DockerWaitTimeoutError` when the budget runs out while Docker is still `starting` or `deferred` — including when a status request is still unanswered at the deadline. No request runs more than a fraction of a second past the deadline. ## DockerStatus [#dockerstatus] ```python @dataclass(frozen=True) class DockerStatus() ``` **Attributes**: - `owner` _DockerOwner_ - `state` _DockerState_ - `process_id` _Optional\[str\] = None_ - `reason` _Optional\[str\] = None_ - `raw_owner` _Optional\[str\] = None_ - `raw_state` _Optional\[str\] = None_ ## DockerState [#dockerstate] ```python DockerState = Literal['ready', 'starting', 'failed', 'not_present', 'disabled', 'unmanaged', 'deferred', 'unsupported', 'unknown'] ``` ## DockerOwner [#dockerowner] ```python DockerOwner = Literal['daemon', 'entrypoint', 'none', 'unknown'] ``` # Image (/docs/python-sdk/image) ## ImageService [#imageservice] ```python class ImageService() ``` Image build/pull/list namespace. #### ImageService.\_\_init\_\_ [#imageservice__init__] ```python def __init__(impl: AsyncImageService, bridge: SyncBridge) -> None ``` #### ImageService.build [#imageservicebuild] ```python def build(builder: ImageBuilder, /, *, name: Optional[str] = None, idle_expiry_seconds: Optional[int] = None, region: Optional[str] = None, cpu_arch: Optional[str] = None, timeout: Optional[float] = None) -> Image ``` Build (or import) an image from an `ImageBuilder` declaration. #### ImageService.delete [#imageservicedelete] ```python def delete(image_id: str) -> None ``` #### ImageService.follow\_build\_logs [#imageservicefollow_build_logs] ```python def follow_build_logs(image_id: str, *, on_logs: _LogsCallback, on_event: Optional[_EventCallback] = None, cursor: Optional[str] = None, timeout: Optional[float] = None) -> BuildLogFollowResult ``` Observe a submitted image build. Timeout is in seconds, not execution TTL. #### ImageService.get [#imageserviceget] ```python def get(image_id: str, *, wait: Literal['ready'] | None = None, timeout: Optional[float] = None) -> Image ``` #### ImageService.iter [#imageserviceiter] ```python def iter(*, anonymous: bool = False, sandbox_id: Optional[str] = None, name: Optional[str] = None, cursor: Optional[str] = None, limit: Optional[int] = None, platform: Optional[Literal['true', 'false', 'any']] = None) -> Iterator[Image] ``` #### ImageService.list [#imageservicelist] ```python def list(*, anonymous: bool = False, sandbox_id: Optional[str] = None, name: Optional[str] = None, cursor: Optional[str] = None, limit: Optional[int] = None, platform: Optional[Literal['true', 'false', 'any']] = None) -> ListResult[Image] ``` List images (`GET /images`). #### ImageService.promote [#imageservicepromote] ```python def promote(image_id: str, name: str) -> Image ``` Name an ANONYMOUS image, making it permanent (`PATCH /images/{id}`). #### ImageService.pull [#imageservicepull] ```python def pull(image: str, *, name: Optional[str] = None, region: Optional[str] = None, wait: bool = True, timeout: Optional[float] = None) -> Image ``` Import a registry image, waiting until ready unless `wait=False`. ## AsyncImageService [#asyncimageservice] ```python class AsyncImageService() ``` Image build/pull/list namespace. #### AsyncImageService.\_\_init\_\_ [#asyncimageservice__init__] ```python def __init__(transport: AsyncTransport) -> None ``` #### AsyncImageService.follow\_build\_logs [#asyncimageservicefollow_build_logs] ```python async def follow_build_logs(image_id: str, *, on_logs: _LogsCallback, on_event: Optional[_EventCallback] = None, cursor: Optional[str] = None, timeout: Optional[float] = None) -> BuildLogFollowResult ``` Observe a submitted image build. Timeout is in seconds, not execution TTL. #### AsyncImageService.build [#asyncimageservicebuild] ```python async def build(builder: ImageBuilder, /, *, name: Optional[str] = None, idle_expiry_seconds: Optional[int] = None, region: Optional[str] = None, cpu_arch: Optional[str] = None, timeout: Optional[float] = None) -> Image ``` Build (or import) an image from an `ImageBuilder` declaration. The builder is the only way to say WHAT to build — `ImageBuilder. from_dockerfile(...)`, `.from_registry(...)`, or the fluent `.run_commands` / `.env` / `.workdir` chain — in both SDKs (parity with TypeScript's `images.build(builder, options)`). `name` omitted makes the image anonymous; `idle_expiry_seconds` is then its idle-retention window — deleted once that long has passed without a sandbox being created from it (every create restarts the clock); omitted ⇒ the maximum retention supported by the API. #### AsyncImageService.pull [#asyncimageservicepull] ```python async def pull(image: str, *, name: Optional[str] = None, region: Optional[str] = None, wait: bool = True, timeout: Optional[float] = None) -> Image ``` Import a registry image, waiting until ready unless `wait=False`. `timeout` is the submission and readiness budget in seconds; omitted or zero waits without a deadline. A failed import raises `ImageBuildFailedError` with the server's recorded error. #### AsyncImageService.get [#asyncimageserviceget] ```python async def get(image_id: str, *, wait: Literal['ready'] | None = None, timeout: Optional[float] = None) -> Image ``` #### AsyncImageService.promote [#asyncimageservicepromote] ```python async def promote(image_id: str, name: str) -> Image ``` Name an ANONYMOUS image, making it permanent (`PATCH /images/{id}`). Promotion only: an image that already has a name answers 409 — renaming a named image is not offered (sandboxes reference images by id, so a rename would silently relabel every sandbox created from it). #### AsyncImageService.delete [#asyncimageservicedelete] ```python async def delete(image_id: str) -> None ``` #### AsyncImageService.list [#asyncimageservicelist] ```python async def list(*, anonymous: bool = False, sandbox_id: Optional[str] = None, name: Optional[str] = None, cursor: Optional[str] = None, limit: Optional[int] = None, platform: Optional[Literal['true', 'false', 'any']] = None) -> ListResult[Image] ``` List images (`GET /images`). `platform` picks the shared images Daytona publishes for every project: `"false"` (the server default) lists the project's own images, `"true"` lists only the non-deprecated platform images (the default one carries `default=True`), and `"any"` lists both. #### AsyncImageService.iter [#asyncimageserviceiter] ```python async def iter(*, anonymous: bool = False, sandbox_id: Optional[str] = None, name: Optional[str] = None, cursor: Optional[str] = None, limit: Optional[int] = None, platform: Optional[Literal['true', 'false', 'any']] = None) -> AsyncIterator[Image] ``` ## ImageListItem [#imagelistitem] ```python class ImageListItem(BaseModel) ``` An image with its pagination cursor. **Attributes**: - `anonymous` _StrictBool = Field(description='Whether the image has no permanent name.')_ - `bytes` _Optional\[StrictInt\] = Field(default=None, description='The image size in bytes, or null until the build completes.')_ - `var_class` _StrictStr = Field(description='The sandbox class supported by the image.', alias='class')_ - `created_at` _datetime = Field(description='When the image was created.')_ - `cursor` _StrictStr = Field(description='Opaque continuation token for the next image in the list.')_ - `default` _StrictBool = Field(description='Whether this is the image a sandbox create without `image` boots.')_ - `deprecated` _StrictBool = Field(description='Whether this platform image is deprecated. A deprecated image is not listed and cannot be used by name, but its ID still resolves.')_ - `disk_mib` _Optional\[StrictInt\] = Field(default=None, description='The disk size in MiB that a macOS sandbox created from this image gets when the create omits `disk_mib`. Set for saved macOS sandbox disks; null for every other image.')_ - `error` _Optional\[StrictStr\] = Field(default=None, description='Build failure reason; null unless `status` is `failed`.')_ - `expires_at` _Optional\[datetime\] = Field(default=None, description='When an anonymous image expires, or null for a permanent image.')_ - `format_outdated` _StrictBool = Field(description='`format_version` is below the current format. Such an image converts on its first Linux sandbox create (which waits `queued` meanwhile) or ahead of time with `POST /images/{id}/convert`; other operations refuse it with `IMAGE_FORMAT_OUTDATED` until then.')_ - `format_version` _StrictInt = Field(description='Image format version: `1` for images imported from Daytona v0, `2` for the current format. See `status` for image readiness.')_ - `id` _StrictStr = Field(description='The image ID.')_ - `imported_from` _Optional\[ImportedFrom\] = None_ - `layer_count` _Optional\[StrictInt\] = Field(default=None, description='The number of filesystem layers, or null until the build completes.')_ - `name` _Optional\[StrictStr\] = Field(default=None, description='The image name, or null for an anonymous image.')_ - `origin` _StrictStr = Field(description='How the image was created.')_ - `platform` _StrictBool = Field(description="Whether the platform publishes this image for every project. A project's own image with the same name takes precedence for that project, and platform images cannot be renamed, converted, or deleted.")_ - `region_id` _StrictStr = Field(description='The home region.')_ - `region_ids` _List\[StrictStr\] = Field(description='Every region where the image is available.')_ - `retention` _ImageRetention_ - `source` _Optional\[ImageSourceValue\] = None_ - `status` _StrictStr = Field(description='The build status.')_ - `updated_at` _datetime = Field(description='When the image was last updated.')_ - `additional_properties` _Dict\[str, Any\] = \{\}_ ##### model\_config [#model_config] ```python model_config = ConfigDict(populate_by_name=True, validate_assignment=True, protected_namespaces=()) ``` #### ImageListItem.to\_str [#imagelistitemto_str] ```python def to_str() -> str ``` Returns the string representation of the model using alias #### ImageListItem.to\_json [#imagelistitemto_json] ```python def to_json() -> str ``` Returns the JSON representation of the model using alias #### ImageListItem.from\_json [#imagelistitemfrom_json] ```python @classmethod def from_json(json_str: str) -> Optional[Self] ``` Create an instance of ImageListItem from a JSON string #### ImageListItem.to\_dict [#imagelistitemto_dict] ```python 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. #### ImageListItem.from\_dict [#imagelistitemfrom_dict] ```python @classmethod def from_dict(obj: Optional[Dict[str, Any]]) -> Optional[Self] ``` Create an instance of ImageListItem from a dict ## BuildLogFollowResult [#buildlogfollowresult] ```python @dataclass(frozen=True) class BuildLogFollowResult() ``` **Attributes**: - `status` _str_ - `reason` _BuildLogDoneReason_ - `output_complete` _bool_ - `cursor` _str \| None = None_ - `raw_reason` _str \| None = None_ ## BuildLogStateEvent [#buildlogstateevent] ```python @dataclass(frozen=True) class BuildLogStateEvent() ``` **Attributes**: - `status` _str_ - `error` _str \| None = None_ - `deadline_at` _str \| None = None_ - `type` _Literal\['state'\] = 'state'_ ## BuildLogChunkEvent [#buildlogchunkevent] ```python @dataclass(frozen=True) class BuildLogChunkEvent() ``` **Attributes**: - `data_base64` _str_ - `start_offset` _str_ - `next_offset` _str_ - `cursor` _str_ - `type` _Literal\['log'\] = 'log'_ ## BuildLogGapEvent [#buildloggapevent] ```python @dataclass(frozen=True) class BuildLogGapEvent() ``` **Attributes**: - `requested_offset` _str_ - `first_available_offset` _str_ - `dropped_bytes` _str_ - `cursor` _str_ - `reason` _BuildLogGapReason = 'truncated'_ - `type` _Literal\['gap'\] = 'gap'_ - `raw_reason` _str \| None = None_ ## BuildLogUnavailableEvent [#buildlogunavailableevent] ```python @dataclass(frozen=True) class BuildLogUnavailableEvent() ``` **Attributes**: - `reason` _str_ - `type` _Literal\['unavailable'\] = 'unavailable'_ ## BuildLogSourceChangedEvent [#buildlogsourcechangedevent] ```python @dataclass(frozen=True) class BuildLogSourceChangedEvent() ``` **Attributes**: - `reason` _str_ - `type` _Literal\['source_changed'\] = 'source_changed'_ ## BuildLogDoneEvent [#buildlogdoneevent] ```python @dataclass(frozen=True) class BuildLogDoneEvent() ``` **Attributes**: - `result` _BuildLogFollowResult_ - `type` _Literal\['done'\] = 'done'_ ## BuildLogErrorEvent [#buildlogerrorevent] ```python @dataclass(frozen=True) class BuildLogErrorEvent() ``` **Attributes**: - `error` _str_ - `code` _str_ - `retryable` _bool_ - `trace_id` _str \| None = None_ - `type` _Literal\['error'\] = 'error'_ ## ImageBuilder [#imagebuilder] ```python @dataclass(frozen=True, slots=True) class ImageBuilder() ``` #### ImageBuilder.from\_registry [#imagebuilderfrom_registry] ```python @classmethod def from_registry(ref: str) -> Self ``` #### ImageBuilder.from\_dockerfile [#imagebuilderfrom_dockerfile] ```python @classmethod def from_dockerfile(content: str) -> Self ``` #### ImageBuilder.pip\_install [#imagebuilderpip_install] ```python def pip_install(*packages: str) -> Self ``` #### ImageBuilder.run\_commands [#imagebuilderrun_commands] ```python def run_commands(*commands: str) -> Self ``` #### ImageBuilder.env [#imagebuilderenv] ```python @overload def env(name: str, value: str, /) -> Self ``` #### ImageBuilder.env [#imagebuilderenv-1] ```python @overload def env(values: Mapping[str, str], /) -> Self ``` #### ImageBuilder.workdir [#imagebuilderworkdir] ```python def workdir(path: str, /) -> Self ``` #### ImageBuilder.build\_request\_source [#imagebuilderbuild_request_source] ```python def build_request_source() -> tuple[dict[str, str] | None, str | None] ``` #### ImageBuilder.render\_dockerfile [#imagebuilderrender_dockerfile] ```python def render_dockerfile() -> str ``` Render the Dockerfile the build request carries. Byte-identical to TypeScript's `ImageBuilder.toDockerfile()` for the same builder: one line per layer, a single trailing newline (a POSIX text file), no trailing whitespace. ## ImageRef [#imageref] ```python @dataclass(frozen=True, slots=True) class ImageRef() ``` **Attributes**: - `id` _str_ - `name` _Optional\[str\] = None_ ## Image [#image] ```python @dataclass(frozen=True, slots=True) class Image() ``` **Attributes**: - `id` _str_ - `name` _Optional\[str\]_ - `status` _str_ - `region` _str_ - `anonymous` _bool_ - `retention` _ArtifactRetention_ - `var_class` _str_ - `available_in` _list\[str\]_ - `origin` _str_ - `created_at` _Optional\[str\] = None_ - `error` _Optional\[str\] = None_ - `expires_at` _Optional\[str\] = None_ - `source` _Optional\[ImageSource\] = None_ - `bytes` _Optional\[int\] = None_ - `layer_count` _Optional\[int\] = None_ - `cursor` _Optional\[str\] = None_ - `format_version` _Optional\[int\] = None_ - `format_outdated` _bool = False_ - `platform` _bool = False_ - `default` _bool = False_ - `deprecated` _bool = False_ - `updated_at` _Optional\[str\] = None_ - `disk_mib` _Optional\[int\] = None_ - `raw_retention` _str = field(default='', kw_only=True)_ ## BuildLogDoneReason [#buildlogdonereason] ```python BuildLogDoneReason = Literal['terminal', 'deadline', 'not_applicable', 'resource_deleted', 'unknown'] ``` ## BuildLogGapReason [#buildloggapreason] ```python BuildLogGapReason = Literal['truncated', 'unknown'] ``` ## BuildLogEvent [#buildlogevent] ```python BuildLogEvent = BuildLogStateEvent | BuildLogChunkEvent | BuildLogGapEvent | BuildLogUnavailableEvent | BuildLogSourceChangedEvent | BuildLogDoneEvent | BuildLogErrorEvent ``` ## ImageBuildResponse [#imagebuildresponse] ```python ImageBuildResponse = _gen.api.AsyncOperation ``` ## ArtifactRetention [#artifactretention] ```python ArtifactRetention = Literal['permanent', 'idle', 'unknown'] ``` ## ImageSource [#imagesource] ```python ImageSource = Union[RegistryImageSource, DockerfileImageSource, NamedImageSource, ManifestImageSource] ``` # Snapshot (/docs/python-sdk/snapshot) ## SnapshotService [#snapshotservice] ```python class SnapshotService() ``` Sandbox snapshot namespace. #### SnapshotService.\_\_init\_\_ [#snapshotservice__init__] ```python def __init__(impl: AsyncSnapshotService, bridge: SyncBridge) -> None ``` #### SnapshotService.delete [#snapshotservicedelete] ```python def delete(snapshot_id: str) -> None ``` Delete a snapshot (409 while sandboxes still depend on it). #### SnapshotService.get [#snapshotserviceget] ```python def get(snapshot_id: str, *, wait: Optional[Literal['ready']] = None, timeout: Optional[float] = None) -> Snapshot ``` #### SnapshotService.iter [#snapshotserviceiter] ```python def iter(*, name: Optional[str] = None, sandbox_id: Optional[str] = None, cursor: Optional[str] = None, limit: Optional[int] = None) -> Iterator[Snapshot] ``` #### SnapshotService.list [#snapshotservicelist] ```python def list(*, name: Optional[str] = None, sandbox_id: Optional[str] = None, cursor: Optional[str] = None, limit: Optional[int] = None) -> ListResult[Snapshot] ``` ## AsyncSnapshotService [#asyncsnapshotservice] ```python class AsyncSnapshotService() ``` Sandbox snapshot namespace. #### AsyncSnapshotService.\_\_init\_\_ [#asyncsnapshotservice__init__] ```python def __init__(transport: AsyncTransport) -> None ``` #### AsyncSnapshotService.list [#asyncsnapshotservicelist] ```python async def list(*, name: Optional[str] = None, sandbox_id: Optional[str] = None, cursor: Optional[str] = None, limit: Optional[int] = None) -> ListResult[Snapshot] ``` #### AsyncSnapshotService.iter [#asyncsnapshotserviceiter] ```python async def iter(*, name: Optional[str] = None, sandbox_id: Optional[str] = None, cursor: Optional[str] = None, limit: Optional[int] = None) -> AsyncIterator[Snapshot] ``` #### AsyncSnapshotService.get [#asyncsnapshotserviceget] ```python async def get(snapshot_id: str, *, wait: Optional[Literal['ready']] = None, timeout: Optional[float] = None) -> Snapshot ``` #### AsyncSnapshotService.delete [#asyncsnapshotservicedelete] ```python async def delete(snapshot_id: str) -> None ``` Delete a snapshot (409 while sandboxes still depend on it). ## Snapshot [#snapshot] ```python @dataclass(frozen=True, slots=True) class Snapshot() ``` **Attributes**: - `id` _str_ - `name` _str_ - `status` _str_ - `region` _str_ - `kind` _SnapshotKind_ - `var_class` _str_ - `available_in` _list\[str\]_ - `created_at` _Optional\[str\] = None_ - `error` _Optional\[str\] = None_ - `bytes` _Optional\[int\] = None_ - `memory_bytes` _Optional\[int\] = None_ - `sandbox_id` _Optional\[str\] = None_ - `raw_kind` _str = field(default='', kw_only=True)_ - `cursor` _Optional\[str\] = None_ - `updated_at` _Optional\[str\] = None_ # Volume (/docs/python-sdk/volume) ## SandboxVolumesService [#sandboxvolumesservice] ```python class SandboxVolumesService() ``` Pull attached volumes, separate from the root platform volume service. #### SandboxVolumesService.\_\_init\_\_ [#sandboxvolumesservice__init__] ```python def __init__(impl: AsyncSandboxVolumesService, bridge: SyncBridge) -> None ``` #### SandboxVolumesService.pull [#sandboxvolumesservicepull] ```python def pull(volume_id: str, *, request_id: str, timeout: Optional[float] = None) -> PullVolumeResult ``` Submit/check once; timeout is a server wait in seconds (0–30, default 30). ## AsyncSandboxVolumesService [#asyncsandboxvolumesservice] ```python class AsyncSandboxVolumesService() ``` Pull attached volumes, separate from the root platform volume service. #### AsyncSandboxVolumesService.\_\_init\_\_ [#asyncsandboxvolumesservice__init__] ```python def __init__(transport: AsyncTransport) -> None ``` #### AsyncSandboxVolumesService.pull [#asyncsandboxvolumesservicepull] ```python async def pull(volume_id: str, *, request_id: str, timeout: Optional[float] = None) -> PullVolumeResult ``` Submit/check once; timeout is a server wait in seconds (0–30, default 30). Zero does not wait: it submits a new request_id, or returns a known one's last outcome without retrying it; a timeout above zero retries pending, unavailable or rate-limited work. Expiry does not cancel work. Neither retries nor identities are automatic. ## VolumeService [#volumeservice] ```python class VolumeService() ``` Volume management namespace. #### VolumeService.\_\_init\_\_ [#volumeservice__init__] ```python def __init__(impl: AsyncVolumeService, bridge: SyncBridge) -> None ``` #### VolumeService.create [#volumeservicecreate] ```python def create(*, name: str, size_gib: Optional[int] = None) -> Volume ``` Create a volume. #### VolumeService.delete [#volumeservicedelete] ```python def delete(volume_id: str, *, id_only: bool = False) -> None ``` Request deletion and return once the API accepts it. #### VolumeService.get [#volumeserviceget] ```python def get(name_or_id: str, *, create: bool = False, id_only: bool = False) -> Volume ``` Fetch by id or name; `id_only` disables name fallback. #### VolumeService.iter [#volumeserviceiter] ```python def iter(*, cursor: Optional[str] = None, limit: Optional[int] = None) -> Iterator[Volume] ``` #### VolumeService.list [#volumeservicelist] ```python def list(*, cursor: Optional[str] = None, limit: Optional[int] = None) -> ListResult[Volume] ``` List volumes. ## AsyncVolumeService [#asyncvolumeservice] ```python class AsyncVolumeService() ``` Volume management namespace. #### AsyncVolumeService.\_\_init\_\_ [#asyncvolumeservice__init__] ```python def __init__(transport: AsyncTransport) -> None ``` #### AsyncVolumeService.list [#asyncvolumeservicelist] ```python async def list(*, cursor: Optional[str] = None, limit: Optional[int] = None) -> ListResult[Volume] ``` List volumes. #### AsyncVolumeService.iter [#asyncvolumeserviceiter] ```python async def iter(*, cursor: Optional[str] = None, limit: Optional[int] = None) -> AsyncIterator[Volume] ``` #### AsyncVolumeService.get [#asyncvolumeserviceget] ```python async def get(name_or_id: str, *, create: bool = False, id_only: bool = False) -> Volume ``` Fetch by id or name; `id_only` disables name fallback. #### AsyncVolumeService.create [#asyncvolumeservicecreate] ```python async def create(*, name: str, size_gib: Optional[int] = None) -> Volume ``` Create a volume. #### AsyncVolumeService.delete [#asyncvolumeservicedelete] ```python async def delete(volume_id: str, *, id_only: bool = False) -> None ``` Request deletion and return once the API accepts it. ## PullVolumeResult [#pullvolumeresult] ```python @dataclass(frozen=True) class PullVolumeResult() ``` **Attributes**: - `request_id` _str_ - `status` _PullVolumeStatus_ - `manifest_id` _Optional\[str\]_ - `raw_status` _Optional\[str\] = None_ ## VolumeMount [#volumemount] ```python @dataclass(frozen=True) class VolumeMount() ``` Attach a volume to a sandbox. **Attributes**: - `volume_id` _str_ - `mount_path` _str_ - `subpath` _Optional\[str\] = None_ - `read_only` _Optional\[bool\] = None_ ## Volume [#volume] ```python @dataclass(frozen=True, slots=True) class Volume() ``` **Attributes**: - `id` _str_ - `name` _str_ - `type` _VolumeType_ - `raw_type` _str_ - `status` _VolumeState_ - `raw_status` _str_ - `created_at` _datetime_ - `updated_at` _datetime_ - `size_gib` _Optional\[int\] = None_ - `error` _Optional\[str\] = None_ - `last_used_at` _Optional\[datetime\] = None_ - `options` _Optional\[JsonObject\] = None_ - `used_bytes` _Optional\[int\] = None_ - `used_bytes_at` _Optional\[datetime\] = None_ ## PullVolumeStatus [#pullvolumestatus] ```python PullVolumeStatus = Literal['pulled', 'unchanged', 'pending', 'unknown'] ``` ## VolumeState [#volumestate] ```python VolumeState = Literal['ready', 'deleting', 'deleted', 'error', 'unknown'] ``` ## VolumeType [#volumetype] ```python VolumeType = Literal['disk', 'bucket', 'unknown'] ``` # Reservations (/docs/python-sdk/reservations) ## ReservationService [#reservationservice] ```python class ReservationService() ``` Dedicated-Mac reservations, which macOS sandboxes run on. #### ReservationService.\_\_init\_\_ [#reservationservice__init__] ```python def __init__(impl: AsyncReservationService, bridge: SyncBridge) -> None ``` #### ReservationService.create [#reservationservicecreate] ```python def create(*, region: str, model: Optional[str] = None, idempotency_key: Optional[str] = None, auto_renew: Optional[bool] = None) -> MacReservation ``` Reserve a Mac of `model` in `region`. #### ReservationService.create\_bulk [#reservationservicecreate_bulk] ```python def create_bulk(*, region: str, count: int, min_count: Optional[int] = None, model: Optional[str] = None, auto_renew: Optional[bool] = None, idempotency_key: Optional[str] = None) -> MacReservationBatch ``` Reserve count Macs of one model in region in one request. #### ReservationService.get [#reservationserviceget] ```python def get(reservation_id: str) -> MacReservation ``` #### ReservationService.iter [#reservationserviceiter] ```python def iter(*, cursor: Optional[str] = None, limit: Optional[int] = None) -> Iterator[MacReservation] ``` Every reservation of the organization, draining page by page. #### ReservationService.list [#reservationservicelist] ```python def list(*, cursor: Optional[str] = None, limit: Optional[int] = None) -> ListResult[MacReservation] ``` One page of the organization's reservations. #### ReservationService.renew [#reservationservicerenew] ```python def renew(reservation_id: str, *, idempotency_key: Optional[str] = None) -> MacReservation ``` Renew the reservation for its next period, which the server charges. #### ReservationService.update [#reservationserviceupdate] ```python def update(reservation_id: str, *, auto_renew: bool) -> MacReservation ``` Turn the reservation's auto-renewal on or off. ## AsyncReservationService [#asyncreservationservice] ```python class AsyncReservationService() ``` Dedicated-Mac reservations, which macOS sandboxes run on. A macOS sandbox runs on a Mac the organization has reserved: reserve one here, or let a macOS create buy one (`reservation="new"`, or the organization's auto-reserve). A reservation lasts 24-hour periods, each charged when it starts. Reserving, renewing and turning auto-renew on need macOS access enabled for the organization (otherwise `403` `FEATURE_NOT_ENABLED`, raised as `FeatureNotEnabledError`); listing, reading and turning auto-renew off do not. #### AsyncReservationService.\_\_init\_\_ [#asyncreservationservice__init__] ```python def __init__(transport: AsyncTransport) -> None ``` #### AsyncReservationService.create [#asyncreservationservicecreate] ```python async def create(*, region: str, model: Optional[str] = None, idempotency_key: Optional[str] = None, auto_renew: Optional[bool] = None) -> MacReservation ``` Reserve a Mac of `model` in `region`. `model`: Mac model slug from GET /mac-models. Omitted uses the region's default model. An unavailable model is never upgraded. The request always carries an `Idempotency-Key`: `idempotency_key` when given, otherwise a random UUID the SDK generates for this call. Pass your own key if you may retry, so a retry after a lost response returns the same reservation instead of reserving a second Mac. `auto_renew` defaults server-side to the organization's auto-reserve setting. Raises `ConflictError` with `code == "NO_MAC_AVAILABLE"` when no Mac of that model is free in the region. #### AsyncReservationService.create\_bulk [#asyncreservationservicecreate_bulk] ```python async def create_bulk(*, region: str, count: int, min_count: Optional[int] = None, model: Optional[str] = None, auto_renew: Optional[bool] = None, idempotency_key: Optional[str] = None) -> MacReservationBatch ``` Reserve count Macs of one model in region in one request. min_count (default count) is the fewest to accept: with fewer Macs free, the request reserves as many as are free, or none, failing with ConflictError code == "NO_MAC_AVAILABLE" when fewer than min_count are free. The request always carries an Idempotency-Key: idempotency_key when given, otherwise a random key the SDK generates for this call. Pass your own key if you may retry, so a retry after a lost response returns the same reservations instead of reserving more Macs. #### AsyncReservationService.list [#asyncreservationservicelist] ```python async def list(*, cursor: Optional[str] = None, limit: Optional[int] = None) -> ListResult[MacReservation] ``` One page of the organization's reservations. #### AsyncReservationService.iter [#asyncreservationserviceiter] ```python async def iter(*, cursor: Optional[str] = None, limit: Optional[int] = None) -> AsyncIterator[MacReservation] ``` Every reservation of the organization, draining page by page. #### AsyncReservationService.get [#asyncreservationserviceget] ```python async def get(reservation_id: str) -> MacReservation ``` #### AsyncReservationService.renew [#asyncreservationservicerenew] ```python async def renew(reservation_id: str, *, idempotency_key: Optional[str] = None) -> MacReservation ``` Renew the reservation for its next period, which the server charges. The request always carries an Idempotency-Key: idempotency_key when given, otherwise a random key the SDK generates for this call. Pass your own key if you may retry, so a retry after a lost response does not pay for a second period. #### AsyncReservationService.update [#asyncreservationserviceupdate] ```python async def update(reservation_id: str, *, auto_renew: bool) -> MacReservation ``` Turn the reservation's auto-renewal on or off. Turning it on needs macOS access enabled for the organization; turning it off works without it, so an organization can stop a reservation renewing. Raises `ConflictError` when the reservation is no longer live. ## MacReservation [#macreservation] ```python @dataclass(frozen=True, slots=True) class MacReservation() ``` **Attributes**: - `id` _str_ - `org_id` _str_ - `project_id` _str_ - `region` _str_ - `status` _MacReservationStatus_ - `raw_status` _str_ - `sandboxes_per_mac` _int_ - `period_n` _int_ - `period_seconds` _int_ - `created_at` _datetime_ - `slots_used` _int_ - `renewal_pending` _bool_ - `auto_renew` _bool_ - `origin` _MacReservationOrigin_ - `raw_origin` _str_ - `resources_used` _MacResources_ - `activated_at` _Optional\[datetime\] = None_ - `capacity` _Optional\[MacResources\] = None_ - `model` _Optional\[str\] = None_ - `end_reason` _Optional\[MacReservationEndReason\] = None_ - `raw_end_reason` _Optional\[str\] = None_ - `ended_at` _Optional\[datetime\] = None_ - `pending_mac_started_at` _Optional\[datetime\] = None_ - `period_end` _Optional\[datetime\] = None_ - `period_started_at` _Optional\[datetime\] = None_ - `reissued_at` _Optional\[datetime\] = None_ - `renewal_error` _Optional\[str\] = None_ ## MacReservationBatch [#macreservationbatch] ```python @dataclass(frozen=True, slots=True) class MacReservationBatch() ``` `POST /reservations/bulk`: `requested` (the request's count), `reserved`, and one reservation per reserved Mac. **Attributes**: - `requested` _int_ - `reserved` _int_ - `reservations` _List\[MacReservation\]_ ## MacReservationStatus [#macreservationstatus] ```python MacReservationStatus = Literal['pending_charge', 'pending_mac', 'active', 'ending', 'released', 'failed', 'unknown'] ``` ## MacReservationEndReason [#macreservationendreason] ```python MacReservationEndReason = Literal['expired', 'released', 'charge_failed', 'not_accepted', 'reissued', 'operator', 'unknown'] ``` ## MacReservationOrigin [#macreservationorigin] ```python MacReservationOrigin = Literal['explicit', 'auto', 'unknown'] ``` # MacModels (/docs/python-sdk/mac-models) ## MacModelService [#macmodelservice] ```python class MacModelService() ``` The Mac model registry (`GET /mac-models`). #### MacModelService.\_\_init\_\_ [#macmodelservice__init__] ```python def __init__(impl: AsyncMacModelService, bridge: SyncBridge) -> None ``` #### MacModelService.catalog [#macmodelservicecatalog] ```python def catalog(*, region: Optional[str] = None) -> MacCatalog ``` Free Macs and prices per Mac model (GET /mac-catalog). available is advisory; price is null when pricing is unavailable. #### MacModelService.list [#macmodelservicelist] ```python def list() -> List[MacModel] ``` Every registered Mac model, ordered by `id`. ## AsyncMacModelService [#asyncmacmodelservice] ```python class AsyncMacModelService() ``` The Mac model registry (`GET /mac-models`). Lists the models `reservations.create(model=...)` accepts, with each model's CPU cores, physical memory, physical SSD capacity and sandbox disk room in MiB, maximum sandbox count, and default sandbox size. `catalog()` adds free Macs and prices. #### AsyncMacModelService.\_\_init\_\_ [#asyncmacmodelservice__init__] ```python def __init__(transport: AsyncTransport) -> None ``` #### AsyncMacModelService.list [#asyncmacmodelservicelist] ```python async def list() -> List[MacModel] ``` Every registered Mac model, ordered by `id`. #### AsyncMacModelService.catalog [#asyncmacmodelservicecatalog] ```python async def catalog(*, region: Optional[str] = None) -> MacCatalog ``` Free Macs and prices per Mac model (GET /mac-catalog). available is advisory; price is null when pricing is unavailable. ## MacModel [#macmodel] ```python class MacModel(BaseModel) ``` A Mac model. **Attributes**: - `cores` _StrictInt = Field(description='CPU cores in the Mac. A Mac core is one CPU (Apple Silicon has no SMT).')_ - `default_size` _Optional\[MacResources\]_ - `disk_mib` _StrictInt = Field(description='Physical SSD capacity in MiB, not free space or a per-sandbox disk allowance.')_ - `id` _StrictStr = Field(description='Mac model slug accepted by POST /reservations.')_ - `max_sandboxes` _StrictInt = Field(description='Most sandboxes a Mac of this model runs at once: 2 when its cores, memory, and sandbox disk room each fit two minimum-sized sandboxes (4 cores, 4096 MiB, 81920 MiB of disk), 1 when they fit one, and 0 when they fit none. The sizes of the running sandboxes must also fit the Mac.')_ - `memory_mib` _StrictInt = Field(description='Physical memory in MiB.')_ - `name` _StrictStr = Field(description='Display name of the Mac model.')_ - `sandbox_disk_mib` _StrictInt = Field(description="Disk room for sandboxes on one Mac of this model, in MiB. The disks of all sandboxes on the Mac, stopped sandboxes included, add up to at most this. Zero until the model's disk room is measured.")_ - `additional_properties` _Dict\[str, Any\] = \{\}_ ##### model\_config [#model_config] ```python model_config = ConfigDict(populate_by_name=True, validate_assignment=True, protected_namespaces=()) ``` #### MacModel.to\_str [#macmodelto_str] ```python def to_str() -> str ``` Returns the string representation of the model using alias #### MacModel.to\_json [#macmodelto_json] ```python def to_json() -> str ``` Returns the JSON representation of the model using alias #### MacModel.from\_json [#macmodelfrom_json] ```python @classmethod def from_json(json_str: str) -> Optional[Self] ``` Create an instance of MacModel from a JSON string #### MacModel.to\_dict [#macmodelto_dict] ```python 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. #### MacModel.from\_dict [#macmodelfrom_dict] ```python @classmethod def from_dict(obj: Optional[Dict[str, Any]]) -> Optional[Self] ``` Create an instance of MacModel from a dict ## MacCatalog [#maccatalog] ```python class MacCatalog(BaseModel) ``` Free Macs and prices per Mac model, per region. **Attributes**: - `regions` _List\[MacCatalogRegion\] = Field(description='Every region the answer covers, in catalog order.')_ - `additional_properties` _Dict\[str, Any\] = \{\}_ ##### model\_config [#model_config-1] ```python model_config = ConfigDict(populate_by_name=True, validate_assignment=True, protected_namespaces=()) ``` #### MacCatalog.to\_str [#maccatalogto_str] ```python def to_str() -> str ``` Returns the string representation of the model using alias #### MacCatalog.to\_json [#maccatalogto_json] ```python def to_json() -> str ``` Returns the JSON representation of the model using alias #### MacCatalog.from\_json [#maccatalogfrom_json] ```python @classmethod def from_json(json_str: str) -> Optional[Self] ``` Create an instance of MacCatalog from a JSON string #### MacCatalog.to\_dict [#maccatalogto_dict] ```python 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. #### MacCatalog.from\_dict [#maccatalogfrom_dict] ```python @classmethod def from_dict(obj: Optional[Dict[str, Any]]) -> Optional[Self] ``` Create an instance of MacCatalog from a dict # Secret (/docs/python-sdk/secret) ## SecretService [#secretservice] ```python class SecretService() ``` Project secret namespace. #### SecretService.\_\_init\_\_ [#secretservice__init__] ```python def __init__(impl: AsyncSecretService, bridge: SyncBridge) -> None ``` #### SecretService.delete [#secretservicedelete] ```python def delete(name: str) -> None ``` Delete a secret. #### SecretService.get [#secretserviceget] ```python def get(name: str) -> Secret ``` Fetch one secret's metadata (never its value). #### SecretService.iter [#secretserviceiter] ```python def iter(*, cursor: Optional[str] = None, limit: Optional[int] = None) -> Iterator[Secret] ``` #### SecretService.list [#secretservicelist] ```python def list(*, cursor: Optional[str] = None, limit: Optional[int] = None) -> ListResult[Secret] ``` List secret metadata. #### SecretService.set [#secretserviceset] ```python def set(name: str, value: str, *, allowed_domains: Sequence[str], description: Optional[str] = None, if_not_exists: bool = False) -> Secret ``` Create or update a write-only secret. ## AsyncSecretService [#asyncsecretservice] ```python class AsyncSecretService() ``` Project secret namespace. Project-scoped secrets: named key/value pairs stored encrypted in the project. Attach one or more to a sandbox at creation via the `secrets` create parameter (a list of names). Attached secrets are available to outbound HTTPS requests to their allowed domains, not plain HTTP requests. Their values never enter the sandbox and are never returned by the API (write-only). #### AsyncSecretService.\_\_init\_\_ [#asyncsecretservice__init__] ```python def __init__(transport: AsyncTransport) -> None ``` #### AsyncSecretService.list [#asyncsecretservicelist] ```python async def list(*, cursor: Optional[str] = None, limit: Optional[int] = None) -> ListResult[Secret] ``` List secret metadata. #### AsyncSecretService.iter [#asyncsecretserviceiter] ```python async def iter(*, cursor: Optional[str] = None, limit: Optional[int] = None) -> AsyncIterator[Secret] ``` #### AsyncSecretService.get [#asyncsecretserviceget] ```python async def get(name: str) -> Secret ``` Fetch one secret's metadata (never its value). #### AsyncSecretService.set [#asyncsecretserviceset] ```python async def set(name: str, value: str, *, allowed_domains: Sequence[str], description: Optional[str] = None, if_not_exists: bool = False) -> Secret ``` Create or update a write-only secret. `allowed_domains`: The hosts where this secret's value may be sent (exact or `*.` wildcard), or `["*"]` for any verified host. `"*"` lets the value reach any HTTPS host, including one a compromised sandbox controls. #### AsyncSecretService.delete [#asyncsecretservicedelete] ```python async def delete(name: str) -> None ``` Delete a secret. ## Secret [#secret] ```python class Secret(BaseModel) ``` Secret metadata. The value is write-only. **Attributes**: - `allowed_domains` _List\[StrictStr\] = Field(description='The hosts the secret\\'s value may be sent to. `["*"]` means any host the platform has verified; an empty list means the secret is sent nowhere.')_ - `created_at` _datetime = Field(description='When the secret was created.')_ - `description` _Optional\[StrictStr\] = Field(default=None, description='The user-facing description, or null when absent.')_ - `name` _StrictStr = Field(description='The secret name.')_ - `updated_at` _datetime = Field(description='When the secret was last updated.')_ - `additional_properties` _Dict\[str, Any\] = \{\}_ ##### model\_config [#model_config] ```python model_config = ConfigDict(populate_by_name=True, validate_assignment=True, protected_namespaces=()) ``` #### Secret.to\_str [#secretto_str] ```python def to_str() -> str ``` Returns the string representation of the model using alias #### Secret.to\_json [#secretto_json] ```python def to_json() -> str ``` Returns the JSON representation of the model using alias #### Secret.from\_json [#secretfrom_json] ```python @classmethod def from_json(json_str: str) -> Optional[Self] ``` Create an instance of Secret from a JSON string #### Secret.to\_dict [#secretto_dict] ```python 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. #### Secret.from\_dict [#secretfrom_dict] ```python @classmethod def from_dict(obj: Optional[Dict[str, Any]]) -> Optional[Self] ``` Create an instance of Secret from a dict # Shared errors (/docs/python-sdk/shared-errors) ## DaytonaError [#daytonaerror] ```python class DaytonaError(Exception) ``` Base of every error the SDK raises, in either namespace. The fields below are set by both namespaces' error classes (v0's and v2's); they are annotated here, without values, so code catching the root class type-checks. A bare marker instance does not carry them. **Attributes**: - `message` _str_ - `status_code` _Optional\[int\]_ - `code` _Optional\[str\]_ - `source` _Optional\[str\]_ ## DaytonaBadRequestError [#daytonabadrequesterror] ```python class DaytonaBadRequestError(DaytonaError) ``` The request was rejected as invalid (HTTP 400 and client-side validation). ## DaytonaAuthenticationError [#daytonaauthenticationerror] ```python class DaytonaAuthenticationError(DaytonaError) ``` Missing or invalid credentials (HTTP 401). ## DaytonaForbiddenError [#daytonaforbiddenerror] ```python class DaytonaForbiddenError(DaytonaError) ``` The credentials do not allow the operation (HTTP 403). ## DaytonaNotFoundError [#daytonanotfounderror] ```python class DaytonaNotFoundError(DaytonaError) ``` The resource does not exist (HTTP 404). ## DaytonaTimeoutError [#daytonatimeouterror] ```python class DaytonaTimeoutError(DaytonaError) ``` A request or wait timed out, on the server (HTTP 408) or in the client. ## DaytonaConflictError [#daytonaconflicterror] ```python class DaytonaConflictError(DaytonaError) ``` The resource's state does not allow the operation (HTTP 409). ## DaytonaGoneError [#daytonagoneerror] ```python class DaytonaGoneError(DaytonaError) ``` The resource is gone for good (HTTP 410). ## DaytonaUnprocessableEntityError [#daytonaunprocessableentityerror] ```python class DaytonaUnprocessableEntityError(DaytonaError) ``` The request was well-formed but could not be processed (HTTP 422). ## DaytonaRateLimitError [#daytonaratelimiterror] ```python class DaytonaRateLimitError(DaytonaError) ``` Too many requests, or a quota was exceeded (HTTP 429). ## DaytonaInternalServerError [#daytonainternalservererror] ```python class DaytonaInternalServerError(DaytonaError) ``` The server failed (HTTP 500). ## DaytonaServiceUnavailableError [#daytonaserviceunavailableerror] ```python class DaytonaServiceUnavailableError(DaytonaError) ``` The service is temporarily unavailable (HTTP 503). ## DaytonaConnectionError [#daytonaconnectionerror] ```python class DaytonaConnectionError(DaytonaError) ``` The API could not be reached. ## DaytonaValidationError [#daytonavalidationerror] ```python DaytonaValidationError = DaytonaBadRequestError ``` ## DaytonaAuthorizationError [#daytonaauthorizationerror] ```python DaytonaAuthorizationError = DaytonaForbiddenError ``` # Errors (/docs/python-sdk/errors) ## BuildLogInterruptedError [#buildloginterruptederror] ```python class BuildLogInterruptedError(DaytonaError) ``` Observation failed; cursor is the last successfully delivered checkpoint. A callback failure is never retried. Its cause may have partially applied application effects; persist output and cursor together before resuming. #### BuildLogInterruptedError.\_\_init\_\_ [#buildloginterruptederror__init__] ```python def __init__(message: str, *, cursor: str | None = None, code: str = 'BUILD_LOG_INTERRUPTED', status_code: int | None = None) -> None ``` ## DaytonaError [#daytonaerror] ```python class DaytonaError(_shared.DaytonaError) ``` Base class for all SDK errors. #### DaytonaError.\_\_init\_\_ [#daytonaerror__init__] ```python def __init__(message: str, *, status_code: Optional[int] = None, code: Optional[str] = None, source: Optional[str] = None, details: Optional[ErrorDetails] = None) -> None ``` ## BadRequestError [#badrequesterror] ```python class BadRequestError(DaytonaError, _shared.DaytonaBadRequestError) ``` HTTP 400. ## UnauthorizedError [#unauthorizederror] ```python class UnauthorizedError(DaytonaError, _shared.DaytonaAuthenticationError) ``` HTTP 401. ## ForbiddenError [#forbiddenerror] ```python class ForbiddenError(DaytonaError, _shared.DaytonaForbiddenError) ``` HTTP 403. ## NotFoundError [#notfounderror] ```python class NotFoundError(DaytonaError, _shared.DaytonaNotFoundError) ``` HTTP 404. ## RequestTimeoutError [#requesttimeouterror] ```python class RequestTimeoutError(DaytonaError, _shared.DaytonaTimeoutError) ``` HTTP 408. ## SandboxCreateTimeoutError [#sandboxcreatetimeouterror] ```python class SandboxCreateTimeoutError(RequestTimeoutError) ``` `create()` ran out of caller budget while the sandbox was still starting. The sandbox was created and is left running; `sandbox_id` lets the caller pick it up (`d.v2.get(sandbox_id)`) or delete it. #### SandboxCreateTimeoutError.\_\_init\_\_ [#sandboxcreatetimeouterror__init__] ```python def __init__(sandbox_id: str) -> None ``` ## DockerWaitTimeoutError [#dockerwaittimeouterror] ```python class DockerWaitTimeoutError(RequestTimeoutError) ``` `sandbox.docker.wait_until_ready()` ran out of caller budget before Docker was `ready`. `status` is the last observed Docker status (`starting`, or `deferred` while the boot has not started Docker yet), or `None` when no status answer arrived before the deadline (for example a stalled first request). #### DockerWaitTimeoutError.\_\_init\_\_ [#dockerwaittimeouterror__init__] ```python def __init__(status: Optional[DockerStatus]) -> None ``` ## ConflictError [#conflicterror] ```python class ConflictError(DaytonaError, _shared.DaytonaConflictError) ``` HTTP 409. ## DockerNotReadyError [#dockernotreadyerror] ```python class DockerNotReadyError(ConflictError) ``` `sandbox.docker.wait_until_ready()` saw Docker settle in a state that cannot become `ready`. The terminal states are `failed`, `not_present`, `disabled`, `unmanaged` and `unsupported`. `status` is the observed Docker status; its `reason` says why, and `process_id` (when set) names the process whose logs hold Docker's output. The sandbox itself stays usable. #### DockerNotReadyError.\_\_init\_\_ [#dockernotreadyerror__init__] ```python def __init__(status: DockerStatus) -> None ``` ## SandboxTerminalStateError [#sandboxterminalstateerror] ```python class SandboxTerminalStateError(ConflictError) ``` `wait_for_state()` saw the sandbox reach a terminal state before any target. `state` is the observed public sandbox state (e.g. `"destroyed"`). #### SandboxTerminalStateError.\_\_init\_\_ [#sandboxterminalstateerror__init__] ```python def __init__(sandbox_id: str, state: SandboxState, *, raw_state: Optional[str] = None) -> None ``` ## PreconditionFailedError [#preconditionfailederror] ```python class PreconditionFailedError(DaytonaError) ``` HTTP 412 — the `If-Match` revision no longer matches (network policy CAS). ## SecretAlreadyExistsError [#secretalreadyexistserror] ```python class SecretAlreadyExistsError(PreconditionFailedError) ``` A create-only secret write found an existing secret. ## GoneError [#goneerror] ```python class GoneError(DaytonaError, _shared.DaytonaGoneError) ``` HTTP 410. ## MethodNotAllowedError [#methodnotallowederror] ```python class MethodNotAllowedError(DaytonaError) ``` HTTP 405. ## PayloadTooLargeError [#payloadtoolargeerror] ```python class PayloadTooLargeError(DaytonaError) ``` HTTP 413. ## UnsupportedMediaTypeError [#unsupportedmediatypeerror] ```python class UnsupportedMediaTypeError(DaytonaError) ``` HTTP 415. ## UnprocessableEntityError [#unprocessableentityerror] ```python class UnprocessableEntityError(DaytonaError, _shared.DaytonaUnprocessableEntityError) ``` HTTP 422. ## RateLimitError [#ratelimiterror] ```python class RateLimitError(DaytonaError, _shared.DaytonaRateLimitError) ``` HTTP 429. ## LimitExceededError [#limitexceedederror] ```python class LimitExceededError(RateLimitError) ``` `LIMIT_EXCEEDED` (429): an organization limit is exhausted. Subclasses `RateLimitError`, so `except RateLimitError` keeps matching; `limit` is the limit's stable machine name (e.g. `max_concurrent_sandboxes`) and `current`/`max` are the counts the refusal was computed from. Attributes are `None` when a body omits or malforms them. ## ImageTooLargeError [#imagetoolargeerror] ```python class ImageTooLargeError(ConflictError) ``` ## SnapshotTooLargeError [#snapshottoolargeerror] ```python class SnapshotTooLargeError(ConflictError) ``` ## PreconditionRequiredError [#preconditionrequirederror] ```python class PreconditionRequiredError(DaytonaError) ``` ## ServiceUnavailableError [#serviceunavailableerror] ```python class ServiceUnavailableError(DaytonaError, _shared.DaytonaServiceUnavailableError) ``` HTTP 503. ## InternalServerError [#internalservererror] ```python class InternalServerError(DaytonaError, _shared.DaytonaInternalServerError) ``` HTTP 5xx. ## NotSupportedError [#notsupportederror] ```python class NotSupportedError(InternalServerError) ``` ## ConnectionError [#connectionerror] ```python class ConnectionError(DaytonaError, _shared.DaytonaConnectionError) ``` Network connection failure. ## ClientTimeoutError [#clienttimeouterror] ```python class ClientTimeoutError(DaytonaError, _shared.DaytonaTimeoutError) ``` Client-side transport timeout. ## TransferCancelledError [#transfercancellederror] ```python class TransferCancelledError(DaytonaError) ``` A local file transfer was cancelled before completion. ## SandboxCreateRequestTimeoutError [#sandboxcreaterequesttimeouterror] ```python class SandboxCreateRequestTimeoutError(ClientTimeoutError) ``` The `create()` request itself timed out before the server answered. The server may still have created the sandbox. `idempotency_key` is the key the request was sent with. Retry with that key and the identical source and create arguments, in the same project and API endpoint, to recover the sandbox (or create it if the first request never landed). Always retry with identical arguments: a changed request may be rejected or return the originally created sandbox. #### SandboxCreateRequestTimeoutError.\_\_init\_\_ [#sandboxcreaterequesttimeouterror__init__] ```python def __init__(idempotency_key: str) -> None ``` ## SandboxCreateConnectionError [#sandboxcreateconnectionerror] ```python class SandboxCreateConnectionError(ConnectionError) ``` The connection failed while the `create()` request was in flight. Same outcome as `SandboxCreateRequestTimeoutError`: the sandbox may or may not exist; retry `create()` with the same `idempotency_key`, source and create arguments, in the same project and API endpoint. #### SandboxCreateConnectionError.\_\_init\_\_ [#sandboxcreateconnectionerror__init__] ```python def __init__(idempotency_key: str, detail: str) -> None ``` ## ProcessNotFoundError [#processnotfounderror] ```python class ProcessNotFoundError(NotFoundError) ``` PROCESS_NOT_FOUND. ## ProcessStartFailedError [#processstartfailederror] ```python class ProcessStartFailedError(BadRequestError) ``` PROCESS_START_FAILED. ## ProcessTerminalError [#processterminalerror] ```python class ProcessTerminalError(ConflictError) ``` PROCESS_TERMINAL. ## ProcessExecutionTimeoutError [#processexecutiontimeouterror] ```python class ProcessExecutionTimeoutError(RequestTimeoutError) ``` PROCESS_EXECUTION_TIMEOUT. ## NameConflictError [#nameconflicterror] ```python class NameConflictError(ConflictError) ``` NAME_CONFLICT. ## InvalidCursorError [#invalidcursorerror] ```python class InvalidCursorError(BadRequestError) ``` INVALID_CURSOR. ## CursorExpiredError [#cursorexpirederror] ```python class CursorExpiredError(ConflictError) ``` CURSOR_EXPIRED. ## StdinClosedError [#stdinclosederror] ```python class StdinClosedError(ConflictError) ``` STDIN_CLOSED. ## StdinUnavailableError [#stdinunavailableerror] ```python class StdinUnavailableError(ConflictError) ``` STDIN_UNAVAILABLE. ## ProtectedProcessError [#protectedprocesserror] ```python class ProtectedProcessError(ForbiddenError) ``` PROTECTED_PROCESS. ## UnsupportedOperationError [#unsupportedoperationerror] ```python class UnsupportedOperationError(BadRequestError) ``` UNSUPPORTED_OPERATION. ## SessionNotFoundError [#sessionnotfounderror] ```python class SessionNotFoundError(NotFoundError) ``` SESSION_NOT_FOUND. ## SessionEndedError [#sessionendederror] ```python class SessionEndedError(GoneError) ``` SESSION_ENDED. ## KernelUnavailableError [#kernelunavailableerror] ```python class KernelUnavailableError(ServiceUnavailableError) ``` KERNEL_UNAVAILABLE. ## LspServerUnavailableError [#lspserverunavailableerror] ```python class LspServerUnavailableError(ServiceUnavailableError) ``` LSP_SERVER_UNAVAILABLE. ## LspNotStartedError [#lspnotstartederror] ```python class LspNotStartedError(ConflictError) ``` LSP_NOT_STARTED. ## AddonUnavailableError [#addonunavailableerror] ```python class AddonUnavailableError(ServiceUnavailableError) ``` ADDON_UNAVAILABLE. ## FileNotFoundError [#filenotfounderror] ```python class FileNotFoundError(NotFoundError) ``` FILE_NOT_FOUND. ## InvalidFilePathError [#invalidfilepatherror] ```python class InvalidFilePathError(BadRequestError) ``` INVALID_FILE_PATH. ## FileAccessDeniedError [#fileaccessdeniederror] ```python class FileAccessDeniedError(ForbiddenError) ``` FILE_ACCESS_DENIED. ## FileReadFailedError [#filereadfailederror] ```python class FileReadFailedError(InternalServerError) ``` FILE_READ_FAILED. ## GitAuthFailedError [#gitauthfailederror] ```python class GitAuthFailedError(UnauthorizedError) ``` GIT_AUTH_FAILED. ## GitRepoNotFoundError [#gitreponotfounderror] ```python class GitRepoNotFoundError(NotFoundError) ``` GIT_REPO_NOT_FOUND. ## GitBranchNotFoundError [#gitbranchnotfounderror] ```python class GitBranchNotFoundError(NotFoundError) ``` GIT_BRANCH_NOT_FOUND. ## GitBranchExistsError [#gitbranchexistserror] ```python class GitBranchExistsError(ConflictError) ``` GIT_BRANCH_EXISTS. ## DesktopNotReadyError [#desktopnotreadyerror] ```python class DesktopNotReadyError(ConflictError) ``` DESKTOP_NOT_READY. ## AtomicUploadUnsupportedError [#atomicuploadunsupportederror] ```python class AtomicUploadUnsupportedError(ConflictError) ``` ATOMIC_UPLOAD_UNSUPPORTED. ## OrgSuspendedError [#orgsuspendederror] ```python class OrgSuspendedError(DaytonaError) ``` ## ProjectBudgetExceededError [#projectbudgetexceedederror] ```python class ProjectBudgetExceededError(DaytonaError) ``` PROJECT_BUDGET_EXCEEDED (402): the project reached its monthly budget. New sandboxes cannot start in the project until the budget is raised or removed, or the next calendar month (UTC) begins. ## RateLimitedError [#ratelimitederror] ```python class RateLimitedError(RateLimitError) ``` ## OverloadedError [#overloadederror] ```python class OverloadedError(RateLimitError) ``` ## NotSupportedForClassError [#notsupportedforclasserror] ```python class NotSupportedForClassError(ConflictError) ``` ## FeatureNotEnabledError [#featurenotenablederror] ```python class FeatureNotEnabledError(ForbiddenError) ``` ## UnsupportedVolumeTypeError [#unsupportedvolumetypeerror] ```python class UnsupportedVolumeTypeError(BadRequestError) ``` ## BucketCreateFailedError [#bucketcreatefailederror] ```python class BucketCreateFailedError(InternalServerError) ``` ## BucketDeleteFailedError [#bucketdeletefailederror] ```python class BucketDeleteFailedError(InternalServerError) ``` ## BucketNotEmptyError [#bucketnotemptyerror] ```python class BucketNotEmptyError(ConflictError) ``` ## OriginImportOnlyError [#originimportonlyerror] ```python class OriginImportOnlyError(BadRequestError) ``` ## ReadOnlyUnsupportedError [#readonlyunsupportederror] ```python class ReadOnlyUnsupportedError(BadRequestError) ``` ## BillingDisabledError [#billingdisablederror] ```python class BillingDisabledError(NotSupportedError) ``` ## BillingUnreachableError [#billingunreachableerror] ```python class BillingUnreachableError(InternalServerError) ``` ## BillingUnavailableError [#billingunavailableerror] ```python class BillingUnavailableError(ServiceUnavailableError) ``` ## BillingNotProvisionedError [#billingnotprovisionederror] ```python class BillingNotProvisionedError(ConflictError) ``` ## ChargeNotFoundError [#chargenotfounderror] ```python class ChargeNotFoundError(NotFoundError) ``` ## InvoiceNotFoundError [#invoicenotfounderror] ```python class InvoiceNotFoundError(NotFoundError) ``` ## CouponNotFoundError [#couponnotfounderror] ```python class CouponNotFoundError(NotFoundError) ``` ## CouponExpiredError [#couponexpirederror] ```python class CouponExpiredError(ConflictError) ``` ## CouponLimitReachedError [#couponlimitreachederror] ```python class CouponLimitReachedError(ConflictError) ``` ## CouponAlreadyRedeemedError [#couponalreadyredeemederror] ```python class CouponAlreadyRedeemedError(ConflictError) ``` ## InvoiceNotFinalizedError [#invoicenotfinalizederror] ```python class InvoiceNotFinalizedError(ConflictError) ``` ## InvoiceNotPayableError [#invoicenotpayableerror] ```python class InvoiceNotPayableError(ConflictError) ``` ## ChargeNotSucceededError [#chargenotsucceedederror] ```python class ChargeNotSucceededError(ConflictError) ``` ## PlanUnchangedError [#planunchangederror] ```python class PlanUnchangedError(ConflictError) ``` ## PlanChangePendingError [#planchangependingerror] ```python class PlanChangePendingError(ConflictError) ``` ## PlanManagedByOperatorError [#planmanagedbyoperatorerror] ```python class PlanManagedByOperatorError(ConflictError) ``` ## PaymentMethodRequiredError [#paymentmethodrequirederror] ```python class PaymentMethodRequiredError(ConflictError) ``` ## BillingAccountConflictError [#billingaccountconflicterror] ```python class BillingAccountConflictError(ConflictError) ``` ## UnknownPlanError [#unknownplanerror] ```python class UnknownPlanError(BadRequestError) ``` ## PlanRequiresSalesError [#planrequiressaleserror] ```python class PlanRequiresSalesError(BadRequestError) ``` ## AutomaticTopUpNotAvailableError [#automatictopupnotavailableerror] ```python class AutomaticTopUpNotAvailableError(ConflictError) ``` ## SearchNotConfiguredError [#searchnotconfigurederror] ```python class SearchNotConfiguredError(NotSupportedError) ``` ## SearchUnavailableError [#searchunavailableerror] ```python class SearchUnavailableError(ServiceUnavailableError) ``` ## SandboxNotRunningError [#sandboxnotrunningerror] ```python class SandboxNotRunningError(ConflictError) ``` ## ImageNotFoundError [#imagenotfounderror] ```python class ImageNotFoundError(NotFoundError) ``` ## ImageNotReadyError [#imagenotreadyerror] ```python class ImageNotReadyError(ConflictError) ``` ## ImageFormatOutdatedError [#imageformatoutdatederror] ```python class ImageFormatOutdatedError(ConflictError) ``` `IMAGE_FORMAT_OUTDATED` (409): the image is stored in an older format than the current one (`Image.format_outdated`) and this operation cannot convert it. Convert it with `POST /images/{id}/convert`, or create a Linux sandbox from it, which converts it first. ## ImageBuildFailedError [#imagebuildfailederror] ```python class ImageBuildFailedError(ConflictError) ``` `IMAGE_BUILD_FAILED` (409), or the SDK-minted refusal when `create_from_build()`'s image build ends `failed`. `image_id` names the failed image (so its build log can be fetched) when the SDK knows it; `build_error` is the build's recorded error, when any. #### ImageBuildFailedError.\_\_init\_\_ [#imagebuildfailederror__init__] ```python def __init__(message: str, *, status_code: Optional[int] = None, code: Optional[str] = None, source: Optional[str] = None, details: Optional[ErrorDetails] = None, image_id: Optional[str] = None, build_error: Optional[str] = None) -> None ``` ## ImageClassMismatchError [#imageclassmismatcherror] ```python class ImageClassMismatchError(ConflictError) ``` ## ImageNameTakenError [#imagenametakenerror] ```python class ImageNameTakenError(ConflictError) ``` ## ImageNameReservedError [#imagenamereservederror] ```python class ImageNameReservedError(BadRequestError) ``` ## IdleOutOfRangeError [#idleoutofrangeerror] ```python class IdleOutOfRangeError(BadRequestError) ``` ## CreateTtlOutOfRangeError [#createttloutofrangeerror] ```python class CreateTtlOutOfRangeError(BadRequestError) ``` ## SnapshotNotFoundError [#snapshotnotfounderror] ```python class SnapshotNotFoundError(NotFoundError) ``` ## SnapshotNotReadyError [#snapshotnotreadyerror] ```python class SnapshotNotReadyError(ConflictError) ``` ## SnapshotClassMismatchError [#snapshotclassmismatcherror] ```python class SnapshotClassMismatchError(ConflictError) ``` ## DaytonaValidationError [#daytonavalidationerror] ```python DaytonaValidationError = BadRequestError ``` ## DaytonaAuthenticationError [#daytonaauthenticationerror] ```python DaytonaAuthenticationError = UnauthorizedError ``` ## DaytonaAuthorizationError [#daytonaauthorizationerror] ```python DaytonaAuthorizationError = ForbiddenError ``` ## DaytonaNotFoundError [#daytonanotfounderror] ```python DaytonaNotFoundError = NotFoundError ``` ## DaytonaConflictError [#daytonaconflicterror] ```python DaytonaConflictError = ConflictError ``` ## DaytonaRateLimitError [#daytonaratelimiterror] ```python DaytonaRateLimitError = RateLimitError ``` ## DaytonaTimeoutError [#daytonatimeouterror] ```python DaytonaTimeoutError = ClientTimeoutError ``` ## DaytonaConnectionError [#daytonaconnectionerror] ```python DaytonaConnectionError = ConnectionError ``` ## DaytonaNotSupportedError [#daytonanotsupportederror] ```python DaytonaNotSupportedError = NotSupportedError ``` # TypeScript SDK Reference (/docs/typescript-sdk) The Daytona TypeScript SDK provides the `Daytona` root client for interacting with Daytona Sandboxes. Every operation goes through a version namespace: `daytona.v2` for the Daytona v2 API, or `daytona.v0` for the Daytona v0 API. The root client is the only way to build a namespace client. Resource types, builders, and errors for v2 are imported from `@daytona/sdk/v2`. ## Installation [#installation] Install the Daytona TypeScript SDK using npm. The SDK ships ESM and CJS builds with type declarations, and requires Node.js 22.4 or later, or a browser environment with `WebSocket`. ```bash npm install @daytona/sdk@2.0.0-alpha.11 ``` Or using yarn: ```bash yarn add @daytona/sdk@2.0.0-alpha.11 ``` ## Getting Started [#getting-started] ### Create a Sandbox [#create-a-sandbox] Create a Daytona Sandbox to run your code securely in an isolated environment. The following snippet is an example "Hello World" program that runs securely inside a Daytona Sandbox. ```typescript import { Daytona } from '@daytona/sdk' async function main() { // Initialize the SDK (reads DAYTONA_API_KEY from the environment) const daytona = new Daytona() // Create a new sandbox const sandbox = await daytona.v2.create({ waitSeconds: 60 }) // Execute a command const result = await sandbox.exec('echo "Hello, World!"') console.log(result.output) await daytona.v2.delete(sandbox) } main().catch(console.error) ``` ## Configuration [#configuration] The Daytona SDK can be configured using environment variables or by passing a `DaytonaConfig` to the constructor. Fields left unset are read from the environment. Configure exactly one credential: `apiKey`, or `jwtToken` scoped with `projectId` for `daytona.v2` or `organizationId` for `daytona.v0`. - `apiKey`: a project API key; falls back to `DAYTONA_API_KEY` - `jwtToken`: a signed-in user's JWT, exchanged for a short-lived project-scoped token; falls back to `DAYTONA_JWT_TOKEN` - `projectId`: scopes `jwtToken` to a project for `daytona.v2`; falls back to `DAYTONA_PROJECT_ID` - `organizationId`: scopes `jwtToken` to an organization for `daytona.v0`; falls back to `DAYTONA_ORGANIZATION_ID` - `requestTimeout`: per-request HTTP timeout in milliseconds for `daytona.v2` - `connectionPoolMaxsize`: keep-alive socket pool size for `daytona.v2` requests in Node.js - `otelEnabled`: runs each SDK HTTP request in a client span; falls back to `DAYTONA_OTEL_ENABLED` `DaytonaConfig` has no API URL or region field, and the root rejects `apiUrl`. Pass `region` to each `daytona.v2` create. `DAYTONA_V2_API_URL`, else `DAYTONA_API_URL`, overrides the `daytona.v2` API endpoint; `daytona.v0` ignores both. The `target` field is deprecated and applies only to `daytona.v0`. ```typescript import { Daytona } from '@daytona/sdk' // Using environment variables (DAYTONA_API_KEY) const daytona = new Daytona() // Using explicit configuration const daytonaWithConfig = new Daytona({ apiKey: 'YOUR_API_KEY', requestTimeout: 30_000, }) const sandbox = await daytonaWithConfig.v2.create({ region: 'us' }) ``` `await daytona.close()` releases the client's connections at once. Closing is optional: in Node.js an idle connection does not keep the process alive. For more information on configuring the Daytona SDK, see [authentication](/docs/authentication). See the [`DaytonaConfig` reference](/docs/typescript-sdk/daytona#daytonaconfig) for details. ## Runtime support [#runtime-support] In Node.js builds, the `daytona.v0` namespace loads on first access, and code that only uses `daytona.v2` never loads it. A browser bundle of the root client includes the v0 SDK, because the root is the only way to build a client. `uploadFile()` and `downloadFile()` stream between the local disk and the sandbox, and are available only in Node.js; in a browser they throw `NotSupportedError`. `daytona.v0` operations that use Node.js APIs, such as file transfers, need Node.js polyfills in a browser bundle, for example [`vite-plugin-node-polyfills`](https://www.npmjs.com/package/vite-plugin-node-polyfills) for `Buffer`, `process`, and `global`. # Daytona (/docs/typescript-sdk/daytona) ## Daytona [#daytona] ### Constructors [#constructors] #### Constructor [#constructor] ```ts new Daytona(config: DaytonaConfig = {}, internal: InternalOptions = {}): Daytona; ``` **Parameters**: - `config` _DaytonaConfig = \{\}_ - `internal` _InternalOptions = \{\}_ **Returns**: - `Daytona` ### Methods [#methods] #### \[Symbol.asyncDispose\]() [#symbolasyncdispose] ```ts [Symbol.asyncDispose](): Promise; ``` `await using daytona = new Daytona()` calls `close()` at the end of the scope. **Returns**: - `Promise` #### close() [#close] ```ts close(): Promise; ``` Close the namespace clients built so far: the v2 client (its sandbox-state events socket) and the v0 client (its event socket and, with `otelEnabled`, its OpenTelemetry SDK, through v0's `[Symbol.asyncDispose]()`). Optional for short scripts — neither keeps a Node process alive — but long-running processes should call it. Idempotent; a later `root.v0` / `root.v2` builds a fresh client. Both are closed even if one fails; the first error is re-thrown (Python parity). **Returns**: - `Promise` #### v0 [#v0] ```ts get v0(): DaytonaV0Client; ``` The v0 namespace: the v0 SDK's own `Daytona` client (the 0.x SDK bundled at a pinned release), the same instance on every access. Built on first access, which loads the v0 SDK synchronously in Node (about 100 ms, once per process); Node code that only uses `v2` never loads it. Browser builds bundle the v0 SDK statically into apps that import the root and evaluate it when the root loads, so `daytona.v0` works there too. A failed load is not cached: the next access retries. **Returns**: - `DaytonaV0Client` #### v2 [#v2] ```ts get v2(): DaytonaV2Client; ``` **Returns**: - `DaytonaV2Client` *** ## DaytonaV2Client [#daytonav2client] **Properties**: - `images` _ImagesService_ - `snapshots` _SnapshotsService_ - `volume` _VolumeService_ - `secret` _SecretService_ - `reservations` _ReservationsService_ - `macModels` _MacModelsService_ - The Mac model registry that `reservations.create({ model })` draws from. ### Methods [#methods-1] #### close() [#close-1] ```ts close(): Promise; ``` **Returns**: - `Promise` #### create() [#create] ```ts create(): Promise; ``` Create a Linux sandbox from a registered image name or `img_…` id. Omitting the image (`create()` or `create(options)`) boots the platform default image, the Linux image Daytona marks as default (`images.list({ platform: 'true' })` shows it with `default: true`). When no default is configured the create fails with `DEFAULT_IMAGE_NOT_CONFIGURED` (400). An empty or whitespace-only image is still an error, thrown before any request. When Linux sandboxes are not enabled for the organization, the API answers `403` `FEATURE_NOT_ENABLED` (thrown as `FeatureNotEnabledError`). **Returns**: - `Promise` #### create() [#create-1] ```ts create(image: string | undefined, options?: CreateSandboxOptions): Promise; ``` **Parameters**: - `image` _string \| undefined_ - `options?` _CreateSandboxOptions_ **Returns**: - `Promise` #### create() [#create-2] ```ts create(options: CreateSandboxOptions): Promise; ``` **Parameters**: - `options` _CreateSandboxOptions_ **Returns**: - `Promise` #### createFromBuild() [#createfrombuild] ```ts createFromBuild( builder: ImageBuilder, options: CreateSandboxOptions & Omit = {}): Promise; ``` Build an anonymous image, wait for it, then create the sandbox from it. `region` selects the region for BOTH legs: a Dockerfile-built image lives in one region and can only boot there, so it is built where the sandbox will run. `BuildImageOptions.region` is therefore not accepted here — pass `region`. **Parameters**: - `builder` _ImageBuilder_ - `options` _CreateSandboxOptions & Omit\ = \{\}_ **Returns**: - `Promise` #### createFromSnapshot() [#createfromsnapshot] ```ts createFromSnapshot( snapshot: string, options: CreateSandboxFromSnapshotOptions = {}): Promise; ``` Create a sandbox from a snapshot. When Linux sandboxes are not enabled for the organization, the API answers `403` `FEATURE_NOT_ENABLED` (thrown as `FeatureNotEnabledError`). **Parameters**: - `snapshot` _string_ - `options` _CreateSandboxFromSnapshotOptions = \{\}_ **Returns**: - `Promise` #### createMacos() [#createmacos] ```ts createMacos(image: string, options: CreateMacosSandboxOptions = {}): Promise; ``` Create a macOS sandbox (`POST /sandboxes/macos`) on a Mac the organization has reserved (`daytona.reservations`), from a macOS image name. `reservation` picks the Mac reservation: omitted uses any fitting reservation of the organization in the region (or lets the organization's auto-reserve buy one), `'new'` buys a reservation of the cheapest model that fits, and a reservation id targets that reservation at claim. With no reservation to use it fails with `ConflictError` (`NO_ACTIVE_RESERVATION`, `NO_FREE_SLOT`, `MAC_DISK_FULL`, `AUTO_RESERVE_LIMIT_REACHED`, `NO_MAC_AVAILABLE`). `cpu` (cores), `memory` (GiB) and `disk` (GiB) size the sandbox; each omitted axis uses half of the claiming Mac, rounded down, on a model that runs two sandboxes, or all of it on a model that runs one. The first successful claim fixes the size, which the sandbox reports from then on. `name`, `idempotencyKey`, `waitSeconds` and `createTimeoutSeconds` behave as on `create`. `networkPolicy` sets the outbound network policy as on `create`; a sandbox with a policy runs only on a Mac that can enforce it. Creating macOS sandboxes must be enabled for the organization; otherwise the API answers `403` `FEATURE_NOT_ENABLED` (thrown as `FeatureNotEnabledError`). Find regions and their regional API endpoints with `GET /regions`; discover Mac models and prices with `macModels.catalog({ region: '' })`. To select a regional API endpoint, set `DAYTONA_V2_API_URL` before creating the client. An API that does not serve the region answers `ConflictError`; the SDK does not reroute. **Parameters**: - `image` _string_ - `options` _CreateMacosSandboxOptions = \{\}_ **Returns**: - `Promise` #### currentApiKey() [#currentapikey] ```ts currentApiKey(): Promise; ``` Describe the API key this client authenticates with: its name, masked display parts, the project and organization it acts in, its permissions, expiry and last use. The token itself is never returned. **Returns**: - `Promise` #### delete() [#delete] ```ts delete(sandbox: Sandbox | string): Promise; ``` Request deletion. Image deletion may still return 409 afterward, even after a sandbox 404 or `destroyed` state. **Parameters**: - `sandbox` _Sandbox \| string_ **Returns**: - `Promise` #### findByName() [#findbyname] ```ts findByName(name: string, options: { region?: string } = {}): Promise; ``` Find the sandbox created with `{ name }`. Uses the exact `labels.name` value every `create*({ name })` stamps. Names are not unique, so this is an array: a get-or-create caller takes `[0]` when it is non-empty and calls `create(image, { 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. The lookup goes through sandbox search, where a new sandbox appears shortly after its create, and a deployment without search answers `SearchNotConfiguredError` (501). `region` scopes the read the way it scopes a create; omit it or pass `'local'` to use the default region. **Parameters**: - `name` _string_ - `options` _\{ region?: string \} = \{\}_ **Returns**: - `Promise` #### get() [#get] ```ts get(id: string, options: SandboxConnectOptions = {}): Promise; ``` Fetch a sandbox by id. **Parameters**: - `id` _string_ - `options` _SandboxConnectOptions = \{\}_ **Returns**: - `Promise` #### getLimits() [#getlimits] ```ts getLimits(options: GetLimitsOptions = {}): Promise; ``` Return the organization's limits and current usage. A null `limit` means unlimited. With an API key the organization defaults to the key's own, looked up once and cached; with `jwtToken` authentication pass `organizationId`. The credential needs `read:limits`. Member counts (`members`) are not included: they are served to signed-in members only. **Parameters**: - `options` _GetLimitsOptions = \{\}_ **Returns**: - `Promise` #### getNetworkPolicy() [#getnetworkpolicy] ```ts getNetworkPolicy(sandbox: Sandbox | string): Promise; ``` **Parameters**: - `sandbox` _Sandbox \| string_ **Returns**: - `Promise` #### getProjectBudget() [#getprojectbudget] ```ts getProjectBudget(): Promise; ``` Return the monthly spend budget of the API key's project. An unset budget has nullable limit and period fields. The key needs `read:spending`. 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 throws `ProjectBudgetExceededError`. **Returns**: - `Promise` #### getSandboxSecrets() [#getsandboxsecrets] ```ts getSandboxSecrets(sandbox: Sandbox | string): Promise; ``` Read a sandbox's attached secret names and apply state; see `Sandbox.getSecrets`. **Parameters**: - `sandbox` _Sandbox \| string_ **Returns**: - `Promise` #### iter() [#iter] ```ts iter(options: ListSandboxesOptions = {}): AsyncIterable; ``` **Parameters**: - `options` _ListSandboxesOptions = \{\}_ **Returns**: - `AsyncIterable` #### list() [#list] ```ts list(options: ListSandboxesOptions = {}): Promise>; ``` List sandboxes as one page `{ items, nextCursor }`. With only `cursor`/`limit` this is the read-your-writes path: one page of `GET /sandboxes`, newest first. A sandbox you just created is in the result; walk further pages with `iter` or the returned cursor. Any other option — including `id`/`name` (sent as `idPrefix`/`namePrefix`), `q`, `status`, `sandboxClass`, `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` and `totalRelation` on the result. That path is **eventually consistent**: results may be briefly stale, and search spans every region. The cursor it returns is opaque, 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: a sandbox whose sort field changes between pages can be seen twice or missed. If the API reports search as unconfigured (501, `SearchNotConfiguredError` with `code === 'SEARCH_NOT_CONFIGURED'`) or search is unavailable (503, `SearchUnavailableError` with `code === 'SEARCH_UNAVAILABLE'`), drop the search options to fall back to the `GET /sandboxes` path. **Parameters**: - `options` _ListSandboxesOptions = \{\}_ **Returns**: - `Promise>` #### listAuditActions() [#listauditactions] ```ts listAuditActions(): Promise; ``` Return the actions the audit log can record for each target type. **Returns**: - `Promise` #### pause() [#pause] ```ts pause( sandbox: Sandbox | string, options: { readonly timeout?: number } = {}): Promise; ``` **Parameters**: - `sandbox` _Sandbox \| string_ - `options` _\{ readonly timeout?: number \} = \{\}_ **Returns**: - `Promise` #### replaceSandboxSecrets() [#replacesandboxsecrets] ```ts replaceSandboxSecrets( sandbox: Sandbox | string, secrets: readonly string[], options: { ifMatch: string }): Promise; ``` Replace a sandbox's attached secret names; see `Sandbox.replaceSecrets`. **Parameters**: - `sandbox` _Sandbox \| string_ - `secrets` _readonly string\[\]_ - `options` _\{ ifMatch: string \}_ **Returns**: - `Promise` #### resetNetworkPolicy() [#resetnetworkpolicy] ```ts resetNetworkPolicy( sandbox: Sandbox | string, options: { ifMatch: string }): Promise; ``` **Parameters**: - `sandbox` _Sandbox \| string_ - `options` _\{ ifMatch: string \}_ **Returns**: - `Promise` #### resume() [#resume] ```ts resume( sandbox: Sandbox | string, options: { readonly timeout?: number } = {}): Promise; ``` **Parameters**: - `sandbox` _Sandbox \| string_ - `options` _\{ readonly timeout?: number \} = \{\}_ **Returns**: - `Promise` #### search() [#search] ```ts search(options: SearchSandboxesOptions = {}): Promise>; ``` Search sandboxes across every region (`GET /sandboxes/search`). Every option is optional and they combine as AND. `q` is free text over name and image (or an exact id); `namePrefix`/`idPrefix` are the server-side form of `list({ name })`/`list({ id })`; `status`, `sandboxClass` 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*` bounds are inclusive, the `*StartAt` timestamp bounds are inclusive and the `*EndAt` bounds are exclusive, timestamps as RFC 3339 strings or `Date` objects (a `Date` is serialized in UTC — a whole day is `createdStartAt` that day and `createdEndAt` the next). `sort` defaults to `created_at` and `order` to `desc`; `limit` is clamped to 1..200 by the server. Resolves to a `SearchResult` whose `items` are the same `Sandbox` handles `list` returns. Consistency: search is **eventually consistent**. A create, update or delete may not appear immediately, 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. Cursor: `nextCursor` 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: a sandbox whose sort field (`status`, `name`, `memory_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`/`sandboxClass`/`sort` value, a non-object `labels` or a `min` above its `max`; 501 (`SearchNotConfiguredError` with `code === 'SEARCH_NOT_CONFIGURED'`) when search is not configured; 503 (`SearchUnavailableError` with `code === 'SEARCH_UNAVAILABLE'`) when search is unavailable. The error body is the unified envelope `{ code, message, source, trace_id }` — the class is dispatched from `(source, code)`. On 501/503 callers may fall back to `list` without search options. **Parameters**: - `options` _SearchSandboxesOptions = \{\}_ **Returns**: - `Promise>` #### start() [#start] ```ts start( sandbox: Sandbox | string, options: { readonly timeout?: number } = {}): Promise; ``` **Parameters**: - `sandbox` _Sandbox \| string_ - `options` _\{ readonly timeout?: number \} = \{\}_ **Returns**: - `Promise` #### stop() [#stop] ```ts stop(sandbox: Sandbox | string): Promise; ``` **Parameters**: - `sandbox` _Sandbox \| string_ **Returns**: - `Promise` #### updateNetworkPolicy() [#updatenetworkpolicy] ```ts updateNetworkPolicy( sandbox: Sandbox | string, networkPolicy: NetworkPolicyInput, options: { ifMatch: string }): Promise; ``` **Parameters**: - `sandbox` _Sandbox \| string_ - `networkPolicy` _NetworkPolicyInput_ - `options` _\{ ifMatch: string \}_ **Returns**: - `Promise` *** ## idempotencyKeyForName [#idempotencykeyforname] ```ts function idempotencyKeyForName(name: string): Promise; ``` The idempotency key `create*({ 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 Python SDK: use it to recover or inspect the key behind a named create made with either SDK. *** ## DaytonaV0Client [#daytonav0client] ```ts type DaytonaV0Client = InstanceType ``` The v0 SDK's own `Daytona` instance type: what `daytona.v0` returns. The bundle exports the class under the private `RootOnlyClientV0`, read only here because SDK 2.x builds a v0 client only through the root. *** ## DaytonaConfig [#daytonaconfig] ```ts type DaytonaConfig = { readonly apiKey?: string readonly jwtToken?: string /** v0 only: scopes a JWT to an organization. */ readonly organizationId?: string /** * The v0 client's default region (`v2` takes a per-create `region`). * @deprecated Applies only to the v0 namespace. Pass `target` per v0 sandbox * create (`d.v0.create({ target })`) or `regionId` per v0 snapshot create * instead. Setting it still works and emits a runtime deprecation warning. */ readonly target?: string /** v2 only: scopes a JWT to a project. */ readonly projectId?: string /** v2 only. */ readonly requestTimeout?: number /** Both namespaces. */ readonly otelEnabled?: boolean /** v2 only. */ readonly otelApi?: OtelApiLike /** v2 only (v0 at the pinned release has no pool-size setting). */ readonly connectionPoolMaxsize?: number /** v2 only: share the sandbox-state events hub with matching clients (default `true`). */ readonly sharedHub?: boolean /** v2 only: sandbox-state events hub settings (`SandboxEventsConfig` from `@daytona/sdk/v2`). */ readonly events?: SandboxEventsConfig } ``` Configuration shared by both namespaces. Routing per field (also `ROOT_CONFIG_ROUTING`): `apiKey`, `jwtToken`, `otelEnabled` reach v0 and v2; `organizationId` and the deprecated `target` are v0-only; `projectId`, `requestTimeout`, `otelApi`, `connectionPoolMaxsize`, `sharedHub` and `events` are v2-only. **Properties**: - `apiKey?` _string_ - `jwtToken?` _string_ - `organizationId?` _string_ - v0 only: scopes a JWT to an organization. - `target?` _string_ - The v0 client's default region (`v2` takes a per-create `region`). - `projectId?` _string_ - v2 only: scopes a JWT to a project. - `requestTimeout?` _number_ - v2 only. - `otelEnabled?` _boolean_ - Both namespaces. - `otelApi?` _OtelApiLike_ - v2 only. - `connectionPoolMaxsize?` _number_ - v2 only (v0 at the pinned release has no pool-size setting). - `sharedHub?` _boolean_ - v2 only: share the sandbox-state events hub with matching clients (default `true`). - `events?` _SandboxEventsConfig_ - v2 only: sandbox-state events hub settings (`SandboxEventsConfig` from `@daytona/sdk/v2`). *** ## OtelApiLike [#otelapilike] Structural subset of `@opentelemetry/api` the SDK uses. Pass your app's `import * as otel from '@opentelemetry/api'` as `otelApi` to skip the SDK's own module resolution (required in bundled browser apps). **Properties**: - `trace` _\{ getTracer(name: string, version: string): OtelTracerLike; setSpan(context: OtelContextLike, span: OtelSpanLike): OtelContextLike \}_ - `context` _\{ active(): OtelContextLike \}_ - `propagation` _\{ inject(context: OtelContextLike, carrier: OtelCarrier): void \}_ - `SpanKind` _\{ readonly CLIENT: number \}_ - `SpanStatusCode` _\{ readonly OK: number; readonly ERROR: number \}_ *** ## Resources [#resources] Sandbox resources; CPU is cores (1 core = 2 vCPUs), memory and disk are GiB. `cpu`/`memory`/`disk` are the request: what is reserved and billed as a floor. `cpuMax`/`memoryMax`/`diskMax` 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. **Properties**: - `cpu?` _number_ - CPU request in cores (1 core = 2 vCPUs), fractional allowed. - `cpuMax?` _number_ - CPU limit in cores, a multiple of 0.5: the sandbox boots `cpuMax * 2` vCPUs. - `memory?` _number_ - Memory in GiB. - `memoryMax?` _number_ - Memory limit in GiB. - `disk?` _number_ - Scratch disk in GiB. - `diskMax?` _number_ - Scratch disk limit in GiB. *** ## SnapshotKind [#snapshotkind] ```ts type SnapshotKind = (typeof API_SNAPSHOT_KINDS)[number] | 'unknown' ``` *** ## SnapshotRef [#snapshotref] **Properties**: - `id` _string_ - `name` _string \| null_ *** ## CreateRequestBaseOptions [#createrequestbaseoptions] **Properties**: - `name?` _string_ - `labels?` _Record\_ - `ports?` _PortMapping\[\]_ - `lifecyclePolicy?` _LifecyclePolicyOptions \| null_ - `null` is accepted and means "no policy", exactly like omitting the key — a JSON config round-trip produces it, and the Python SDK's `None` (the same argument in the same position) already reads that way. - `cpuArch?` _CpuArch_ - `cpuType?` _string_ - `region?` _string_ - Region selector for this create request. - `waitSeconds?` _number_ - `createTimeoutSeconds?` _number_ - `idempotencyKey?` _string_ - Identifies this create to the server: a second `create()` with the same key and request (in the same project and API endpoint) returns the sandbox the first one made instead of a new one, so a create whose response was lost can be retried safely. Reusing a key with changed parameters can return `ConflictError`. Reuse the same parameters when retrying and use a fresh key for a different sandbox. A retried create returns no fresh access token; the project API key manages the sandbox as usual. When omitted the SDK mints a random key per call and reports it on `SandboxCreateRequestTimeoutError` / `SandboxCreateConnectionError` if the request itself fails before the server answers. The key is sent verbatim; the server rejects a blank key, a key longer than 256 characters, or one with characters outside printable ASCII with `400 BAD_REQUEST` (it travels as an HTTP header). *** ## CreateSandboxOptions [#createsandboxoptions] Options for `Daytona.create`. **Visible resources.** Burstable sandboxes expose the burst ceiling (`resources.cpuMax` / `memoryMax`, 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. **Properties**: - `name?` _string_ - `labels?` _Record\_ - `ports?` _PortMapping\[\]_ - `lifecyclePolicy?` _LifecyclePolicyOptions \| null_ - `null` is accepted and means "no policy", exactly like omitting the key — a JSON config round-trip produces it, and the Python SDK's `None` (the same argument in the same position) already reads that way. - `cpuArch?` _CpuArch_ - `cpuType?` _string_ - `region?` _string_ - Region selector for this create request. - `waitSeconds?` _number_ - `createTimeoutSeconds?` _number_ - `idempotencyKey?` _string_ - Identifies this create to the server: a second `create()` with the same key and request (in the same project and API endpoint) returns the sandbox the first one made instead of a new one, so a create whose response was lost can be retried safely. Reusing a key with changed parameters can return `ConflictError`. Reuse the same parameters when retrying and use a fresh key for a different sandbox. A retried create returns no fresh access token; the project API key manages the sandbox as usual. When omitted the SDK mints a random key per call and reports it on `SandboxCreateRequestTimeoutError` / `SandboxCreateConnectionError` if the request itself fails before the server answers. The key is sent verbatim; the server rejects a blank key, a key longer than 256 characters, or one with characters outside printable ASCII with `400 BAD_REQUEST` (it travels as an HTTP header). - `volumes?` _VolumeMount\[\]_ - `env?` _Record\_ - `envVars?` _Record\_ - `resources?` _Resources_ - `cpu?` _number_ - `memory?` _number_ - `disk?` _number_ - `secrets?` _string\[\]_ - `spot?` _boolean_ - `user?` _string_ - `networkPolicy?` _NetworkPolicyInput \| null_ *** ## LifecycleAction [#lifecycleaction] ```ts type LifecycleAction = 'stop' | 'pause' | 'delete' ``` The action a lifecycle trigger fires: `onTimeout` / `onIdleTimeout`. `delete` is available for every sandbox; `stop` requires a persistent macOS sandbox. Pause a macOS sandbox with its explicit `pause()` operation. *** ## CreateSandboxFromSnapshotOptions [#createsandboxfromsnapshotoptions] **Properties**: - `name?` _string_ - `labels?` _Record\_ - `ports?` _PortMapping\[\]_ - `lifecyclePolicy?` _LifecyclePolicyOptions \| null_ - `null` is accepted and means "no policy", exactly like omitting the key — a JSON config round-trip produces it, and the Python SDK's `None` (the same argument in the same position) already reads that way. - `cpuArch?` _CpuArch_ - `cpuType?` _string_ - `region?` _string_ - Region selector for this create request. - `waitSeconds?` _number_ - `createTimeoutSeconds?` _number_ - `idempotencyKey?` _string_ - Identifies this create to the server: a second `create()` with the same key and request (in the same project and API endpoint) returns the sandbox the first one made instead of a new one, so a create whose response was lost can be retried safely. Reusing a key with changed parameters can return `ConflictError`. Reuse the same parameters when retrying and use a fresh key for a different sandbox. A retried create returns no fresh access token; the project API key manages the sandbox as usual. When omitted the SDK mints a random key per call and reports it on `SandboxCreateRequestTimeoutError` / `SandboxCreateConnectionError` if the request itself fails before the server answers. The key is sent verbatim; the server rejects a blank key, a key longer than 256 characters, or one with characters outside printable ASCII with `400 BAD_REQUEST` (it travels as an HTTP header). *** ## LifecyclePolicyOptions [#lifecyclepolicyoptions] Per-sandbox lifecycle policy: a wall-clock timeout and an idle timeout, each paired with the action it fires. `timeoutSeconds` (`>= 1`, never disabled) fires `onTimeout` after that many seconds after create, after an `updateLifecyclePolicy()` that supplies it, and again after every accepted transition to running (start or resume) — the full budget re-arms each time. Omitted `onTimeout` uses the server's default for the sandbox class and persistence. `idleExpirySeconds` is opt-in and fires `onIdleTimeout` after that many seconds without activity; `DISABLED` clears it. `onIdleTimeout` has no default — arming `idleExpirySeconds` from nothing requires it. At Linux create, each field you omit is inherited first from the project's lifecycle defaults (set in the dashboard's project settings), then — for `timeoutSeconds` only — from the platform default timeout when enabled. macOS uses platform defaults, not project lifecycle defaults. An action follows its own interval: a `timeoutSeconds` you pass without `onTimeout` gets the class default, not the project's action. Pass `DISABLED` as `idleExpirySeconds` to opt out of an inherited idle timeout. Project defaults apply to new sandboxes only; `updateLifecyclePolicy()` never consults them. Rejected before posting when inapplicable to the sandbox class: see `LifecycleAction` for the supported actions. **Properties**: - `timeoutSeconds?` _number_ - `onTimeout?` _LifecycleAction_ - `idleExpirySeconds?` _number_ - `onIdleTimeout?` _LifecycleAction_ *** ## SandboxConnectOptions [#sandboxconnectoptions] **Properties**: - `toolboxUrl?` _string_ - Toolbox URL already scoped to this sandbox. The SDK sends this sandbox's toolbox credential there (the API key, a project token, or a minted sandbox token), so pass only a URL you trust — never one read from stored or user-supplied data. Omit it to use the URL the API returns. - `accessToken?` _string_ - Token override for this sandbox's toolbox requests. A caller-supplied token is used verbatim and never silently replaced: its expiry surfaces as a 401. Without one, a handle with a project API key mints and refreshes short-lived sandbox access tokens transparently. - `autoDelete?` _boolean_ - Auto-delete when disposed with `await using`; defaults to false. *** ## ListResult [#listresult] **Properties**: - `items` _T\[\]_ - `nextCursor?` _string_ - `total?` _number_ - Only set for search results (`Daytona.list()` with a search filter). - `totalRelation?` _SearchTotalRelation_ - `'eq'` when `total` is exact, `'gte'` when it is a lower bound; only set with `total`. - `rawTotalRelation?` _string_ *** ## NetworkPolicyInput [#networkpolicyinput] **Properties**: - `blockAll?` _boolean \| null_ - `allowCidrs?` _string\[\]_ - `allowDomains?` _string\[\] \| null_ *** ## NetworkPolicy [#networkpolicy] **Properties**: - `version` _number_ - `blockAll` _boolean_ - `allowCidrs` _string\[\]_ - `allowDomains` _string\[\] \| null_ *** ## NetworkPolicyInfo [#networkpolicyinfo] **Properties**: - `desired?` _NetworkPolicy_ - `desiredRevision` _number_ - `etag` _string_ - `httpStatus` _number_ - `applied?` _NetworkPolicy_ - `appliedRevision?` _number_ - `appliedStartId?` _string_ - `status?` _string_ - `error?` _string_ *** ## CpuArch [#cpuarch] ```ts type CpuArch = 'amd64' | 'arm64' ``` *** ## CpuTypeInfo [#cputypeinfo] **Properties**: - `id` _string_ - `name` _string_ - `cpuArch` _CpuArch_ *** ## AuditActionList [#auditactionlist] ```ts type AuditActionList = api.AuditActionList ``` *** ## AuditActionGroup [#auditactiongroup] ```ts type AuditActionGroup = api.AuditActionGroup ``` *** ## ProjectApiKeyWithContext [#projectapikeywithcontext] ```ts type ProjectApiKeyWithContext = api.ProjectApiKeyWithContext ``` *** ## ProjectBudget [#projectbudget] ```ts type ProjectBudget = api.ProjectBudget ``` *** ## SnapshotDetail [#snapshotdetail] ```ts type SnapshotDetail = api.Snapshot ``` `GET /snapshots/{id}` details. *** ## ListSandboxesOptions [#listsandboxesoptions] Every `Daytona.list()` option. `cursor`/`limit` alone read `GET /sandboxes`; `id`/`name` and any inherited search filter route the call to `/sandboxes/search`. **Properties**: - `q?` _string_ - Free text over name and image; also an exact match when it is a sandbox id. - `status?` _string \| readonly string\[\]_ - A single value or a list (any-of) over the API's lifecycle state names (`running`, `stopped`, ...). - `sandboxClass?` _SandboxClass \| readonly SandboxClass\[\]_ - A single value or a list (any-of). - `region?` _string \| readonly string\[\]_ - A single value or a list (any-of) over region slugs. - `imageRef?` _string_ - `imageRefPrefix?` _string_ - `labels?` _Record\_ - Containment: every listed label must match. - `spot?` _boolean_ - `forkedFrom?` _string_ - Sandboxes forked from this sandbox id. - `minCores?` _number_ - Inclusive bounds on `cores_max` (the CPU limit), in cores (1 core = 2 vCPUs). - `maxCores?` _number_ - `minMemoryMib?` _number_ - `maxMemoryMib?` _number_ - `minDiskMib?` _number_ - `maxDiskMib?` _number_ - `createdStartAt?` _SearchTimestamp_ - `createdEndAt?` _SearchTimestamp_ - `updatedStartAt?` _SearchTimestamp_ - `updatedEndAt?` _SearchTimestamp_ - `lastActivityStartAt?` _SearchTimestamp_ - `lastActivityEndAt?` _SearchTimestamp_ - `sort?` _SearchSort_ - Defaults to `created_at`. - `order?` _SearchOrder_ - Defaults to `desc`. - `cursor?` _string_ - `limit?` _number_ - `id?` _string_ - Prefix on the id. - `name?` _string_ - Prefix on the name. *** ## ListSandboxesQuery [#listsandboxesquery] ```ts type ListSandboxesQuery = ListSandboxesOptions ``` *** ## CreateMacosSandboxOptions [#createmacossandboxoptions] Options for a macOS create (`POST /sandboxes/macos`). `cpu`, `memory` and `disk` size the sandbox; omitted values use the API defaults. CPU selectors do not apply. **Extends**: `Omit` **Properties**: - `volumes?` _VolumeMount\[\]_ - Read-write disk volumes. Cannot be combined with `persistent: true`. - `env?` _Record\_ - `envVars?` _Record\_ - `secrets?` _string\[\]_ - Project secret names to attach, as on `create`. Values are write-only and restricted to each secret's allowed domains. Needs `read:secrets` permission. - `cpu?` _number_ - CPU cores, at least 4; sent as `cores`. Omitted uses the API default. - `memory?` _number_ - Memory in GiB, at least 4; sent as memory_mib. memory * 1024 must be an integer. Omitted uses the API default. - `disk?` _number_ - Disk in GiB, at least 80, including macOS; sent as disk_mib. disk * 1024 must be an integer. Omitted uses the API default. - `persistent?` _boolean_ - Preserve the sandbox's disk when stopped. Start or resume to continue; delete to remove it. At reservation end, the disk is saved as an anonymous image that can be used to create another sandbox. - `reservation?` _'new' \| (string & \{\})_ - Which Mac reservation the sandbox runs on. Omitted: any fitting reservation of the organization in the region; when none fits and the organization's auto-reserve setting allows it, the server buys a reservation. `'new'`: buy a reservation of the cheapest model that fits. Any other value is a reservation id as `reservations.list()` returns it. A reservation ID selects that reservation. Acceptance does not guarantee immediate capacity; the sandbox can wait for room or time out. - `autoRenew?` _boolean_ - Only with `reservation: 'new'`: whether the bought reservation renews itself each period. The server defaults it to the organization's auto-reserve setting. Rejected before posting otherwise. - `networkPolicy?` _NetworkPolicyInput \| null_ - Network policy, as on `create`, effective from the sandbox's first boot. Change it later with `sandbox.updateNetworkPolicy`. *** ## OrganizationLimits [#organizationlimits] ```ts type OrganizationLimits = api.OrganizationLimits ``` *** ## GetLimitsOptions [#getlimitsoptions] Options for `Daytona.getLimits`. **Properties**: - `organizationId?` _string_ - The organization to read. Defaults to the API key's organization; required when the client authenticates with `jwtToken`. *** ## DEFAULT\_V2\_API\_URL [#default_v2_api_url] ```ts const DEFAULT_V2_API_URL = 'https://api.daytona.com' ``` The default Daytona Cloud v2 API, used when neither `DAYTONA_V2_API_URL` nor `DAYTONA_API_URL` is set. These variables can select a regional API endpoint. *** ## V0\_API\_URL [#v0_api_url] ```ts const V0_API_URL = 'https://app.daytona.io/api' ``` *** ## DEFAULT\_V2\_API\_URL [#default_v2_api_url-1] ```ts export { DEFAULT_V2_API_URL as DEFAULT_V2_API_URL } ``` Alias of `DEFAULT_V2_API_URL`. *** ## NAME\_LABEL [#name_label] ```ts const NAME_LABEL = 'name' ``` The label every `create*({ name })` stamps with the name: `labels == { name, … }`. `Daytona.findByName` reads it back. *** ## DISABLED [#disabled] ```ts const DISABLED = -1 ``` Clears `LifecyclePolicyOptions.idleExpirySeconds` — and ONLY that field. `idleExpirySeconds` value space, identical at create and on `sandbox.updateLifecyclePolicy()`: omitted = unchanged / disabled (create); `DISABLED` (-1) = clear the idle pair (`onIdleTimeout` with it); `n > 0` = whole seconds, sent verbatim on the wire; a value below 60 raised to 60 server-side and read back raised; `0` and anything below -1 are rejected. `timeoutSeconds` does NOT accept it: the timeout cannot be disabled, so `timeoutSeconds` must be `>= 1` (`-1` and `0` are rejected). # Sandbox (/docs/typescript-sdk/sandbox) ## Sandbox [#sandbox] **Properties**: - `id` _string_ - `toolboxProxyUrl?` _string_ - `name?` _string_ - `image` _ImageRef \| null_ - `snapshot` _SnapshotRef \| null_ - `target?` _string_ - `labels` _Record\_ - `cpu?` _number_ - Reserved CPU (the guarantee), in cores (1 core = 2 vCPUs; a macOS core is one Mac CPU). - `cpuMax?` _number_ - CPU limit (the boot shape), in cores; undefined when the API did not report it. - `memory?` _number_ - `memoryMax?` _number_ - `disk?` _number_ - `diskMax?` _number_ - `state?` _SandboxState_ - `rawState?` _string_ - `error?` _string_ - `errorReason?` _string_ - `imageBuildId?` _string_ - `sandboxClass?` _SandboxClass_ - Undefined until fetched, and for a class this SDK does not know (calls that depend on the class then throw). - `user?` _string_ - `region?` _string_ - `persistent?` _boolean_ - macOS only: whether the sandbox preserves its disk when stopped; undefined on a handle whose metadata has not been loaded yet. - `spot?` _boolean_ - `spotEvictedAt?` _string_ - `lifecyclePolicy?` _SandboxLifecycle_ - `forkedFrom?` _string_ - `reservationId?` _string_ - macOS only: the ID of the reservation selected for this sandbox. Unset before a reservation is selected, and on search results (`search()`, a search-routed `list()`), which omit it; `refreshData()` reads it. - `accessToken?` _string_ - `accessTokenExpiresAt?` _string_ - Expiry of `accessToken` (RFC 3339), when known. Undefined for the opaque `dtnv_` create token (no known expiry) and for handles without a token. ### Constructors [#constructors] #### Constructor [#constructor] ```ts new Sandbox( sandboxOrId: SandboxDto | SandboxInfo | string, api: AxiosInstance | undefined, toolboxBaseUrl: string | undefined, apiKey: string | undefined, target?: string, options?: SandboxConnectOptions, requestTimeout?: number, httpOptions?: HttpClientOptions): Sandbox; ``` Low-level constructor; prefer `daytona.create*()`, `get(id)` or `list()`. Any toolbox URL inside `sandboxOrId` (a stored `toJSON()` blob or an API-shaped object) is ignored, so stored data never chooses where the SDK sends a credential. Pass `options.toolboxUrl` to set one explicitly — the toolbox credential (the API key, a project token, a minted sandbox token, or `options.accessToken`) goes there, so pass only a URL you trust. The third parameter, `toolboxBaseUrl`, is unused: pass the URL as `options.toolboxUrl`. **Parameters**: - `sandboxOrId` _SandboxDto \| SandboxInfo \| string_ - `api` _AxiosInstance \| undefined_ - `toolboxBaseUrl` _string \| undefined_ - `apiKey` _string \| undefined_ - `target?` _string_ - `options?` _SandboxConnectOptions_ - `requestTimeout?` _number_ - `httpOptions?` _HttpClientOptions_ **Returns**: - `Sandbox` ### Methods [#methods] #### \[Symbol.asyncDispose\]() [#symbolasyncdispose] ```ts [Symbol.asyncDispose](): Promise; ``` Dispose by deleting the sandbox when constructed with `autoDelete`. **Returns**: - `Promise` #### buildLogs() [#buildlogs] ```ts buildLogs(): Promise; ``` Return retained build output as one-shot text, not a live follower. The body includes the current build state and available output. A sandbox with no image build (for example a registry image) throws `NotFoundError`. Output can be incomplete while the build is in progress; truncation is indicated in the text. Use followBuildLogs for live output and completeness metadata. **Returns**: - `Promise` #### computerUse [#computeruse] ```ts get computerUse(): ComputerUseService; ``` **Returns**: - `ComputerUseService` #### createAccessToken() [#createaccesstoken] ```ts createAccessToken(options: CreateAccessTokenOptions = {}): Promise; ``` Mint a scoped, short-lived access token for THIS sandbox. The token authorizes sandbox services (toolbox, SSH, desktop, private previews) and the self-service API routes, for exactly the granted operations and ports — hand it to a collaborator, a CI job, or a browser instead of a project API key. It expires at `expiresAt`, cannot be refreshed, and can never mint further credentials; mint a fresh one here instead. An unknown operation or an over-cap `ttlSeconds` is a 400, never a silent narrowing. **Parameters**: - `options` _CreateAccessTokenOptions = \{\}_ **Returns**: - `Promise` #### createSnapshot() [#createsnapshot] ```ts createSnapshot(name: string): Promise; ``` **Parameters**: - `name` _string_ **Returns**: - `Promise` #### delete() [#delete] ```ts delete(): Promise; ``` Request deletion. Returning, a `destroyed` state, or a subsequent 404 does not guarantee that the image can already be deleted. Image deletion may still return 409. **Returns**: - `Promise` #### docker [#docker] ```ts get docker(): DockerService; ``` Docker Engine status inside the sandbox; see `DockerService`. **Returns**: - `DockerService` #### entrypointLogs() [#entrypointlogs] ```ts entrypointLogs(): Promise; ``` Return the sandbox entrypoint log as plain text. **Returns**: - `Promise` #### exec() [#exec] ```ts exec(command: ProcessCommand, options: RunOptions = {}): Promise; ``` Run a command, wait for its shell to exit, and collect its output. A convenience alias for `ProcessService.run` — identical behaviour, same parameters, same return value. **Shell selection.** Passing a string runs the command through the sandbox shell: `bash` when the image has it, else `sh`. Pass `shell` to pin another interpreter, and quote globs and brackets (`pip install -e '.[test]'`) so the command means the same under any shell. Pass `{ argv: [...] }` to bypass the shell entirely, which is the safe form for untrusted arguments. Use `process.createSession()` when commands need shared shell state. **Background processes.** The call returns when the shell exits. If the command launches a background child that holds its output descriptors open (e.g. `python3 -m http.server 8000 &`), execution waits at most ~2 seconds for output to drain and then returns; output the child writes later is not part of the result. For a long-running server use `ProcessService.start`, which returns a `ProcessHandle` immediately (logs, wait, kill). Alternatively redirect: `nohup cmd > server.log 2>&1 &`. **Parameters**: - `command` _ProcessCommand_ - Shell command string, or `{ argv }` for shell-free execution. - `options` _RunOptions = \{\}_ **Returns**: - `Promise` #### followBuildLogs() [#followbuildlogs] ```ts followBuildLogs(options: BuildLogFollowOptions): Promise; ``` Observe this sandbox's build without changing its execution lifetime. Discovery failures, including a 404 for a sandbox with no image build, throw BuildLogInterruptedError with the HTTP status and last cursor. They do not fall back to another log source. **Parameters**: - `options` _BuildLogFollowOptions_ **Returns**: - `Promise` #### fork() [#fork] ```ts fork( options: { name?: string; memory?: boolean; timeout?: number } = {}): Promise; ``` Fork this sandbox and return the fork handle. By default the fork continues from the source's memory (running processes included). `memory: false` copies only the disk, after which the fork boots fresh. A stopped sandbox is always forked disk-only. Only a fork of a RUNNING sandbox is started automatically; a fork of a paused source rests `paused` (memory fork, call `resume()`) or `stopped` (`memory: false`), and a fork of a stopped source rests `stopped` — call `start()` on those. A macOS fork copies the disk only: omit `memory` or pass `memory: false` (`memory: true` is refused with `NOT_SUPPORTED_FOR_CLASS`). A fork of a running macOS sandbox boots with a fresh machine identity; a fork of a paused or stopped one rests `stopped`. The fork may wait for capacity, as a create does; insufficient capacity can return `NO_FREE_SLOT`. **Parameters**: - `options` _\{ name?: string; memory?: boolean; timeout?: number \} = \{\}_ **Returns**: - `Promise` #### fs [#fs] ```ts get fs(): FileSystemService; ``` **Returns**: - `FileSystemService` #### getNetworkPolicy() [#getnetworkpolicy] ```ts getNetworkPolicy(): Promise; ``` **Returns**: - `Promise` #### getSecrets() [#getsecrets] ```ts getSecrets(): Promise; ``` Read this sandbox's attached secret names and their apply state (`GET /sandboxes/{id}/secrets`). Returns names and revisions only, never values. `etag` is the `ifMatch` value for `replaceSecrets`; `status` is `pending` until the sandbox has applied `desiredRevision`. **Returns**: - `Promise` #### git [#git] ```ts get git(): GitService; ``` **Returns**: - `GitService` #### interpreter [#interpreter] ```ts get interpreter(): InterpreterService; ``` **Returns**: - `InterpreterService` #### lsp [#lsp] ```ts get lsp(): LspService; ``` **Returns**: - `LspService` #### macBootMode [#macbootmode] ```ts get macBootMode(): MacBootMode | null; ``` macOS only: how the sandbox resumed, as reported by the API. Null for any other class and for a sandbox not resumed since it last booted. **Returns**: - `MacBootMode | null` #### metrics() [#metrics] ```ts metrics(): Promise; ``` **Returns**: - `Promise` #### pause() [#pause] ```ts pause(options: LifecycleWaitOptions = {}): Promise; ``` Pause a persistent macOS sandbox with its memory. Waits up to `timeout` for `paused` and throws `SandboxTerminalStateError` if the pause fails. A paused macOS sandbox keeps its Mac slot but does not keep its reservation renewing. **Parameters**: - `options` _LifecycleWaitOptions = \{\}_ **Returns**: - `Promise` #### ports [#ports] ```ts get ports(): PortsService; ``` **Returns**: - `PortsService` #### process [#process] ```ts get process(): ProcessService; ``` **Returns**: - `ProcessService` #### pty [#pty] ```ts get pty(): PtyService; ``` **Returns**: - `PtyService` #### refreshData() [#refreshdata] ```ts refreshData(): Promise; ``` Refresh sandbox metadata from the API. **Returns**: - `Promise` #### replaceSecrets() [#replacesecrets] ```ts replaceSecrets( secrets: readonly string[], options: { ifMatch: string }): Promise; ``` Replace the full set of project secrets attached to this sandbox (`PUT /sandboxes/{id}/secrets`). `secrets` names project secrets. `ifMatch` is the `etag` of the last read; a stale one throws `PreconditionFailedError`. The change applies asynchronously: poll `getSecrets` until `status` is `applied`. Running processes keep their environment; processes started afterwards see the new names. **Parameters**: - `secrets` _readonly string\[\]_ - `options` _\{ ifMatch: string \}_ **Returns**: - `Promise` #### resetIdleTimer() [#resetidletimer] ```ts resetIdleTimer(): Promise; ``` Reset this sandbox's idle timer: an explicit keepalive for work the platform cannot see. Bumps the sandbox's activity clock (`lastActivityAt`, attributed server-side to the `api` source), which restarts the idle countdown — `idleTimeoutAt` re-anchors to now + `idleExpirySeconds`. The wall-clock `timeoutAt` is NOT affected. Succeeds whether or not an idle timeout is armed (an unarmed sandbox echoes `idleTimeoutAt: undefined`), and in any state — a never-started sandbox already carries its creation-time activity stamp, which the reset advances. The echo is the full post-reset lifecycle, the same shape `updateLifecyclePolicy()` returns. Advance-only: a newer concurrent activity bump keeps the clock, and what comes back is the state that won. **Returns**: - `Promise` #### resetNetworkPolicy() [#resetnetworkpolicy] ```ts resetNetworkPolicy(options: { ifMatch: string }): Promise; ``` **Parameters**: - `options` _\{ ifMatch: string \}_ **Returns**: - `Promise` #### resume() [#resume] ```ts resume(options: LifecycleWaitOptions = {}): Promise; ``` Resume a paused persistent macOS sandbox and wait until it is started. A macOS resume the Mac cannot finish ends `stopped`; this then throws `SandboxTerminalStateError`. **Parameters**: - `options` _LifecycleWaitOptions = \{\}_ **Returns**: - `Promise` #### rotateSigningKey() [#rotatesigningkey] ```ts rotateSigningKey(): Promise; ``` Rotate the sandbox's signing key: every pre-signed URL minted so far stops working within ~30 s; new URLs from presignedDownloadUrl/UploadUrl use the new key. The key itself is never returned. **Returns**: - `Promise` #### runCode() [#runcode] ```ts runCode(code: string, options: InterpreterRunOptions = {}): Promise; ``` **Parameters**: - `code` _string_ - `options` _InterpreterRunOptions = \{\}_ **Returns**: - `Promise` #### setLabels() [#setlabels] ```ts setLabels(labels: Record): Promise>; ``` Replace the sandbox's full label set. Pass `{}` to clear all labels; resolves to the applied labels. **Parameters**: - `labels` _Record\_ **Returns**: - `Promise>` #### snapshotFilesystem() [#snapshotfilesystem] ```ts snapshotFilesystem(options: CaptureImageOptions = {}): Promise; ``` Snapshot this sandbox's filesystem as a new `Image` (`POST /sandboxes/{id}/images`). The result boots new sandboxes (`daytona.create(image.id)`); a Linux sandbox keeps running. A macOS sandbox must be persistent and stopped; it cannot start until the snapshot is `ready`. **Parameters**: - `options` _CaptureImageOptions = \{\}_ **Returns**: - `Promise` #### start() [#start] ```ts start(options: LifecycleWaitOptions = {}): Promise; ``` Start a stopped sandbox, or resume a paused one, and wait until it is started. **Parameters**: - `options` _LifecycleWaitOptions = \{\}_ **Returns**: - `Promise` #### stop() [#stop] ```ts stop(): Promise; ``` Stop a persistent macOS sandbox. **Returns**: - `Promise` #### toJSON() [#tojson] ```ts toJSON(): SandboxHandleJSON; ``` The sandbox's data as JSON. A snapshot, not a way back: resume a stored sandbox with `daytona.get(info.sandboxId)`. It carries no toolbox URL — where a credential goes always comes from the API or an explicit caller option, never from stored data. **Returns**: - `SandboxHandleJSON` #### updateEnv() [#updateenv] ```ts updateEnv( env: Record = {}, options: UpdateEnvOptions = {}): Promise; ``` Update the extra environment layer used by processes created after this call. **Parameters**: - `env` _Record\ = \{\}_ - `options` _UpdateEnvOptions = \{\}_ **Returns**: - `Promise` #### updateLifecyclePolicy() [#updatelifecyclepolicy] ```ts updateLifecyclePolicy(options: LifecyclePolicyOptions): Promise; ``` Update this sandbox's lifecycle policy; omitted knobs stay unchanged. `timeoutSeconds` re-anchors the deadline from now (`>= 1`; the timeout cannot be disabled). `idleExpirySeconds: DISABLED` clears the idle pair; arming it on a sandbox with no idle policy requires `onIdleTimeout`. Setting either action to `'delete'` — or touching a pair whose current or resulting action is `'delete'` — requires the API key to hold `delete:sandboxes` in addition to `write:sandboxes`. **Parameters**: - `options` _LifecyclePolicyOptions_ **Returns**: - `Promise` #### updateNetworkPolicy() [#updatenetworkpolicy] ```ts updateNetworkPolicy( networkPolicy: NetworkPolicyInput, options: { ifMatch: string }): Promise; ``` **Parameters**: - `networkPolicy` _NetworkPolicyInput_ - `options` _\{ ifMatch: string \}_ **Returns**: - `Promise` #### volumes [#volumes] ```ts get volumes(): SandboxVolumesService; ``` **Returns**: - `SandboxVolumesService` #### wait() [#wait] ```ts wait(options: WaitOptions = {}): Promise; ``` Wait for one or more public sandbox states. `timeout` is a caller wait budget in seconds. The default is 60; `0` waits without a deadline. Timeout raises `RequestTimeoutError`, and a terminal state before the target raises `SandboxTerminalStateError`. **Parameters**: - `options` _WaitOptions = \{\}_ **Returns**: - `Promise` #### waitForState() [#waitforstate] ```ts waitForState( states: readonly SandboxWaitState[], options: WaitForStateOptions = {}): Promise; ``` **Parameters**: - `states` _readonly SandboxWaitState\[\]_ - `options` _WaitForStateOptions = \{\}_ **Returns**: - `Promise` *** ## UpdateEnvOptions [#updateenvoptions] **Properties**: - `unset?` _readonly string\[\]_ *** ## SandboxEventsConfig [#sandboxeventsconfig] Configuration for the sandbox-state events hub (WebSocket-based waiting). `enabled` defaults to `true`. `reconcileIntervalMs` defaults to 60 000 (ms); `0` disables the periodic re-subscribe timer. `idleCloseMs` closes the events socket that long after its last waiter leaves; unset, the socket stays open. In Node an idle socket does not keep the process alive, so a script that never calls `daytona.close()` still exits; a runtime where the socket cannot be released that way (no `ws` package) closes it after 10 000 ms instead. `0` keeps the socket open until `close()`. **Properties**: - `enabled?` _boolean_ - Enable WebSocket-based waiting; default `true`. - `reconcileIntervalMs?` _number_ - Reconcile timer interval in ms; default 60 000; 0 disables. Values above 2 147 483 647 clamp to that maximum. - `idleCloseMs?` _number_ - Close an idle events socket after this many ms; default never (10 000 where an idle socket would keep the process alive); `0` = never. Values above 2 147 483 647 clamp to that maximum. *** ## SandboxState [#sandboxstate] ```ts type SandboxState = | 'queued' | 'creating' | 'starting' | 'started' | 'pausing' | 'stopping' | 'stopped' | 'paused' | 'destroying' | 'destroyed' | 'error' | 'unknown' ``` *** ## SandboxWaitState [#sandboxwaitstate] ```ts type SandboxWaitState = Exclude ``` *** ## SandboxClass [#sandboxclass] ```ts type SandboxClass = 'linux' | 'macos' ``` *** ## SandboxLifecycle [#sandboxlifecycle] Lifecycle policy as the API reports it. `timeoutSeconds` is the re-arm budget in seconds; `timeoutAt` is the current absolute deadline it derives. `timeoutAt`, `idleTimeoutAt`, `lastActivityAt` and `lastActivitySource` are server-derived and read-only. An action the SDK does not know yet (a newer server) is passed through as its wire string. **Properties**: - `timeoutSeconds?` _number_ - `onTimeout?` _string_ - `timeoutAt?` _string_ - `idleExpirySeconds?` _number_ - `onIdleTimeout?` _string_ - `idleTimeoutAt?` _string_ - When `onIdleTimeout` becomes eligible to fire: `lastActivityAt + idleExpirySeconds`, server-derived and read-only. Undefined when the idle pair is not armed or the sandbox has never been active. Any activity — traffic, SSH, a non-PTY process or code execution started through the process API that is still running (`exec`, `process.start`, `runCode` and interpreter cells included), or `sandbox.resetIdleTimer()` — advances `lastActivityAt` and pushes it. - `lastActivityAt?` _string_ - `lastActivitySource?` _string_ *** ## SandboxLifecycleDto [#sandboxlifecycledto] Wire shape of the lifecycle object on sandbox DTOs and the lifecycle PATCH response. **Properties**: - `timeout_seconds?` _number \| null_ - `on_timeout?` _string \| null_ - `timeout_at?` _string \| null_ - `idle_expiry_seconds?` _number \| null_ - `on_idle_timeout?` _string \| null_ - `idle_timeout_at?` _string \| null_ - `last_activity_at?` _string \| null_ - `last_activity_source?` _string \| null_ *** ## SandboxInfo [#sandboxinfo] **Properties**: - `sandboxId` _string_ - `toolboxProxyUrl?` _string_ - Internal: the create path passes the create response's toolbox URL here. `toJSON()` never writes it, and the public `Sandbox` constructor ignores it — pass `options.toolboxUrl` to set a toolbox URL explicitly. - `name?` _string_ - `image?` _ImageRef_ - `snapshot?` _SnapshotRef_ - `target?` _string_ - `cpu?` _number_ - `cpuMax?` _number_ - `memory?` _number_ - `memoryMax?` _number_ - `disk?` _number_ - `diskMax?` _number_ - `state?` _SandboxState_ - `error?` _string_ - `imageBuildId?` _string_ - `sandboxClass?` _SandboxClass_ - `labels?` _Record\_ - `region?` _string_ - `persistent?` _boolean_ - macOS only: preserve the sandbox's disk when stopped. - `spot?` _boolean_ - `spotEvictedAt?` _string_ - `lifecyclePolicy?` _SandboxLifecycle_ - `forkedFrom?` _string_ - `reservationId?` _string_ - `user?` _string_ *** ## SandboxHandleJSON [#sandboxhandlejson] ```ts type SandboxHandleJSON = SandboxInfo ``` *** ## WaitOptions [#waitoptions] **Properties**: - `until?` _SandboxWaitState \| readonly SandboxWaitState\[\]_ - `timeout?` _number_ *** ## WaitForStateOptions [#waitforstateoptions] **Properties**: - `terminalStates?` _readonly SandboxState\[\]_ - `timeout?` _number_ - Caller wait budget in milliseconds; `0` and `undefined` wait unbounded. *** ## SandboxSearchFilters [#sandboxsearchfilters] The `GET /sandboxes/search` filters shared by `Daytona.search()` and `Daytona.list()`. `status`, `sandboxClass` and `region` take a single value or a list; lists are joined with commas on the wire. `labels` is sent as a JSON object string (containment match); numeric bounds and timestamp starts are inclusive; timestamp ends are exclusive. **Properties**: - `q?` _string_ - Free text over name and image; also an exact match when it is a sandbox id. - `status?` _string \| readonly string\[\]_ - A single value or a list (any-of) over the API's lifecycle state names (`running`, `stopped`, ...). - `sandboxClass?` _SandboxClass \| readonly SandboxClass\[\]_ - A single value or a list (any-of). - `region?` _string \| readonly string\[\]_ - A single value or a list (any-of) over region slugs. - `imageRef?` _string_ - `imageRefPrefix?` _string_ - `labels?` _Record\_ - Containment: every listed label must match. - `spot?` _boolean_ - `forkedFrom?` _string_ - Sandboxes forked from this sandbox id. - `minCores?` _number_ - Inclusive bounds on `cores_max` (the CPU limit), in cores (1 core = 2 vCPUs). - `maxCores?` _number_ - `minMemoryMib?` _number_ - `maxMemoryMib?` _number_ - `minDiskMib?` _number_ - `maxDiskMib?` _number_ - `createdStartAt?` _SearchTimestamp_ - `createdEndAt?` _SearchTimestamp_ - `updatedStartAt?` _SearchTimestamp_ - `updatedEndAt?` _SearchTimestamp_ - `lastActivityStartAt?` _SearchTimestamp_ - `lastActivityEndAt?` _SearchTimestamp_ - `sort?` _SearchSort_ - Defaults to `created_at`. - `order?` _SearchOrder_ - Defaults to `desc`. *** ## SandboxSecretsInfo [#sandboxsecretsinfo] **Properties**: - `secrets` _string\[\]_ - `desiredRevision` _number_ - `etag` _string_ - `httpStatus` _number_ - `appliedRevision?` _number_ - `status?` _string_ - `error?` _string_ - `captureStatus?` _string_ - `captureUnresolvedCount?` _number_ *** ## SandboxStateSnapshot [#sandboxstatesnapshot] ```ts type SandboxStateSnapshot = api.Snapshot ``` *** ## SandboxDto [#sandboxdto] **Properties**: - `id` _string_ - `class?` _SandboxClass \| string_ - Sandbox class (`linux` | `macos`); the authoritative class when present. - `name?` _string_ - `image?` _api.ImageReference \| null_ - `status?` _string_ - `cpu?` _number_ - Reserved CPU (the guarantee), in cores (1 core = 2 vCPUs). - `cores_max?` _number \| null_ - CPU limit (the boot shape), in cores, a multiple of 0.5. - `memory_mib?` _number_ - `memory_max_mib?` _number \| null_ - `disk_mib?` _number_ - `disk_max_mib?` _number \| null_ - `error?` _string \| null_ - `labels?` _unknown_ - `spot?` _boolean \| null_ - `spot_evicted_at?` _string \| null_ - `toolboxProxyUrl?` _string_ - `toolbox_proxy_url?` _string \| null_ - `region_id?` _string_ - `image_build_id?` _string \| null_ - `user?` _string \| null_ - `snapshot?` _api.SnapshotReference \| null_ - `mac_boot_mode?` _string \| null_ - macOS only: set on the `running` that ends a resume; null otherwise. - `reservation_id?` _string \| null_ - macOS only: the reservation selected for this sandbox. `GET /sandboxes/search` items omit it. - `persistent?` _boolean \| null_ - macOS only; absent on `GET /sandboxes/batch-wait` items. - `lifecycle_policy?` _SandboxLifecycleDto \| null_ - `created_at?` _string \| null_ - Present on `GET /sandboxes/search` items; absent on the plain list. `created_at` is always set on a search item; the other timestamps and `forked_from` are `null` when the sandbox has no such event. - `updated_at?` _string \| null_ - `last_activity_at?` _string \| null_ - `started_at?` _string \| null_ - `stopped_at?` _string \| null_ - `forked_from?` _string \| null_ - `cursor?` _string_ - Per-item cursor on search results. *** ## PreviewEndpoint [#previewendpoint] **Properties**: - `port` _number_ - `public` _boolean_ - `url` _string_ - `createdAt?` _string_ *** ## PreviewLink [#previewlink] Preview URL plus an access token for one sandbox port. Send `token` in the `X-Daytona-Preview-Token` header to reach a private endpoint; without a credential the request returns 401. When `token` is a sandbox access token (a JWT) it also works as `Authorization: Bearer` or `?daytona_token=`; an opaque preview token works only in the header. Public endpoints set `token` to `''` and need no credential. For a shareable URL that works in a browser without extra headers, use `PortsService.signedPreviewLink` instead. **Example:** ```ts const link = await sandbox.ports.previewLink(8080) const response = await fetch(link.url, { headers: { 'X-Daytona-Preview-Token': link.token }, }) ``` **Properties**: - `url` _string_ - `token` _string_ - `expiresAt?` _string_ - Absent when the preview token has no readable expiry. *** ## SignedPreviewLink [#signedpreviewlink] Self-contained signed URL for one sandbox port. The token is embedded in the hostname — no extra headers or credentials are needed. The link expires at `expiresAt` (RFC 3339). Revoke it early with `PortsService.expireSignedPreviewLink`. **Properties**: - `url` _string_ - `token` _string_ - `expiresAt?` _string_ - Absent when the server response carried no expiry (parity with the Python SDK's `expires_at: Optional[str]`). *** ## CreateAccessTokenOptions [#createaccesstokenoptions] Options for `Sandbox.createAccessToken`. **Properties**: - `operations?` _readonly string\[\]_ - Requested operation subset (the sandbox-operation vocabulary: `toolbox`, `toolbox:exec`, `toolbox:fs`, `toolbox:git`, `toolbox:lsp`, `desktop`, `ssh`, `sandbox:stop`, `sandbox:pause`, `sandbox:delete`). Omitted = the minter's full grantable set; `[]` is a valid ports-only grant. Unknown operations are a 400, never a silent narrowing. - `ports?` _readonly number\[\]_ - Private-preview ports the token may reach. Omitted = all; `[]` = none. - `ttlSeconds?` _number_ - Token lifetime in seconds; omitted = the deployment default, capped server-side. *** ## SandboxAccessToken [#sandboxaccesstoken] A short-lived per-sandbox access token (`POST …/access-token`). `accessToken` is a bearer for sandbox services (toolbox, SSH, desktop, private previews) and for the self-service API routes named by `operations`. It expires at `expiresAt` (RFC 3339) and cannot be refreshed — mint a fresh one with `Sandbox.createAccessToken` instead. `ports` is the granted private-preview port set; `undefined` means every port. **Properties**: - `accessToken` _string_ - `tokenType` _string_ - `expiresAt` _string_ - `operations` _readonly string\[\]_ - `ports?` _readonly number\[\]_ *** ## SystemMetrics [#systemmetrics] **Properties**: - `timestamp` _string_ - `cpuCount` _number_ - `cpuUtilization` _number_ - `memoryUsageBytes` _number_ - `memoryTotalBytes` _number_ - `diskUsageBytes` _number_ - `diskTotalBytes` _number_ *** ## MacBootMode [#macbootmode-1] ```ts type MacBootMode = string ``` How a macOS sandbox resumed, as reported by the API. # FileSystem (/docs/typescript-sdk/file-system) ## FileSystemService [#filesystemservice] ### Constructors [#constructors] #### Constructor [#constructor] ```ts new FileSystemService( transport: HttpTransport, fileUrlSigner?: FileUrlSigner): FileSystemService; ``` **Parameters**: - `transport` _HttpTransport_ - `fileUrlSigner?` _FileUrlSigner_ **Returns**: - `FileSystemService` ### Methods [#methods] #### chmod() [#chmod] ```ts chmod(path: string, permissions: FilePermissionsOptions): Promise; ``` **Parameters**: - `path` _string_ - `permissions` _FilePermissionsOptions_ **Returns**: - `Promise` #### downloadFile() [#downloadfile] ```ts downloadFile( remotePath: string, localPath: string, options: DownloadFileOptions = {}): Promise; ``` Stream a sandbox file to disk via an exclusive random temp file in the destination directory, renaming on success. Progress callback errors are swallowed. Node.js only. **Parameters**: - `remotePath` _string_ - `localPath` _string_ - `options` _DownloadFileOptions = \{\}_ **Returns**: - `Promise` #### glob() [#glob] ```ts glob(path: string, pattern: string): Promise>; ``` Return the paths of files under `path` whose base name matches the glob `pattern`. **Parameters**: - `path` _string_ - `pattern` _string_ **Returns**: - `Promise>` #### grep() [#grep] ```ts grep(path: string, pattern: string): Promise>; ``` Search file contents under `path` for the literal substring `pattern`; returns matches with one-based line numbers. **Parameters**: - `path` _string_ - `pattern` _string_ **Returns**: - `Promise>` #### list() [#list] ```ts list(path: string, options: { depth?: number } = {}): Promise>; ``` List a directory; response always has `{items,nextCursor}`. **Parameters**: - `path` _string_ - `options` _\{ depth?: number \} = \{\}_ **Returns**: - `Promise>` #### mkdir() [#mkdir] ```ts mkdir(path: string, options: { mode?: string } = {}): Promise; ``` **Parameters**: - `path` _string_ - `options` _\{ mode?: string \} = \{\}_ **Returns**: - `Promise` #### move() [#move] ```ts move(source: string, destination: string): Promise; ``` **Parameters**: - `source` _string_ - `destination` _string_ **Returns**: - `Promise` #### presignedDownloadUrl() [#presigneddownloadurl] ```ts presignedDownloadUrl(path: string, options: PresignedUrlOptions = {}): Promise; ``` Pre-signed download URL for a sandbox file. The signature is minted by the API; `expiresInSeconds` must be between 1 and `SIGNED_FILE_MAX_TTL_SECONDS` (7 days). **Parameters**: - `path` _string_ - `options` _PresignedUrlOptions = \{\}_ **Returns**: - `Promise` #### presignedUploadUrl() [#presigneduploadurl] ```ts presignedUploadUrl(path: string, options: PresignedUrlOptions = {}): Promise; ``` Pre-signed upload URL for a sandbox file. The signature is minted by the API; `expiresInSeconds` must be between 1 and `SIGNED_FILE_MAX_TTL_SECONDS` (7 days). **Parameters**: - `path` _string_ - `options` _PresignedUrlOptions = \{\}_ **Returns**: - `Promise` #### readBytes() [#readbytes] ```ts readBytes(path: string, _options: ReadFileOptions = {}): Promise; ``` **Parameters**: - `path` _string_ - `_options` _ReadFileOptions = \{\}_ **Returns**: - `Promise` #### readMany() [#readmany] ```ts readMany( paths: readonly string[], _options: ReadManyOptions = {}): Promise; ``` **Parameters**: - `paths` _readonly string\[\]_ - `_options` _ReadManyOptions = \{\}_ **Returns**: - `Promise` #### readText() [#readtext] ```ts readText(path: string, options: ReadFileOptions = {}): Promise; ``` **Parameters**: - `path` _string_ - `options` _ReadFileOptions = \{\}_ **Returns**: - `Promise` #### remove() [#remove] ```ts remove(path: string, options: { recursive?: boolean } = {}): Promise; ``` **Parameters**: - `path` _string_ - `options` _\{ recursive?: boolean \} = \{\}_ **Returns**: - `Promise` #### replace() [#replace] ```ts replace( files: string[], pattern: string, newValue: string): Promise>; ``` **Parameters**: - `files` _string\[\]_ - `pattern` _string_ - `newValue` _string_ **Returns**: - `Promise>` #### stat() [#stat] ```ts stat(path: string): Promise; ``` **Parameters**: - `path` _string_ **Returns**: - `Promise` #### uploadFile() [#uploadfile] ```ts uploadFile( localPath: string, remotePath: string, options: UploadFileOptions = {}): Promise; ``` Stream a local file to the sandbox without buffering the full body in memory. Progress callback errors are swallowed. Node.js only. **Parameters**: - `localPath` _string_ - `remotePath` _string_ - `options` _UploadFileOptions = \{\}_ **Returns**: - `Promise` #### watchDir() [#watchdir] ```ts watchDir( path: string, onEvent: (event: FilesystemEvent) => void | Promise, options: WatchDirOptions = {}): Promise; ``` **Parameters**: - `path` _string_ - `onEvent` _(event: FilesystemEvent) = \> void \| Promise\, options: WatchDirOptions = \{\}_ **Returns**: - `Promise` #### writeBytes() [#writebytes] ```ts writeBytes( path: string, data: Uint8Array, options: WriteFileOptions = {}): Promise; ``` **Parameters**: - `path` _string_ - `data` _Uint8Array_ - `options` _WriteFileOptions = \{\}_ **Returns**: - `Promise` #### writeMany() [#writemany] ```ts writeMany( files: Record, options: WriteManyOptions = {}): Promise; ``` **Parameters**: - `files` _Record\_ - `options` _WriteManyOptions = \{\}_ **Returns**: - `Promise` #### writeText() [#writetext] ```ts writeText(path: string, text: string, options: WriteFileOptions = {}): Promise; ``` **Parameters**: - `path` _string_ - `text` _string_ - `options` _WriteFileOptions = \{\}_ **Returns**: - `Promise` *** ## FilesystemEventType [#filesystemeventtype] ```ts enum FilesystemEventType { CREATE = 'create', WRITE = 'write', REMOVE = 'remove', RENAME = 'rename', CHMOD = 'chmod', } ``` **Properties**: - `CREATE` _'create'_ - `WRITE` _'write'_ - `REMOVE` _'remove'_ - `RENAME` _'rename'_ - `CHMOD` _'chmod'_ *** ## DownloadFileOptions [#downloadfileoptions] **Properties**: - `onProgress?` _TransferProgressCallback_ - `signal?` _AbortSignal_ *** ## FilePermissionsParams [#filepermissionsparams] ```ts type FilePermissionsParams = FilePermissionsOptions ``` *** ## FilesystemEvent [#filesystemevent] **Properties**: - `type` _FilesystemEventType_ - `name` _string_ - `isDir` _boolean_ - `timestamp` _number_ *** ## Match [#match] ```ts type Match = FileMatch ``` *** ## PresignedUrlOptions [#presignedurloptions] **Properties**: - `expiresInSeconds?` _number_ *** ## ReadFileOptions [#readfileoptions] *** ## ReadManyOptions [#readmanyoptions] *** ## SearchFilesResponse [#searchfilesresponse] ```ts type SearchFilesResponse = ListResult ``` *** ## TransferProgressCallback [#transferprogresscallback] *** ## UploadFileOptions [#uploadfileoptions] **Properties**: - `onProgress?` _TransferProgressCallback_ - `signal?` _AbortSignal_ - `atomic?` _boolean_ *** ## WatchDirOptions [#watchdiroptions] **Properties**: - `recursive?` _boolean_ - `onExit?` _(err?: Error) =\> void_ - `onOverflow?` _() =\> void_ *** ## WatchHandle [#watchhandle] **Properties**: - `exitError` _Error \| undefined_ ### Methods [#methods-1] #### stop() [#stop] ```ts stop(): Promise; ``` **Returns**: - `Promise` #### waitForExit() [#waitforexit] ```ts waitForExit(): Promise; ``` **Returns**: - `Promise` *** ## WriteFileOptions [#writefileoptions] **Properties**: - `mode?` _string_ - `atomic?` _boolean_ *** ## WriteManyOptions [#writemanyoptions] **Properties**: - `atomic?` _boolean_ *** ## SearchResult [#searchresult] One page of `GET /sandboxes/search` (`Daytona.search()`). `total` is exact when `totalRelation === 'eq'` and a lower bound when it is `'gte'`. **Properties**: - `items` _T\[\]_ - `nextCursor?` _string_ - `total` _number_ - `totalRelation` _SearchTotalRelation_ - `rawTotalRelation` _string_ *** ## SearchSandboxesOptions [#searchsandboxesoptions] Every `Daytona.search()` option (`GET /sandboxes/search`). **Properties**: - `q?` _string_ - Free text over name and image; also an exact match when it is a sandbox id. - `status?` _string \| readonly string\[\]_ - A single value or a list (any-of) over the API's lifecycle state names (`running`, `stopped`, ...). - `sandboxClass?` _SandboxClass \| readonly SandboxClass\[\]_ - A single value or a list (any-of). - `region?` _string \| readonly string\[\]_ - A single value or a list (any-of) over region slugs. - `imageRef?` _string_ - `imageRefPrefix?` _string_ - `labels?` _Record\_ - Containment: every listed label must match. - `spot?` _boolean_ - `forkedFrom?` _string_ - Sandboxes forked from this sandbox id. - `minCores?` _number_ - Inclusive bounds on `cores_max` (the CPU limit), in cores (1 core = 2 vCPUs). - `maxCores?` _number_ - `minMemoryMib?` _number_ - `maxMemoryMib?` _number_ - `minDiskMib?` _number_ - `maxDiskMib?` _number_ - `createdStartAt?` _SearchTimestamp_ - `createdEndAt?` _SearchTimestamp_ - `updatedStartAt?` _SearchTimestamp_ - `updatedEndAt?` _SearchTimestamp_ - `lastActivityStartAt?` _SearchTimestamp_ - `lastActivityEndAt?` _SearchTimestamp_ - `sort?` _SearchSort_ - Defaults to `created_at`. - `order?` _SearchOrder_ - Defaults to `desc`. - `namePrefix?` _string_ - Server-side prefix on the name (the search form of `list({ name })`). - `idPrefix?` _string_ - Server-side prefix on the id (the search form of `list({ id })`). - `limit?` _number_ - Clamped to 1..200 by the server. - `cursor?` _string_ - Opaque; bound to the filter + sort that produced it. *** ## SearchSort [#searchsort] ```ts type SearchSort = 'created_at' | 'updated_at' | 'last_activity_at' | 'name' | 'cores' | 'memory_mib' | 'disk_mib' ``` *** ## SearchOrder [#searchorder] ```ts type SearchOrder = 'asc' | 'desc' ``` *** ## SearchTimestamp [#searchtimestamp] ```ts type SearchTimestamp = Date | string ``` An RFC 3339 string, or a `Date` (serialized with `toISOString()`, i.e. UTC). *** ## SearchTotalRelation [#searchtotalrelation] ```ts type SearchTotalRelation = (typeof API_SEARCH_TOTAL_RELATIONS)[number] | 'unknown' ``` *** ## FileInfo [#fileinfo] **Properties**: - `name` _string_ - `path?` _string_ - `isDir` _boolean_ - `size` _number_ - `modTime?` _string_ - `modifiedAt?` _string_ - `mode?` _string_ - `permissions?` _string_ - `owner?` _string_ - `group?` _string_ *** ## FileMatch [#filematch] ```ts type FileMatch = toolbox.Match ``` *** ## ReplaceResult [#replaceresult] **Properties**: - `file` _string_ - `success?` _boolean_ - `error?` _string_ *** ## FilePermissionsOptions [#filepermissionsoptions] **Properties**: - `mode?` _string_ - `owner?` _string_ - `group?` _string_ *** ## BulkWriteFile [#bulkwritefile] **Properties**: - `path` _string_ - `bytes` _number_ *** ## BulkWriteResult [#bulkwriteresult] **Properties**: - `files` _BulkWriteFile\[\]_ - `errors` _string\[\]_ *** ## BulkReadError [#bulkreaderror] **Properties**: - `path` _string_ - `code?` _string_ - `message` _string_ - `source?` _string_ *** ## BulkReadResult [#bulkreadresult] **Properties**: - `files` _Record\_ - `errors` _BulkReadError\[\]_ *** ## SIGNED\_FILE\_MAX\_TTL\_SECONDS [#signed_file_max_ttl_seconds] ```ts const SIGNED_FILE_MAX_TTL_SECONDS = 604_800 ``` Server ceiling on a pre-signed file URL's lifetime (7 days). The API rejects an `expires` further ahead than this, so the SDK refuses it before the request; never-expiring links do not exist. # Git (/docs/typescript-sdk/git) ## GitService [#gitservice] ### Constructors [#constructors] #### Constructor [#constructor] ```ts new GitService(transport: HttpTransport): GitService; ``` **Parameters**: - `transport` _HttpTransport_ **Returns**: - `GitService` ### Methods [#methods] #### add() [#add] ```ts add(path: string, files: string[]): Promise; ``` **Parameters**: - `path` _string_ - `files` _string\[\]_ **Returns**: - `Promise` #### addRemote() [#addremote] ```ts addRemote(path: string, name: string, url: string): Promise; ``` **Parameters**: - `path` _string_ - `name` _string_ - `url` _string_ **Returns**: - `Promise` #### checkoutBranch() [#checkoutbranch] ```ts checkoutBranch(path: string, branch: string): Promise; ``` **Parameters**: - `path` _string_ - `branch` _string_ **Returns**: - `Promise` #### clone() [#clone] ```ts clone(url: string, options: CloneOptions): Promise; ``` **Parameters**: - `url` _string_ - `options` _CloneOptions_ **Returns**: - `Promise` #### commit() [#commit] ```ts commit( path: string, message: string, options: CommitOptions): Promise; ``` **Parameters**: - `path` _string_ - `message` _string_ - `options` _CommitOptions_ **Returns**: - `Promise` #### createBranch() [#createbranch] ```ts createBranch(path: string, name: string): Promise; ``` **Parameters**: - `path` _string_ - `name` _string_ **Returns**: - `Promise` #### deleteBranch() [#deletebranch] ```ts deleteBranch(path: string, name: string): Promise; ``` **Parameters**: - `path` _string_ - `name` _string_ **Returns**: - `Promise` #### getConfig() [#getconfig] ```ts getConfig(key: string, options: GitConfigOptions = {}): Promise; ``` **Parameters**: - `key` _string_ - `options` _GitConfigOptions = \{\}_ **Returns**: - `Promise` #### history() [#history] ```ts history(path: string): Promise>; ``` **Parameters**: - `path` _string_ **Returns**: - `Promise>` #### init() [#init] ```ts init(path: string, options: InitOptions = {}): Promise; ``` **Parameters**: - `path` _string_ - `options` _InitOptions = \{\}_ **Returns**: - `Promise` #### listBranches() [#listbranches] ```ts listBranches(path: string): Promise>; ``` List branches; response always has `{items,nextCursor}`. **Parameters**: - `path` _string_ **Returns**: - `Promise>` #### listRemotes() [#listremotes] ```ts listRemotes(path: string): Promise>; ``` **Parameters**: - `path` _string_ **Returns**: - `Promise>` #### pull() [#pull] ```ts pull(path: string, options: CredentialOptions = {}): Promise; ``` **Parameters**: - `path` _string_ - `options` _CredentialOptions = \{\}_ **Returns**: - `Promise` #### push() [#push] ```ts push(path: string, options: PushOptions = {}): Promise; ``` **Parameters**: - `path` _string_ - `options` _PushOptions = \{\}_ **Returns**: - `Promise` #### reset() [#reset] ```ts reset(path: string, options: ResetOptions = {}): Promise; ``` **Parameters**: - `path` _string_ - `options` _ResetOptions = \{\}_ **Returns**: - `Promise` #### restore() [#restore] ```ts restore(path: string, files: string[], options: RestoreOptions = {}): Promise; ``` **Parameters**: - `path` _string_ - `files` _string\[\]_ - `options` _RestoreOptions = \{\}_ **Returns**: - `Promise` #### setConfig() [#setconfig] ```ts setConfig(key: string, value: string, options: GitConfigOptions = {}): Promise; ``` **Parameters**: - `key` _string_ - `value` _string_ - `options` _GitConfigOptions = \{\}_ **Returns**: - `Promise` #### status() [#status] ```ts status(path: string): Promise; ``` **Parameters**: - `path` _string_ **Returns**: - `Promise` *** ## CloneOptions [#cloneoptions] **Properties**: - `path` _string_ - `branch?` _string_ - `commitId?` _string_ - `depth?` _number_ - `insecureSkipTls?` _boolean_ - `username?` _string_ - `password?` _string_ - `timeout?` _number_ *** ## CommitOptions [#commitoptions] **Properties**: - `author` _string_ - `email` _string_ - `allowEmpty?` _boolean_ *** ## CredentialOptions [#credentialoptions] **Properties**: - `username?` _string_ - `password?` _string_ - `branch?` _string_ - `remote?` _string_ - `timeout?` _number_ *** ## GitCommit [#gitcommit] ```ts type GitCommit = toolbox.CommitInfo ``` One commit returned by `git.history()`. *** ## ListBranchResponse [#listbranchresponse] ```ts type ListBranchResponse = toolbox.BranchList ``` *** ## PushOptions [#pushoptions] **Properties**: - `username?` _string_ - `password?` _string_ - `branch?` _string_ - `remote?` _string_ - `timeout?` _number_ - `setUpstream?` _boolean_ *** ## ResetOptions [#resetoptions] **Properties**: - `mode?` _string_ - `target?` _string_ - `files?` _string\[\]_ *** ## RestoreOptions [#restoreoptions] **Properties**: - `staged?` _boolean_ - `worktree?` _boolean_ - `source?` _string_ *** ## GitConfigScope [#gitconfigscope] ```ts type GitConfigScope = 'global' | 'local' ``` *** ## GitRemote [#gitremote] **Properties**: - `name` _string_ - `url` _string_ *** ## GitStatus [#gitstatus] **Properties**: - `currentBranch` _string_ - `ahead?` _number_ - `behind?` _number_ - `branchPublished?` _boolean_ - `fileStatus?` _Array\<\{ name: string; staging?: string; worktree?: string \}\>_ *** ## GitCommitResponse [#gitcommitresponse] ```ts type GitCommitResponse = toolbox.CommitResponse ``` # Process (/docs/typescript-sdk/process) ## ProcessHandle [#processhandle] **Properties**: - `id` _string_ - `sandboxId` _string_ - `kind?` _ProcessKind_ ### Constructors [#constructors] #### Constructor [#constructor] ```ts new ProcessHandle( transport: HttpTransport, sandboxId: string, processId: string, kind?: ProcessKind): ProcessHandle; ``` **Parameters**: - `transport` _HttpTransport_ - `sandboxId` _string_ - `processId` _string_ - `kind?` _ProcessKind_ **Returns**: - `ProcessHandle` ### Methods [#methods] #### attach() [#attach] ```ts attach(): Promise; ``` **Returns**: - `Promise` #### closeStdin() [#closestdin] ```ts closeStdin(): Promise; ``` Close the stdin of an exec or pty process (EOF). **Returns**: - `Promise` #### delete() [#delete] ```ts delete(): Promise; ``` Delete the process and its logs, stopping it first if it is running. Refused (`UnsupportedOperationError`) for a running code cell, and for a session command that has not stopped within 5 s: delete its session. **Returns**: - `Promise` #### get() [#get] ```ts get(): Promise; ``` **Returns**: - `Promise` #### kill() [#kill] ```ts kill(options: KillOptions = {}): Promise; ``` **Parameters**: - `options` _KillOptions = \{\}_ **Returns**: - `Promise` #### logs() [#logs] ```ts logs(options: LogsOptions = {}): Promise; ``` **Parameters**: - `options` _LogsOptions = \{\}_ **Returns**: - `Promise` #### resize() [#resize] ```ts resize(cols: number, rows: number): Promise; ``` **Parameters**: - `cols` _number_ - `rows` _number_ **Returns**: - `Promise` #### streamLogs() [#streamlogs] ```ts streamLogs(options: StreamLogsOptions = {}): AsyncIterable; ``` **Parameters**: - `options` _StreamLogsOptions = \{\}_ **Returns**: - `AsyncIterable` #### toJSON() [#tojson] ```ts toJSON(): ProcessHandleJSON; ``` **Returns**: - `ProcessHandleJSON` #### wait() [#wait] ```ts wait(options: WaitProcessOptions = {}): Promise; ``` **Parameters**: - `options` _WaitProcessOptions = \{\}_ **Returns**: - `Promise` #### writeStdin() [#writestdin] ```ts writeStdin(data: string | Uint8Array): Promise; ``` Write to the stdin of an exec or pty process created with stdin='open'. **Parameters**: - `data` _string \| Uint8Array_ **Returns**: - `Promise` *** ## ProcessService [#processservice] ### Constructors [#constructors-1] #### Constructor [#constructor-1] ```ts new ProcessService(transport: HttpTransport, sandboxId: string): ProcessService; ``` **Parameters**: - `transport` _HttpTransport_ - `sandboxId` _string_ **Returns**: - `ProcessService` ### Methods [#methods-1] #### connect() [#connect] ```ts connect(idOrHandle: string | ProcessHandleJSON): ProcessHandle; ``` **Parameters**: - `idOrHandle` _string \| ProcessHandleJSON_ **Returns**: - `ProcessHandle` #### connectSession() [#connectsession] ```ts connectSession(sessionIdOrJSON: string | SessionJSON): Session; ``` Rebind a shell session by id or serialized identity, without a request. **Parameters**: - `sessionIdOrJSON` _string \| SessionJSON_ **Returns**: - `Session` #### createSession() [#createsession] ```ts createSession(options: CreateSessionOptions = {}): Promise; ``` Create one persistent shell. Set its cwd/env here, not on its commands. **Parameters**: - `options` _CreateSessionOptions = \{\}_ **Returns**: - `Promise` #### get() [#get-1] ```ts get(id: string): Promise; ``` **Parameters**: - `id` _string_ **Returns**: - `Promise` #### list() [#list] ```ts list(options: ProcessListOptions = {}): Promise>; ``` **Parameters**: - `options` _ProcessListOptions = \{\}_ **Returns**: - `Promise>` #### run() [#run] ```ts run(command: ProcessCommand, options: RunOptions = {}): Promise; ``` Run a command, wait for its shell to exit, and collect its output. Normally one round trip: starts, waits, and returns inline logs. Larger output or a process outliving the wait window falls back to split calls. Output is bounded by per-process retention; a timed-out result collects only the first few log pages rather than chasing a live writer. Strings (or `{ cmd }`) use the sandbox shell (`bash`, else `sh`; override with `shell`). Quote globs and brackets (`pip install -e '.[test]'`). `{ argv: [...] }` bypasses the shell for untrusted arguments. For shared shell state, use `createSession` instead. Background children holding output descriptors open drain for at most about two seconds after the shell exits; later output is not included. Prefer `start` for long-running servers, or redirect their output (`nohup cmd > server.log 2>&1 &`). **Parameters**: - `command` _ProcessCommand_ - Shell command string, `{ cmd }`, or shell-free `{ argv }`. - `options` _RunOptions = \{\}_ **Returns**: - `Promise` - Output, stdout, stderr, logs and the exit result. #### start() [#start] ```ts start( command: ProcessCommand, options: ProcessStartOptions = {}): Promise; ``` Start a detached process and return a handle immediately. Use `ProcessHandle.streamLogs`, `ProcessHandle.wait`, or `ProcessHandle.kill` to control it. Prefer this for long-running servers: start once, then poll the port or stream logs for readiness. String commands (or `{ cmd }`) run through the sandbox shell (`bash`, else `sh`; pin another with `shell`). Quote globs and brackets, such as `pip install -e '.[test]'`. Pass `{ argv: [...] }` to bypass the shell for untrusted arguments. Plain commands do not share shell state; use `createSession` for a persistent shell. **Parameters**: - `command` _ProcessCommand_ - Shell command string, `{ cmd }`, or shell-free `{ argv }`. - `options` _ProcessStartOptions = \{\}_ **Returns**: - `Promise` *** ## PtyService [#ptyservice] ### Constructors [#constructors-2] #### Constructor [#constructor-2] ```ts new PtyService(process: ProcessService): PtyService; ``` **Parameters**: - `process` _ProcessService_ **Returns**: - `PtyService` ### Methods [#methods-2] #### attach() [#attach-1] ```ts attach( command?: string, options: Omit & { terminal?: TerminalSize } = {}): Promise<{ handle: ProcessHandle; connection: PtyDuplex }>; ``` **Parameters**: - `command?` _string_ - `options` _Omit\ & \{ terminal?: TerminalSize \} = \{\}_ **Returns**: - `Promise<{ handle: ProcessHandle; connection: PtyDuplex }>` #### connect() [#connect-1] ```ts connect(idOrHandle: string | ProcessHandleJSON): ProcessHandle; ``` **Parameters**: - `idOrHandle` _string \| ProcessHandleJSON_ **Returns**: - `ProcessHandle` #### delete() [#delete-1] ```ts delete(idOrHandle: string | ProcessHandleJSON): Promise; ``` **Parameters**: - `idOrHandle` _string \| ProcessHandleJSON_ **Returns**: - `Promise` #### list() [#list-1] ```ts list(): Promise>; ``` **Returns**: - `Promise>` #### start() [#start-1] ```ts start( command?: string, options: Omit & { terminal?: TerminalSize } = {}): Promise; ``` **Parameters**: - `command?` _string_ - `options` _Omit\ & \{ terminal?: TerminalSize \} = \{\}_ **Returns**: - `Promise` *** ## Session [#session] One persistent shell. Commands run one at a time, in order; `cd`, exports, and functions carry over. Set cwd/env with `process.createSession()`. Interrupt a command with `handle.kill({ signal: 'INT' })`: the session survives. Sessions survive pause/resume, but not a sandbox stop/start. After `set -x` or `set -v` in a session, later commands' stderr also includes the shell wrapper used to run each command. **Properties**: - `sandboxId` _string_ - `id` _string_ ### Constructors [#constructors-3] #### Constructor [#constructor-3] ```ts new Session(binding: ProcessBinding, id: string): Session; ``` **Parameters**: - `binding` _ProcessBinding_ - `id` _string_ **Returns**: - `Session` ### Methods [#methods-3] #### \[Symbol.asyncDispose\]() [#symbolasyncdispose] ```ts [Symbol.asyncDispose](): Promise; ``` Deletes the session on scope exit; one already deleted in the scope is fine. **Returns**: - `Promise` #### delete() [#delete-2] ```ts delete(): Promise; ``` End the shell and delete it and all its command records. **Returns**: - `Promise` #### get() [#get-2] ```ts get(): Promise; ``` Read the shell process, including its current working directory. **Returns**: - `Promise` #### run() [#run-1] ```ts run(command: string, options: SessionRunOptions = {}): Promise; ``` Run in this shell, wait, and collect output using the process run path. **Parameters**: - `command` _string_ - `options` _SessionRunOptions = \{\}_ **Returns**: - `Promise` #### start() [#start-2] ```ts start(command: string, options: SessionStartOptions = {}): Promise; ``` Queue a command and return its handle without waiting for completion. **Parameters**: - `command` _string_ - `options` _SessionStartOptions = \{\}_ **Returns**: - `Promise` #### toJSON() [#tojson-1] ```ts toJSON(): SessionJSON; ``` **Returns**: - `SessionJSON` *** ## PtyDuplex [#ptyduplex] **Properties**: - `readable` _AsyncIterable\_ ### Methods [#methods-4] #### close() [#close] ```ts close(): void; ``` **Returns**: - `void` #### write() [#write] ```ts write(data: string | Uint8Array): void; ``` **Parameters**: - `data` _string \| Uint8Array_ **Returns**: - `void` *** ## CreateSessionOptions [#createsessionoptions] Settings for the persistent shell, inherited by every command. **Properties**: - `cwd?` _string_ - `env?` _Readonly\\>_ - `shell?` _string_ - A POSIX shell (bash, sh, dash, zsh, ksh) on Linux and macOS; another shell is refused when the session is created. - `login?` _boolean_ - `name?` _string_ *** ## SessionRunOptions [#sessionrunoptions] **Properties**: - `stdin?` _'closed' \| 'open'_ - `executionTimeout?` _number_ - Server-side command deadline in milliseconds. The clock starts when the command starts, after any queued commands ahead of it. The command is stopped and the session survives; a command that has not stopped 5 s after its timeout ends the session instead of blocking it. In dash, BusyBox `sh` and mksh an interrupt leaves only the innermost shell function or sourced file, as it does in bash older than 4.4 (macOS's `/bin/bash`) when a DEBUG trap is set. - `name?` _string_ - `keepLogs?` _KeepLogs_ - `timeout?` _number_ - Caller wait budget in milliseconds; omitted or 0 waits unbounded. *** ## SessionStartOptions [#sessionstartoptions] **Properties**: - `stdin?` _'closed' \| 'open'_ - `executionTimeout?` _number_ - Server-side command deadline in milliseconds. The clock starts when the command starts, after any queued commands ahead of it. The command is stopped and the session survives; a command that has not stopped 5 s after its timeout ends the session instead of blocking it. In dash, BusyBox `sh` and mksh an interrupt leaves only the innermost shell function or sourced file, as it does in bash older than 4.4 (macOS's `/bin/bash`) when a DEBUG trap is set. - `name?` _string_ - `keepLogs?` _KeepLogs_ *** ## SessionJSON [#sessionjson] **Properties**: - `sandboxId` _string_ - `sessionId` _string_ *** ## ProcessHandleJSON [#processhandlejson] **Properties**: - `sandboxId` _string_ - `processId` _string_ - `kind?` _ProcessKind_ *** ## ProcessKind [#processkind] ```ts type ProcessKind = 'exec' | 'pty' | 'code' | 'session' ``` *** ## ProcessReportedKind [#processreportedkind] ```ts type ProcessReportedKind = ProcessKind | 'unknown' ``` *** ## ProcessState [#processstate] ```ts type ProcessState = 'starting' | 'provisioning' | 'running' | 'terminal' | 'unknown' ``` *** ## ProcessSignal [#processsignal] ```ts type ProcessSignal = 'TERM' | 'KILL' | 'INT' | 'HUP' | 'QUIT' | 'USR1' | 'USR2' ``` *** ## ProcessReason [#processreason] ```ts type ProcessReason = 'exited' | 'signaled' | 'timed_out' | 'lost' | 'failed' | 'unknown' ``` *** ## KeepLogs [#keeplogs] ```ts type KeepLogs = 'until_cleanup' | 'on_exit_ttl' | 'none' ``` *** ## ProcessKeepLogs [#processkeeplogs] ```ts type ProcessKeepLogs = KeepLogs | 'unknown' ``` *** ## ProcessStdinMode [#processstdinmode] ```ts type ProcessStdinMode = 'closed' | 'open' | 'unknown' ``` *** ## TerminalSize [#terminalsize] ```ts type TerminalSize = toolbox.TerminalSize ``` *** ## ProcessDto [#processdto] **Properties**: - `id` _string_ - `name?` _string_ - `pid?` _number_ - `kind` _ProcessReportedKind_ - `rawKind` _string_ - `state` _ProcessState_ - `rawState` _string_ - `system` _boolean_ - `sessionId?` _string_ - `argv?` _string\[\]_ - `shellCommand?` _string_ - `code?` _string_ - `language?` _string_ - `shell?` _string_ - `resolvedShell?` _string_ - `login?` _boolean_ - `cwd?` _string_ - `user?` _string_ - `stdin?` _ProcessStdinMode_ - `rawStdin?` _string_ - `executionTimeout?` _number_ - Server-managed process deadline in milliseconds. - `terminal?` _TerminalSize_ - `keepLogs?` _ProcessKeepLogs_ - `rawKeepLogs?` _string_ - `exitCode?` _number_ - `signal?` _string_ - `reason?` _ProcessReason_ - `rawReason?` _string_ - `createdAt?` _string_ - `startedAt?` _string_ - `exitedAt?` _string_ - `truncatedHead?` _boolean_ - `firstAvailableCursor?` _string_ - `lastCursor?` _string_ *** ## WaitResult [#waitresult] ```ts type WaitResult = | { reason: 'exited'; exitCode: number; signal?: undefined; rawReason?: string } | { reason: 'signaled'; signal: string; exitCode?: undefined; rawReason?: string } | { reason: 'timed_out'; exitCode?: undefined; signal?: undefined; rawReason?: string } | { reason: 'lost' | 'failed'; exitCode?: number; signal?: string; rawReason?: string } | { reason: 'unknown'; exitCode?: number; signal?: string; rawReason: string } ``` *** ## ProcessStartOptions [#processstartoptions] **Properties**: - `cmd?` _string_ - `argv?` _string\[\]_ - `name?` _string_ - `cwd?` _string_ - `env?` _Record\_ - `user?` _string_ - `shell?` _string_ - `login?` _boolean_ - `stdin?` _'closed' \| 'open'_ - `executionTimeout?` _number_ - Server-managed process deadline in milliseconds. - `terminal?` _TerminalSize_ - `keepLogs?` _KeepLogs_ *** ## ProcessCommand [#processcommand] ```ts type ProcessCommand = string | { cmd: string; argv?: never } | { argv: readonly string[]; cmd?: never } ``` What to execute, as the first argument of `process.start()` / `process.run()` / `sandbox.exec()`: a shell command string, or an object naming exactly one of `cmd` (shell) or `argv` (exec, no shell — the safe form for untrusted arguments). Mirrors Python's `command=` / `argv=` keywords. *** ## RunOptions [#runoptions] ```ts type RunOptions = Omit & { /** Caller wait budget in milliseconds; `0` waits unbounded. */ timeout?: number /** `run()` only creates exec processes; PTYs come from `sandbox.pty.start()` / `attach()`. */ kind?: 'exec' } ``` *** ## RunResult [#runresult] ```ts type RunResult = WaitResult & { processId: string output: string stdout: string stderr: string logs: LogFrame[] } ``` *** ## LogFrame [#logframe] **Properties**: - `cursor` _string_ - `channel` _'stdout' \| 'stderr' \| 'pty' \| 'setup' \| string_ - `data` _string_ - `encoding?` _'text' \| 'base64' \| string_ - `timestamp?` _number_ *** ## LogsPage [#logspage] **Extends**: `ListResult` **Properties**: - `truncatedHead?` _boolean_ - `firstAvailableCursor?` _string_ *** ## StreamLogEvent [#streamlogevent] ```ts type StreamLogEvent = | { type: 'log'; cursor?: string; frame: LogFrame } | { type: 'state'; cursor?: string; result: WaitResult } | { type: 'warning'; cursor?: string; message: string; firstAvailableCursor?: string } | { type: 'eof'; cursor?: string } | { type: 'error'; cursor?: string; error: Error } ``` *** ## LogsOptions [#logsoptions] **Properties**: - `cursor?` _string_ - `limit?` _number_ - `encoding?` _'text' \| 'base64'_ *** ## StreamLogsOptions [#streamlogsoptions] **Properties**: - `cursor?` _string_ - `limit?` _number_ - `encoding?` _'text' \| 'base64'_ - `signal?` _AbortSignal_ *** ## KillOptions [#killoptions] **Properties**: - `signal?` _ProcessSignal_ - `escalateAfter?` _number_ - `escalateTo?` _ProcessSignal_ *** ## ProcessListOptions [#processlistoptions] **Properties**: - `state?` _'running' \| 'terminal' \| 'all'_ - `kind?` _ProcessKind_ - `sessionId?` _string_ - `name?` _string_ - `pid?` _number_ # Interpreter (/docs/typescript-sdk/interpreter) ## InterpreterContext [#interpretercontext] **Properties**: - `id` _string_ - `language` _string_ - `sandboxId` _string_ - `#transport` _HttpTransport_ - `#executionQueue` _ContextExecutionQueue_ - `#onClose` _() =\> Promise\_ ### Constructors [#constructors] #### Constructor [#constructor] ```ts new InterpreterContext( transport: HttpTransport, sandboxId: string, id: string, language: string, executionQueue: ContextExecutionQueue, onClose: () => Promise): InterpreterContext; ``` **Parameters**: - `transport` _HttpTransport_ - `sandboxId` _string_ - `id` _string_ - `language` _string_ - `executionQueue` _ContextExecutionQueue_ - `onClose` _() = \> Promise\_ **Returns**: - `InterpreterContext` ### Methods [#methods] #### close() [#close] ```ts close(): Promise; ``` **Returns**: - `Promise` #### run() [#run] ```ts run( code: string, options: Omit = {}): Promise; ``` Execute code inside this explicit interpreter context. If the named context vanished, the typed SESSION_NOT_FOUND error surfaces unchanged so the caller can recreate the context and decide what code, if any, is safe to rerun. **Parameters**: - `code` _string_ - `options` _Omit\ = \{\}_ **Returns**: - `Promise` #### toJSON() [#tojson] ```ts toJSON(): InterpreterContextJSON; ``` **Returns**: - `InterpreterContextJSON` *** ## InterpreterService [#interpreterservice] ### Constructors [#constructors-1] #### Constructor [#constructor-1] ```ts new InterpreterService( transport: HttpTransport, process: ProcessService): InterpreterService; ``` **Parameters**: - `transport` _HttpTransport_ - `process` _ProcessService_ **Returns**: - `InterpreterService` ### Methods [#methods-1] #### connectContext() [#connectcontext] ```ts connectContext(sessionId: string, language: string): InterpreterContext; ``` **Parameters**: - `sessionId` _string_ - `language` _string_ **Returns**: - `InterpreterContext` #### connectContext() [#connectcontext-1] ```ts connectContext(context: InterpreterContextJSON): InterpreterContext; ``` **Parameters**: - `context` _InterpreterContextJSON_ **Returns**: - `InterpreterContext` #### createContext() [#createcontext] ```ts createContext(options: InterpreterContextOptions): Promise; ``` **Parameters**: - `options` _InterpreterContextOptions_ **Returns**: - `Promise` #### deleteContext() [#deletecontext] ```ts deleteContext( sessionIdOrContext: string | InterpreterContext | InterpreterContextJSON): Promise; ``` **Parameters**: - `sessionIdOrContext` _string \| InterpreterContext \| InterpreterContextJSON_ **Returns**: - `Promise` #### listContexts() [#listcontexts] ```ts listContexts(): Promise; ``` **Returns**: - `Promise` #### run() [#run-1] ```ts run(code: string, options: InterpreterRunOptions = {}): Promise; ``` Execute code and return the parsed interpreter result. Rehydrated `kind:'code'` process handles can replay logs and wait/kill, but they do not recreate this decomposed result on another worker. A vanished explicit context surfaces the typed SESSION_NOT_FOUND error; callers decide whether to recreate the context and what to rerun. **Parameters**: - `code` _string_ - `options` _InterpreterRunOptions = \{\}_ **Returns**: - `Promise` *** ## InterpreterError [#interpretererror] **Properties**: - `name` _string_ - `value` _string_ - `traceback` _string\[\]_ *** ## InterpreterLogs [#interpreterlogs] **Properties**: - `stdout` _string_ - `stderr` _string_ *** ## InterpreterOutput [#interpreteroutput] **Properties**: - `data` _Record\_ - `isMainResult` _boolean_ - `text?` _string_ - `html?` _string_ - `png?` _string_ - `svg?` _string_ - `json?` _unknown_ *** ## InterpreterProcess [#interpreterprocess] ```ts type InterpreterProcess = WaitResult & { processId: string } ``` *** ## InterpreterRunOptions [#interpreterrunoptions] **Properties**: - `language?` _'python' \| 'typescript' \| 'javascript' \| string_ - `sessionId?` _string_ - `context?` _InterpreterContextReference \| InterpreterContextJSON_ - `isolated?` _boolean_ - `cwd?` _string_ - `env?` _Record\_ - `timeout?` _number_ - Caller wait budget in milliseconds; `0` waits unbounded. *** ## InterpreterContextJSON [#interpretercontextjson] **Properties**: - `sandboxId` _string_ - `contextId` _string_ - `language` _string_ *** ## InterpreterContextOptions [#interpretercontextoptions] **Properties**: - `id?` _string_ - `language` _'python' \| 'typescript' \| 'javascript' \| string_ - `cwd?` _string_ - `env?` _Record\_ *** ## InterpreterContextReference [#interpretercontextreference] **Properties**: - `sandboxId` _string_ - `id` _string_ - `language` _string_ *** ## InterpreterResult [#interpreterresult] **Properties**: - `process` _InterpreterProcess_ - `results` _InterpreterOutput\[\]_ - `logs` _InterpreterLogs_ - `error?` _InterpreterError_ # ComputerUse (/docs/typescript-sdk/computer-use) ## ComputerUseService [#computeruseservice] **Properties**: - `service` _AddonProcessesService_ - `mouse` _MouseService_ - `keyboard` _KeyboardService_ - `screen` _ScreenService_ - `display` _DisplayService_ - `a11y` _A11yService_ - `recording` _RecordingService_ ### Constructors [#constructors] #### Constructor [#constructor] ```ts new ComputerUseService(transport: ComputerUseTransport): ComputerUseService; ``` **Parameters**: - `transport` _ComputerUseTransport_ **Returns**: - `ComputerUseService` ### Methods [#methods] #### restart() [#restart] ```ts restart(): Promise; ``` **Returns**: - `Promise` #### start() [#start] ```ts start(): Promise; ``` **Returns**: - `Promise` #### status() [#status] ```ts status(): Promise; ``` **Returns**: - `Promise` #### stop() [#stop] ```ts stop(): Promise; ``` **Returns**: - `Promise` *** ## AddonProcessesService [#addonprocessesservice] ### Constructors [#constructors-1] #### Constructor [#constructor-1] ```ts new AddonProcessesService(transport: ComputerUseTransport): AddonProcessesService; ``` **Parameters**: - `transport` _ComputerUseTransport_ **Returns**: - `AddonProcessesService` ### Methods [#methods-1] #### errors() [#errors] ```ts errors(name: string): Promise; ``` **Parameters**: - `name` _string_ **Returns**: - `Promise` #### logs() [#logs] ```ts logs(name: string): Promise; ``` **Parameters**: - `name` _string_ **Returns**: - `Promise` #### restart() [#restart-1] ```ts restart(name: string): Promise; ``` **Parameters**: - `name` _string_ **Returns**: - `Promise` #### status() [#status-1] ```ts status(): Promise>; ``` **Returns**: - `Promise>` #### status() [#status-2] ```ts status(name: string): Promise