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
- Python
- TypeScript
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.
- Python
- TypeScript
- YAML
Connecting the workspace
Pick amount_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:
- Python
- TypeScript
sudo for mountpoints such as
/data.
A sandbox Mirage starts
Withoutsandbox_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:
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, seton_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:
sandbox_id to its ID, and create
the workspace again.
Notes
- With
mount_type: ssh,mirageorboth, 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
ddandbase64(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.