> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Daytona

> Run captured programs in a Daytona cloud sandbox you created.

The `daytona` machine provider reaches a running
[Daytona](https://www.daytona.io) sandbox, by ID, and runs the programs it
captures in it. You create and size the
sandbox; Mirage only runs programs in it. Python SDK and Node.

## Installation

> [tab] Python
>
> ```bash theme={null}
> pip install 'mirage-ai[daytona]'
> ```

> [tab] TypeScript
>
> ```bash theme={null}
> pnpm add @daytonaio/sdk
> ```

Boot the sandbox from an image or snapshot that has what
[connecting the workspace](#connecting-the-workspace) needs.
Set `api_key` in the config, or `DAYTONA_API_KEY`.

## Usage

`captures` defaults to [`@external`](https://docs.mirage.strukto.ai/home/setup/machine/overview#captures):
every program Mirage does not have itself. Name `@python` to run
Python in the sandbox too.

> [tab] Python
>
> ```python theme={null}
> from mirage import RAMVFS, MountMode, Workspace
>
> ws = Workspace(
>     {"/data": RAMVFS()},
>     mode=MountMode.EXEC,
>     machines={"box": {"provider": "daytona", "sandbox_id": "sandbox-id", "captures": ["@python", "@external"]}},
> )
> await ws.shell("python3 -c 'print(1 + 1)'")
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { MountMode, RAMVFS, Workspace } from '@struktoai/mirage-node'
>
> const ws = new Workspace(
>   { '/data': new RAMVFS() },
>   {
>     mode: MountMode.EXEC,
>     machines: { box: { provider: 'daytona', sandboxId: 'sandbox-id', captures: ['@python', '@external'] } },
>   },
> )
> await ws.shell("python3 -c 'print(1 + 1)'")
> ```

> [tab] YAML
>
> ```yaml theme={null}
> mode: exec
> machines:
>   box:
>     provider: daytona
>     sandbox_id: ${DAYTONA_SANDBOX_ID}
>     captures: ["@python", "@external"]
> mounts:
>   /data:
>     vfs: ram
> ```

## Connecting the workspace

Mirage does not serve mounts into a Daytona sandbox. Use
[the machine image](https://docs.mirage.strukto.ai/home/setup/machine/overview.md#the-machine-image) and the
[`fuse` steps](https://docs.mirage.strukto.ai/home/setup/machine/overview#fuse), then start Mirage in the
sandbox:

```bash theme={null}
mirage workspace create /tmp/sandbox.yaml
```

## Pausing the sandbox

To pause the sandbox when the workspace pauses, set `on_pause: pause` on the
machine:

```yaml theme={null}
machines:
  box:
    provider: daytona
    sandbox_id: ${DAYTONA_SANDBOX_ID}
    on_pause: pause
```

`workspace.pause()` closes the workspace, then pauses the sandbox: Daytona
keeps its disk and memory, and it uses no CPU while paused. The next line's
connect starts it again. Daytona pauses only VM sandboxes; for any other,
`workspace.pause()` raises Daytona's error and the sandbox keeps running.
Without `on_pause`, `workspace.pause()` leaves the sandbox running unless the
call names the machine. See [Pause](https://docs.mirage.strukto.ai/home/setup/machine/overview.md#pause).

## Notes

* Stopping or closing the workspace leaves the sandbox running.
* Daytona's exec takes no input, so a line given piped input, or a program
  that reads a `<(...)`, exits 126 before it runs, with
  `mirage: daytona:<name>: the machine takes no input`.
* Output comes back as the program wrote it, binary included: the
  sandbox base64-encodes it on the way out, so the image needs `dd` and
  `base64` (Debian, Ubuntu and Alpine images have both), and output
  takes about a third more to transfer. Without them a line runs
  nothing, prints why and exits 127.
* Sizing, GPUs, snapshots, networking, idle-stop and auto-delete stay
  Daytona settings. The
  [Daytona example](https://github.com/strukto-ai/mirage/tree/main/examples/python/machine/daytona)
  covers baking a snapshot and a full read and write round trip.
* A Daytona sandbox has no timeout of its own. After a Mirage
  [timeout](https://docs.mirage.strukto.ai/home/setup/machine/overview.md#timeouts), Python stops the
  program; in TypeScript it keeps running and billing until you stop it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.