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

# E2B

> Run captured programs in an E2B cloud sandbox, one Mirage starts for the workspace or one you created.

The `e2b` machine provider runs the programs it captures in an
[E2B](https://e2b.dev) sandbox. Leave out `sandbox_id` and Mirage starts a
sandbox from `template` when the first program needs one, pauses it when the
workspace has no work there, and kills it when the workspace is deleted.
Give `sandbox_id` and Mirage runs programs in your sandbox and leaves its
lifetime to you. Python SDK, Node and browsers.

## Installation

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

> [tab] TypeScript
>
> ```bash theme={null}
> pnpm add e2b ssh2
> ```

The `ssh` extra and `ssh2` serve the workspace into the sandbox with
`mount_type: ssh`; see [connecting the workspace](#connecting-the-workspace).
Set `api_key`
in the config, as a value or a [credential pointer](https://docs.mirage.strukto.ai/home/service-credentials.md#pointer-fields),
or `E2B_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. Without `sandbox_id`, the first program starts
the sandbox; Mirage's own commands start none.

> [tab] Python
>
> ```python theme={null}
> from mirage import RAMVFS, MountMode, Workspace
>
> ws = Workspace(
>     {"/data": RAMVFS()},
>     mode=MountMode.EXEC,
>     machines={
>         "sandbox": {
>             "provider": "e2b",
>             "mount_type": "ssh",
>             "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: { sandbox: { provider: 'e2b', mountType: 'ssh', captures: ['@python', '@external'] } },
>   },
> )
> await ws.shell("python3 -c 'print(1 + 1)'")
> ```
>
> In a browser, import `@struktoai/mirage-core/machine/e2b/handle` once
> to register the provider (`pnpm add @struktoai/mirage-core`), pass
> `apiKey`, and use `mountType: 'own'` or leave it unset.

> [tab] YAML
>
> ```yaml theme={null}
> mode: exec
> machines:
>   sandbox:
>     provider: e2b
>     mount_type: ssh
>     captures: ["@python", "@external"]
> mounts:
>   /data:
>     vfs: ram
> ```

## Connecting the workspace

Pick a [`mount_type`](https://docs.mirage.strukto.ai/home/setup/machine/overview#connecting-the-workspace). `ssh`, `mirage` and `both` do not work in browsers. Under
`ssh` each file call is about 150 ms for a small file from a laptop; under
`mirage`, files on `ram` and `sql` mounts stay cached in the sandbox once
read, unless a policy judges the session's file calls, and E2B's `base`
template is enough: it has `fuse3` and `npm`, and Mirage installs
[`mirage-fuse`](https://docs.mirage.strukto.ai/home/setup/machine/overview#mirage) there the first time. With `own`,
base the template on [the machine image](https://docs.mirage.strukto.ai/home/setup/machine/overview.md#the-machine-image)
and run `mirage workspace create /tmp/sandbox.yaml` in the sandbox.

### sshfs for ssh

`ssh` needs `sshfs` in the sandbox. One that lacks it gets it from
its package manager as the workspace is first served, as root or through
`sudo` without a password, with `apt-get`, `apk`, `dnf` or `yum`. E2B's
default template takes about 3 seconds, once per sandbox. Where that cannot
work, the line fails with what to install. To skip the install, build a
template with `sshfs` and name it as `template`, or create your sandbox from
it and pass its ID as `sandbox_id`:

> [tab] Python
>
> ```python theme={null}
> from e2b import AsyncSandbox, Template
>
> Template.build(Template().from_base_image().apt_install("sshfs"), "mirage-sshfs")
> sandbox = await AsyncSandbox.create("mirage-sshfs", timeout=3600)
> print(sandbox.sandbox_id)
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Sandbox, Template } from 'e2b'
>
> await Template.build(Template().fromBaseImage().aptInstall('sshfs'), 'mirage-sshfs')
> const sandbox = await Sandbox.create('mirage-sshfs', { timeoutMs: 3_600_000 })
> console.log(sandbox.sandboxId)
> ```

Keep the base image's user, which has `sudo` for mountpoints such as
`/data`.

## A sandbox Mirage starts

Without `sandbox_id`, the first program that needs the sandbox starts one
from `template` (E2B's `base` when unset). The workspace keeps its ID in its
state, so a later build of the same workspace reaches the same sandbox, and
one that is gone is started anew.

While Mirage has work there, a program's run or one of its own lines, the
sandbox's E2B timeout is 10 minutes, pushed out every 5 minutes while the
work lasts. Once the last of it ends, the timeout is `idle_timeout` seconds,
10 when unset, after which E2B pauses the sandbox: its disk and memory are
kept and its compute is not billed. Mirage's own commands on the
workspace's files run while it stays paused. The next program resumes it,
which takes about a second, and serves the workspace into it again:

```yaml theme={null}
machines:
  sandbox:
    provider: e2b
    template: my-template
    idle_timeout: 30
    mount_type: ssh
```

Closing the workspace pauses the sandbox; deleting the workspace kills it.
A process a program left running on its own, outside the line's job, is
paused with the sandbox and goes on when it resumes.

## A sandbox you bring

The timeout you give the sandbox at creation, one hour above, sets when it
ends. Mirage never kills your sandbox or sets its timeout. Reaching a
sandbox resumes it if it is paused and keeps it alive at least 5 more
minutes, as any E2B connect does, so reaching it near the end moves the end
back. Closing the workspace leaves the sandbox running.

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

```yaml theme={null}
machines:
  sandbox:
    provider: e2b
    sandbox_id: ${E2B_SANDBOX_ID}
    on_pause: pause
```

`workspace.pause()` closes the workspace, then pauses the sandbox: its disk
and memory are kept and E2B stops billing its compute. The next line's
connect resumes it, with at least 5 more minutes. Mirage pauses only a
sandbox the workspace reached, and a sandbox that is already gone counts as
paused. A pause interrupts anything else running in the sandbox, so leave
`on_pause` unset when the sandbox is shared. Without it, `workspace.pause()`
leaves the sandbox running, as `close()` does, unless the call names the
machine (`pause(machines=["sandbox"])`), which pauses it whatever its config says.
`pause` is the only value.

Once the sandbox has ended, a line exits 1, and its error names the fix:

```text theme={null}
sandbox sb-123 is not running: it was killed or reached its timeout; create a new sandbox and set the machine's sandbox_id to it
```

A line that is running when the sandbox ends exits 129. Create a new sandbox
from the same template, set the machine's `sandbox_id` to its ID, and create
the workspace again.

## Notes

* With `mount_type: ssh`, `mirage` or `both`, a workspace that restarts with the
  same workspace ID takes back the mounts it left in the sandbox. Give
  each live workspace its own ID: two live workspaces with one ID take
  each other's mounts.
* 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.
* Commands run concurrently, each with its own input and output. Without
  piped input, stdin starts closed.
* Template contents, sizing and networking stay E2B settings.
* A Mirage [timeout](https://docs.mirage.strukto.ai/home/setup/machine/overview.md#timeouts) tries to kill the command; its child
  processes may survive.


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