daytona

What this skill does

## What is Daytona

Daytona provides **full composable computers** — **sandboxes** — for AI agents. Each sandbox is an isolated runtime environment with its own kernel, filesystem, network stack, and dedicated vCPU, RAM, and disk. Agents can install packages, run servers, compile code, and manage processes inside sandboxes.

Sandboxes are built from OCI-compliant images or snapshots. Any language or tool that runs on Linux works.

**Scope:** This skill covers Daytona Cloud (`app.daytona.io`). For self-hosted Daytona OSS deployment, see `./references/platform/oss-deployment.md`.

## Before You Start

Before writing any Daytona code, verify setup:

1. **SDK installed?** Check that the Daytona SDK is installed for the user's language (e.g. `pip show daytona` or check `package.json` for `@daytonaio/sdk`). If not, install it.
2. **API key set?** Check `DAYTONA_API_KEY` in the shell environment or in environment files. If not set, tell the user they need an API key and point them to [Daytona Dashboard > API Keys](https://app.daytona.io/dashboard/keys) to create one.

## SDK Essentials — Python

### Installation

```bash
pip install daytona
```

### Create client and sandbox

```python
from daytona import Daytona

# Uses DAYTONA_API_KEY env var
daytona = Daytona()

# Create a sandbox with defaults (1 vCPU, 1GB RAM, 3GB disk)
sandbox = daytona.create()
```

```python
from daytona import Daytona, CreateSandboxFromImageParams, Image, Resources

daytona = Daytona()

# Create with a custom image, name, and resources
sandbox = daytona.create(CreateSandboxFromImageParams(
    image=Image.debian_slim("3.12"),
    name="my-sandbox",
    resources=Resources(cpu=2, memory=4, disk=8),
))
```

### Execute commands

Both `exec` and `code_run` return an `ExecuteResponse` with `.result` (stdout) and `.exit_code`.
`code_run` executes in the sandbox's language runtime (set at creation via `language=` param, defaults to `"python"`). Supported: `python`, `typescript`, `javascript`.

```python
# Run a shell command
response = sandbox.process.exec("echo 'Hello, World!'")
print(response.result)     # "Hello, World!"
print(response.exit_code)  # 0

# Run Python code (stateless)
response = sandbox.process.code_run('''
import json
data = {"key": "value"}
print(json.dumps(data, indent=2))
''')
print(response.result)
print(response.exit_code)  # 0 on success, non-zero on error
```

### File operations

```python
# Write a file
sandbox.fs.upload_file(b"Hello, Daytona!", "/home/daytona/data.txt")

# Read a file
content = sandbox.fs.download_file("/home/daytona/data.txt")
print(content.decode())

# List files
files = sandbox.fs.list_files("workspace")
for f in files:
    print(f"{f.name} ({'dir' if f.is_dir else f.size})")
```

### Sandbox lifecycle

```python
# Pause and resume later
sandbox.stop()          # frees CPU/RAM, keeps disk
sandbox.start()         # ready to use again

# Long-term storage (must be stopped first)
sandbox.stop()
sandbox.archive()       # cold storage, no quota impact

# Resume a previous sandbox by ID or name
sandbox = daytona.get("sandbox-id-or-name")
sandbox.start()

# Permanently remove
sandbox.delete()
```

Wrap Daytona calls with `DaytonaError` for error handling. For async, use `AsyncDaytona` (async context manager). For full Python SDK reference, see [python-sdk/README.md](./references/python-sdk/README.md).

## SDK Essentials — TypeScript

The TypeScript SDK (`@daytonaio/sdk`) mirrors the Python API. Key differences: `executeCommand` instead of `exec`, `codeRun` instead of `code_run`, `uploadFile`/`downloadFile`/`listFiles` for file ops, `DaytonaError` for error handling. Install with `npm install @daytonaio/sdk`.

For full TypeScript SDK reference and examples, see [typescript-sdk/README.md](./references/typescript-sdk/README.md).

## Common Patterns

### Custom environments and snapshots

When the user needs specific packages, tools, or a custom OS in their sandbox, define a custom image with the `Image` builder. If the user will create multiple sandboxes with the same setup, offer to build a **snapshot** — snapshots bake dependencies into a reusable template so subsequent sandboxes start quickly with everything pre-installed.

**Note:** Snapshots are built from image definitions, not from live sandbox state. You cannot snapshot a running sandbox to capture its current filesystem.

Define images with the `Image` builder:

```python
from daytona import Image

# Debian with Python packages
image = Image.debian_slim("3.12").pip_install(["pandas", "numpy", "scikit-learn"])

# With system packages and shell commands
image = (Image.debian_slim("3.12")
    .run_commands("apt-get update && apt-get install -y curl git",
                   "curl -fsSL https://deb.nodesource.com/setup_20.x | bash -")
    .pip_install(["flask"])
    .env({"APP_ENV": "production"}))

# From a Dockerfile
image = Image.from_dockerfile("./Dockerfile")

# From a registry image directly
image = Image.base("node:20-slim")
```

```typescript
import { Image } from '@daytonaio/sdk'

const image = Image.debianSlim('3.12').pipInstall(['pandas', 'numpy', 'scikit-learn'])

const image = Image.debianSlim('3.12')
    .runCommands('apt-get update && apt-get install -y curl git',
                 'curl -fsSL https://deb.nodesource.com/setup_20.x | bash -')
    .pipInstall(['flask'])
    .env({ APP_ENV: 'production' })

const image = Image.fromDockerfile('./Dockerfile')

const image = Image.base('node:20-slim')
```

Create a one-off sandbox directly from an image:

```python
from daytona import Daytona, CreateSandboxFromImageParams, Image

daytona = Daytona()
image = Image.debian_slim("3.12").pip_install(["flask"])
sandbox = daytona.create(CreateSandboxFromImageParams(image=image))
```

```typescript
const sandbox = await daytona.create({ image })
```

Or build a snapshot for reuse (recommended if creating multiple sandboxes with the same setup):

```python
from daytona import Daytona, CreateSandboxFromSnapshotParams, CreateSnapshotParams, Image

daytona = Daytona()

# One-time: build a snapshot
image = Image.debian_slim("3.12").pip_install(["pandas", "numpy", "scikit-learn"])
snapshot = daytona.snapshot.create(CreateSnapshotParams(
    name="data-science",
    image=image,
))

# Every time after: fast start from snapshot
sandbox = daytona.create(CreateSandboxFromSnapshotParams(
    snapshot=snapshot.name,
))
response = sandbox.process.code_run("import pandas; print(pandas.__version__)")
```

```typescript
const snapshot = await daytona.snapshot.create({
    name: 'data-science',
    image: Image.debianSlim('3.12').pipInstall(['pandas', 'numpy', 'scikit-learn']),
})

const sandbox = await daytona.create({ snapshot: snapshot.name })
```

For the full `Image` builder API, see `./references/<lang>-sdk/declarative-builder.md`. For snapshot management, see `./references/<lang>-sdk/snapshots.md`.

### Long-running task pattern

```python
from daytona import Daytona

daytona = Daytona()
sandbox = daytona.create()

# ... clone repo, install deps, etc.

# Start a test suite in the background
sandbox.process.exec("nohup pytest --tb=short > /home/daytona/test.log 2>&1 &")

# Check progress later
response = sandbox.process.exec("tail -5 /home/daytona/test.log")
print(response.result)

# Download the full report when done
report = sandbox.fs.download_file("/home/daytona/test.log")
```

### Preview URLs

Sandboxes expose HTTP services via preview URLs. Previews are token-authenticated by default, or public if `public=True` (Python) / `public: true` (TypeScript) at sandbox creation.

- **Token-authenticated** — returns `.url` and `.token` (send as `x-daytona-preview-token` header)
  - Python: `sandbox.get_preview_link(port)` | TypeScript: `sandbox.getPreviewLink(port)` | Go: `sandbox.GetPreviewLink(port)` | Ruby: `sandbox.get_preview_link(port)`
- **Signed URL (shareable)** — token embedded in URL, no headers needed
  - Python: `sandbox.create_signed_preview_url(port, expires_in_seconds=3600)` | TypeScript: `s