# Python SDK Reference

The Daytona Python SDK provides two clients for interacting with Daytona Sandboxes:

- **`Daytona`**: asynchronous client; methods are coroutines and must be awaited
- **`SyncDaytona`**: synchronous client with the same methods; each call blocks until it completes and returns `Sync*` handles such as `SyncSandbox`

## Installation

Install the Daytona Python SDK using pip:

```bash
pip install daytona
```

Or using poetry:

```bash
poetry add daytona
```

## Getting Started

### 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 SyncDaytona

    def main():
        # Initialize the SDK (uses environment variables by default)
        with SyncDaytona() as daytona:
            # Create a new sandbox
            sandbox = daytona.create()

            # Execute a command
            response = sandbox.process.run("echo 'Hello, World!'")
            print(response.stdout)

    if __name__ == "__main__":
        main()
    ```

    ```python
    import asyncio
    from daytona import Daytona

    async def main():
        # Initialize the SDK (uses environment variables by default)
        async with Daytona() as daytona:
            # Create a new sandbox
            sandbox = await daytona.create()

            # Execute a command
            response = await sandbox.process.run("echo 'Hello, World!'")
            print(response.stdout)

    if __name__ == "__main__":
        asyncio.run(main())
    ```

## Configuration

The Daytona SDK can be configured using environment variables or by passing a `DaytonaConfig` to the constructor. Values set in `DaytonaConfig` take precedence over environment variables. `api_key` and `api_url` are required; the client raises an error on construction if either is missing from both sources.

- `api_key`: your Daytona API key; falls back to `DAYTONA_API_KEY`
- `api_url`: URL of the Daytona API; falls back to `DAYTONA_API_URL`
- `target`: target [region](https://www.daytona.io/docs/en/v2/regions.md) for sandboxes; falls back to `DAYTONA_TARGET`
- `toolbox_url`: override for the toolbox proxy URL; falls back to `DAYTONA_TOOLBOX_URL`
- `request_timeout`: per-request HTTP timeout in seconds; `0` keeps the transport unbounded

    ```python
    from daytona import SyncDaytona, DaytonaConfig

    # Using environment variables (DAYTONA_API_KEY, DAYTONA_API_URL, DAYTONA_TARGET)
    daytona = SyncDaytona()

    # Using explicit configuration
    config = DaytonaConfig(
        api_key="YOUR_API_KEY",
        api_url="https://app.daytona.io/api",
        target="us"
    )
    daytona = SyncDaytona(config)
    ```

    ```python
    import asyncio
    from daytona import Daytona, DaytonaConfig

    async def main():
        # Using environment variables (DAYTONA_API_KEY, DAYTONA_API_URL, DAYTONA_TARGET)
        async with Daytona() as daytona:
            # Your code here
            pass

        # Using explicit configuration
        config = DaytonaConfig(
            api_key="YOUR_API_KEY",
            api_url="https://app.daytona.io/api",
            target="us"
        )
        async with Daytona(config) as daytona:
            # Your code here
            pass

    if __name__ == "__main__":
        asyncio.run(main())
    ```

For more information on configuring the Daytona SDK, see [authentication](https://www.daytona.io/docs/en/v2/authentication.md). See the [`DaytonaConfig` reference](https://www.daytona.io/docs/en/v2/python-sdk/daytona.md#daytonaconfig) for details.