Migrate from E2B

This page is for code that creates E2B sandboxes and runs commands, code and files in them. Most calls keep their shape: the TypeScript SDK uses the same Sandbox object, and the Python SDK uses a Client. Read the gaps first if your code uses run_code results, file watching, or sandboxes that delete themselves after a timeout.

What maps to what

E2B	InstaBox Python (`instabox-sdk`)	InstaBox TypeScript (`@insforge/instabox-sdk`)
`E2B_API_KEY`	`INSTABOX_API_KEY`	`INSTABOX_API_KEY`
`Sandbox.create(template)`	`client.machines.create(template=...)`	`Sandbox.create(template, opts)`
`metadata={...}` on create	`metadata={...}`	`{ metadata }`
`envs={...}` on create	`env=` on each `exec`	`{ envs }` on create (added to each `commands.run`)
`sbx.commands.run(cmd)`	`client.machines.exec(box.id, cmd)`	`sbx.commands.run(cmd)`
`commands.run(cmd, background=True)`	`exec(box.id, "nohup cmd >log 2>&1 &")`	`commands.run(cmd, { background: true })`
`sbx.run_code(code)` (code interpreter)	`exec(box.id, "python3 -", stdin=code)`	`commands.run('python3 -', { stdin: code })`
`sbx.files.write`, `read`, `list`	`client.files.write`, `read`, `list`	`sbx.files.write`, `read`, `list`
`sbx.files.remove`, `exists`	`client.files.remove`, `exists`	`sbx.files.remove`, `exists`
`sbx.files.watch_dir`	none, see gaps	none
`sbx.get_host(port)`	`POST /v1/machines/{id}/ports` (no SDK call)	`(await sbx.ports.publish(port)).url`
`sbx.pause()`	`client.machines.pause(box.id)`	`sbx.pause()`
`Sandbox.connect(id)` (resumes)	`client.machines.ensure_running(id)`	`Sandbox.connect(id)`
`Sandbox.list()`	`client.machines.list(metadata=...)`	`Sandbox.list({ metadata })`
`sbx.kill()`	`client.machines.delete(box.id)`	`sbx.kill()`
`timeout` on create, `set_timeout`	`delete_after_seconds` or `archive_seconds` on create	`archiveMs` on create
`e2b.Dockerfile`, `e2b template build`	push the image, `instabox snapshot import`, then `create(snapshot_id=...)`	the same import, then `Sandbox.create('<snapshot name>')`
home directory `/home/user`	`/data/home` (HOME)	`/data/home` (HOME)

Move your code

Install the SDK and set the key

Create a key on API keys in the dashboard, with machines:write and machines:delete. To bring your E2B template (below), also give it images:read and images:write. Full access covers all of them. See API keys.

pip install instabox-sdk          # Python, imports as instabox
npm install @insforge/instabox-sdk@^0.8.0   # TypeScript; ports.publish needs 0.8.0
export INSTABOX_API_KEY=ibk_...

Create the machine

E2B creates a sandbox that lives for its timeout. An InstaBox machine lives until you delete it, and pauses after idle minutes on its own. create waits until the machine runs.

from instabox import Client

client = Client()  # reads INSTABOX_API_KEY
box = client.machines.create(metadata={"user": "u_123"}, delete_after_seconds=3600)
print(box.id)  # m_...

import { Sandbox } from '@insforge/instabox-sdk'

const sbx = await Sandbox.create('agent-browser', { metadata: { user: 'u_123' } })
console.log(sbx.sandboxId) // m_...

The default template, agent-browser, has Linux, Python 3, Node.js, a desktop and a browser. To start from your own image, see Use your E2B template.

Run commands and code

r = client.machines.exec(box.id, "echo $GREETING", env={"GREETING": "hi"})
print(r.stdout, r.exit_code)   # hi 0; a non-zero exit is a result, not an error

code = "import platform\nprint(platform.python_version())"
r = client.machines.exec(box.id, "python3 -", stdin=code)  # in place of run_code
print(r.stdout)

const r = await sbx.commands.run('echo $GREETING', { envs: { GREETING: 'hi' } })
console.log(r.stdout, r.exitCode) // a non-zero exit throws CommandExitError

const code = 'import platform\nprint(platform.python_version())'
const out = await sbx.commands.run('python3 -', { stdin: code }) // in place of runCode
console.log(out.stdout)

In Python, exec returns a non-zero exit code in r.exit_code. In TypeScript, commands.run throws on it, as E2B does. A command stops after timeout seconds (60 by default, 600 at most).

Move files

client.files.write(box.id, "/data/home/data.csv", "a,b\n1,2\n")
print(client.files.read(box.id, "/data/home/data.csv"))
print([e.name for e in client.files.list(box.id, "/data/home")])

await sbx.files.write('/data/home/data.csv', 'a,b\n1,2\n')
console.log(await sbx.files.read('/data/home/data.csv'))
console.log((await sbx.files.list('/data/home')).map((e) => e.name))

Paths are absolute. Use /data/home where your E2B code used /home/user. Files under /data survive a stop.

Give a port a URL

E2B’s get_host(port) returns a host name. On InstaBox, publish the port once. The result has the URL, https://<port>-<machine id without m_>.<domain>. A port is public by default, as on E2B.

import os, httpx

client.machines.exec(box.id, "nohup python3 -m http.server 8000 >/tmp/http.log 2>&1 &")
api = os.environ.get("INSTABOX_API_URL", "https://api.instabox.sh")
r = httpx.post(  # the Python SDK has no ports call yet
    f"{api}/v1/machines/{box.id}/ports",
    headers={"X-API-Key": os.environ["INSTABOX_API_KEY"]},
    json={"port": 8000},
)
r.raise_for_status()
url = r.json()["url"]

await sbx.commands.run('python3 -m http.server 8000', { background: true })
const { url } = await sbx.ports.publish(8000)

Ports 1024 to 65535 can be published, up to 16 per machine. For a URL only people with a link can open, publish it private: sbx.ports.publish(8000, { access: 'private' }) in TypeScript, or "access": "private" in the Python request. A private port’s plain url answers 401. Share the response’s tokenUrl instead, the URL with the token as ?_token=. Only the publish that creates or rotates the token returns tokenUrl, so keep it, or publish again with rotateToken: true for a new one. See Public and private ports.

Pause, resume and delete

client.machines.pause(box.id)            # memory and processes are kept
box = client.machines.ensure_running(box.id)
client.machines.delete(box.id)

await sbx.pause()
const again = await Sandbox.connect(sbx.sandboxId) // resumes it, as on E2B
await again.kill()

Use your E2B template

An E2B template is built from a Dockerfile. Build the same Dockerfile with Docker, push it to a registry, and import it as a snapshot. The import needs a key with images:write, and creating from the snapshot by name needs images:read, as well as the machine scopes from the first step.

docker build -t ghcr.io/you/my-template:1 -f e2b.Dockerfile .
docker push ghcr.io/you/my-template:1
npx instabox snapshot import ghcr.io/you/my-template:1 --name my-template   # waits until it is saved

Then create machines from the snapshot. It is a snapshot, not a template: in Python, look it up by name and pass its ID. In TypeScript, Sandbox.create takes the snapshot name and looks it up.

snap = next(s for s in client.snapshots.list() if s.name == "my-template")
box = client.machines.create(snapshot_id=snap.id)

const fromImage = await Sandbox.create('my-template') // a snapshot name, or its ID (sn_...)

Only linux/amd64 images work. The image’s ENV reaches every command, and its CMD runs as a service. See Custom images.

What has no direct equivalent

E2B	On InstaBox
`run_code` with a stateful Jupyter kernel and rich `results` (charts, tables)	Not available. Each `python3 -` run is a new process. To keep state, write it to a file, or run your own kernel or server in the machine and call it. Read text from `stdout`.
`files.watch_dir`	Not available. Poll `files.list`, or run `inotifywait -m` as a background command and read its log.
A sandbox that is deleted when its timeout ends	Python: `delete_after_seconds` on create deletes it. TypeScript: `archiveMs` stops it and keeps its disk; call `kill()` to delete.
`set_timeout` after create	Not available as a deadline. Idle machines pause on their own. To change the idle time, call `client.machines.update(box.id, auto_suspend_after_seconds=...)` (paid plans).
`get_host` in the Python SDK	No Python call. Use `POST /v1/machines/{id}/ports`, the CLI `instabox port publish`, or `instabox-port publish` inside the machine. TypeScript has `sbx.ports.publish(port)`.
Port URLs for ports below 1024	Not available. Serve on 1024 or higher.

Migrate with your coding agent

Paste this prompt into your coding agent in the repository that uses E2B:

Migration prompt

Migrate this repository from E2B sandboxes to InstaBox machines.

1. Find every use of the e2b, e2b-code-interpreter, @e2b/code-interpreter or e2b npm/pip packages,
   E2B_API_KEY, and e2b.Dockerfile. List the files before changing anything.
2. Replace the SDK:
   - Python: pip install instabox-sdk; `from instabox import Client`; `client = Client()`.
   - TypeScript: npm install @insforge/instabox-sdk@^0.8.0; `import { Sandbox } from '@insforge/instabox-sdk'`.
   - The key is INSTABOX_API_KEY (an ibk_ key), never E2B_API_KEY. It needs machines:write and
     machines:delete, plus images:read and images:write if the repo has an e2b.Dockerfile.
3. Map the calls:
   - Sandbox.create() with E2B's default template -> Python client.machines.create(metadata=...);
     TypeScript Sandbox.create('agent-browser', { metadata, envs }).
   - Sandbox.create(<your custom template>) -> an imported snapshot (see the e2b.Dockerfile step):
     Python `snap = next(s for s in client.snapshots.list() if s.name == "<name>")`, then
     client.machines.create(snapshot_id=snap.id); TypeScript Sandbox.create('<name>', { ... }).
     Never pass a snapshot name as Python's template=: the server answers 400 unknown template.
   - sbx.commands.run(cmd) -> Python client.machines.exec(box.id, cmd) (exit code in r.exit_code,
     no exception); TypeScript sbx.commands.run(cmd) (throws CommandExitError on a non-zero exit).
   - run_code(code) -> run "python3 -" with the code as stdin. There is no Jupyter kernel: each run is
     a new process, and only stdout and stderr come back.
   - sbx.files.write/read/list/remove/exists -> client.files.<same>(box.id, path, ...) in Python,
     sbx.files.<same>(path, ...) in TypeScript.
   - Paths under /home/user -> /data/home.
   - sbx.get_host(port) -> TypeScript: `const { url } = await sbx.ports.publish(port)` for a public
     port. For a link-only port, `const { tokenUrl } = await sbx.ports.publish(port, { access: 'private' })`
     and share tokenUrl: the plain url answers 401. Python has no ports call: POST
     $INSTABOX_API_URL/v1/machines/{id}/ports (default https://api.instabox.sh) with {"port": N}
     (add "access": "private" for a link-only port) and the X-API-Key header, raise on an error
     status, and use the "url" field, or "tokenUrl" for a private port. tokenUrl comes back only
     from the publish that creates or rotates the token ("rotateToken": true). Ports must be 1024
     to 65535.
   - sbx.pause() -> client.machines.pause(box.id) / sbx.pause(); Sandbox.connect(id) ->
     client.machines.ensure_running(id) / Sandbox.connect(id).
   - Sandbox.list() -> client.machines.list(metadata=...) / Sandbox.list({ metadata }).
   - sbx.kill() -> client.machines.delete(box.id) / sbx.kill().
   - timeout on create -> Python delete_after_seconds=...; TypeScript archiveMs (stops, does not delete).
   - e2b.Dockerfile -> docker build and push the image (linux/amd64), then
     `npx instabox snapshot import <image> --name <name>` with a key that has images:write. It waits
     until the snapshot is saved. Create from it as in the custom-template mapping above.
4. Stop and ask me before working around any of these, which have no direct equivalent:
   a stateful run_code kernel or its rich results (charts, tables, display data), files.watch_dir,
   set_timeout after create, and port URLs below port 1024.
5. Run the project's tests and its example scripts against InstaBox with INSTABOX_API_KEY set.
   Delete every machine the tests create. Report what you changed, what you could not map, and the
   test results.

Troubleshooting

401 missing_api_key

INSTABOX_API_KEY is not set in the process that runs the code. E2B’s E2B_API_KEY is not read.

429 rate_limited: sandbox start limit reached

Each workspace may start only a set number of machines a minute; the free plan allows the fewest. A create counts, and so does a resume, including Sandbox.connect and ensure_running on a paused machine. Code that created many short-lived E2B sandboxes in a loop hits this first. Retry only when the error’s code is rate_limited: wait a minute and retry, or reuse one machine across jobs instead of creating one per job. Another 429, such as quota_exceeded, does not clear by waiting, so do not retry it. See Limits.

403 missing_scope

The key lacks a scope the call needs. snapshot import needs images:write, and creating from a snapshot by name (or client.snapshots.list()) needs images:read. Create a key with those scopes added, or with Full access. See API keys.

400 bad_request: unknown template, when creating from your imported image

An imported image is a snapshot, not a template. In Python pass snapshot_id=snap.id, not template=. See Use your E2B template.

403 template_not_allowed

The free plan creates only from some templates. A machine from your own imported snapshot is not limited. See Pricing.

The port URL answers 502 or 503

502: nothing listens on the port yet, or the server listens on 127.0.0.1 only. Listen on 0.0.0.0. 503: the machine is paused or stopped. A visit wakes a machine that paused itself.

A command fails with No such file or directory under /home/user

The home directory is /data/home. Change the path, or use paths relative to HOME in commands.

SDK quick start

Every TypeScript call, with curl.

Python SDK

Every Python call and error.

Get started

Use cases

Machines

Access

Security

Account

Reference

Migrate

What maps to what

Move your code

Use your E2B template

What has no direct equivalent

Migrate with your coding agent

Troubleshooting

SDK quick start

Python SDK

​What maps to what

​Move your code

​Use your E2B template

​What has no direct equivalent

​Migrate with your coding agent

​Troubleshooting

SDK quick start

Python SDK

What maps to what

Move your code

Use your E2B template

What has no direct equivalent

Migrate with your coding agent

Troubleshooting