The Problem
LLMs need a safe, isolated environment to execute code or interact with graphical applications. Existing sandbox solutions either expose the host OS, require heavyweight VM provisioning, or lack a simple API for streaming the desktop back to the model. This repo provides an open‑source virtual desktop that can be created, launched, and streamed from any LLM while keeping each instance isolated.
What This Does
The project is a thin wrapper around E2B’s cloud sandbox that boots a full XFCE desktop (see template/files/ for the XFCE config). Two SDKs expose the same surface:
packages/js-sdk/src/index.ts – JavaScript/TypeScript entry point. packages/python-sdk/e2bdesktop/main.py – Python package (e2bdesktop module).
Both implement Sandbox.create(), desktop.launch(), desktop.wait(), and a stream API for real‑time screen capture (see packages/js-sdk/src/sandbox.ts and packages/python-sdk/e2bdesktop/main.py). Example usage is demonstrated in examples/basic-javascript/index.js and examples/basic-python/main.py.
The desktop image is built from the template/ directory (Dockerfiles, pyproject.toml, and poetry.lock), then shipped as a lightweight container. React appears in the packages/js-sdk but is used only for the SDK’s internal UI, not the core sandbox.
How To Use It
Setup
API key – Sign up at <https://e2b.dev> and set the environment variable E2BAPIKEY. The key is read at runtime; no secret is stored in the repo. Install an SDK
Python
pip install e2b-desktop
JavaScript
npm install @e2b/desktop
(These commands correspond to the package.json at the root and pyproject.toml in packages/python-sdk.)
Create and run a sandbox – Python example (also in examples/basic-python/main.py):
from e2bdesktop import Sandbox
desktop = Sandbox.create() desktop.launch('google-chrome') desktop.wait(10000) authkey = desktop.stream.getauthkey() print('Stream URL:', desktop.stream.geturl(authkey=authkey)) …perform tasks… desktop.kill()
– JavaScript example (also in examples/basic-javascript/index.js):
import { Sandbox } from '@e2b/desktop'
const desktop = await Sandbox.create() await desktop.launch('google-chrome') await desktop.wait(10000) const authKey = desktop.stream.getAuthKey() console.log('Stream URL:', desktop.stream.getUrl({ authKey })) // …perform tasks… // await desktop.kill()
Configuration – The only required configuration is the E2BAPIKEY env var. The sandbox image is defined by template/pyproject.toml and template/poetry.lock; customizing dependencies would require editing those files and rebuilding the Docker image (see template/builddev.py, template/builddocker.py).
Real‑World Use
A common pattern is feeding a vision‑enabled LLM a live desktop stream so it can “look” at UI elements and issue commands (e.g., fill forms, click buttons). The SDK’s stream.start({requireAuth:true}) returns an auth key that the LLM can use to pull JPEG frames over HTTPS without embedding credentials. This enables scenarios such as automated browser testing, data‑entry assistants, or interactive code‑execution environments where the model must interact with a graphical stack.
Code Health & Issues
Tests & CI – 10 test files exist (packages/js-sdk/tests/, packages/python-sdk/tests/). GitHub Actions workflows (lint.yml, js-sdk-tests.yml, python-sdk-tests.yml, etc.) run on every pull request. License – LICENSE files are present at the root and in both SDK packages. Dependency hygiene – package-lock.json, poetry.lock, and pnpm-lock.yaml are committed, ensuring reproducible installs. Potential risk – The JS SDK’s src/sandbox.ts abstracts sandbox lifecycle but does not surface detailed error types; consumers may see generic exceptions when launch fails. The Python SDK similarly raises broad E2BError without granular codes. Adding typed error enums would improve developer ergonomics. No obvious secrets in code – The API key is expected from the environment, not checked into the repo, which is a good practice.
The Bottom Line
This repo delivers a minimal, SDK‑driven virtual desktop that LLMs can control safely and stream back. It’s well‑structured, has tests, CI, and clear licensing, making it suitable for teams building computer‑use agents or needing a sandboxed UI for model interaction. The main trade‑off is that error reporting could be more granular; otherwise it’s a solid starting point for secure desktop‑level LLM integration.