Skip to main content
The e2b machine provider runs the programs it captures in an E2B 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

The ssh extra and ssh2 serve the workspace into the sandbox with mount_type: ssh; see connecting the workspace. Set api_key in the config, as a value or a credential pointer, or E2B_API_KEY.

Usage

captures defaults to @external: 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.

Connecting the workspace

Pick a mount_type. 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 there the first time. With own, base the template on 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:
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:
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:
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:
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 tries to kill the command; its child processes may survive.