The Problem

LLMs need a safe, isolated environment to execute real‑world computer actions (opening apps, moving the mouse, taking screenshots). Without such a sandbox, any generated code runs on the host machine, exposing secrets and the file system. The repository provides a ready‑made virtual desktop that can be started, driven, and streamed from a language model while keeping the host isolated.

What This Does

The core implementation lives in packages/python-sdk/e2b_desktop/main.py and its counterpart packages/js-sdk/src/index.ts. These modules wrap the underlying E2B sandbox, expose high‑level operations such as launch, wait, and stream.start, and handle the VNC/Xfce stack needed for a graphical session. Example entry points are examples/basic-python/main.py (Python) and examples/basic-javascript/index.js (JavaScript), which demonstrate creating a sandbox, launching Chrome, waiting, and streaming the screen.

The Python SDK ships as the e2b-desktop package (see packages/python-sdk/package.json for the npm metadata and pyproject.toml for the Poetry configuration). The JavaScript SDK is packaged under @e2b/desktop with its own package.json, TypeScript source, and Vitest test suite. Both SDKs share the same runtime behavior but expose language‑specific APIs.

How It Is Wired

Execution begins at packages/python-sdk/e2b_desktop/main.py:144 in the start function. start builds a VNC server, generates a secret password via _generate_password (uses secrets.choice), and then calls a short chain of helpers: _wait_for_port, _check_vnc_running, and finally returns a Sandbox object. The object’s methods (launch, wait, stream.start) delegate to lower‑level functions such as move_mouse, screenshot, and right_click.

The internal call graph shows that move_mouse is the most referenced function (7 distinct callers). Functions like screenshot, right_click, and _wait_and_verify each have three callers, making them secondary hotspots. No circular dependencies were detected, so the dependency surface is predictable.

On the JavaScript side, packages/js-sdk/src/index.ts re‑exports the sandbox class and forwards calls to src/sandbox.ts. The most connected module in the JS test suite is packages/js-sdk/tests/setup (imports from three places, imports one module).

The only external effect is the cryptographic password generation (_generate_password) and three file‑system interactions (reading/writing temporary VNC config files). No database or network calls are made directly from the SDK; all network activity is limited to the E2B API endpoint configured by the user’s E2B_API_KEY.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/desktop.git
cd desktop

# Python SDK setup (uses Poetry)
poetry install        # installs e2b-desktop and test deps
# set required secret
export E2B_API_KEY=your_key_here

# Run the Python example
python examples/basic-python/main.py
# JavaScript SDK setup (uses pnpm)
pnpm install           # reads examples/basic-javascript/package.json
export E2B_API_KEY=your_key_here

# Run the JS example
node examples/basic-javascript/index.js

Both examples create a sandbox, launch google-chrome, wait 10 seconds, start a stream, and print a URL that can be opened in a browser. The SDKs expose the same methods, so swapping languages only changes the import path.

Real‑World Use

A conversational agent can import Sandbox from the Python SDK, call Sandbox.create(), and then issue desktop.launch('vscode'), desktop.wait(5000), and desktop.stream.start(require_auth=True). The agent receives the stream URL and can feed the video back to the LLM for visual feedback, while all actions remain confined to the isolated VNC session.

Code Health & Issues

  • High – Pin third‑party GitHub Actions – .github/workflows/*.yml use tag references (@v2.1.1, @v3). Replace with 40‑character commit SHAs.
  • High – Push directly to default branch – .github/workflows/publish_packages.yml runs git push. Change to push a bot branch and open a PR.
  • Medium – Least‑privilege GITHUB_TOKEN – .github/workflows/lint.yml declares no permissions. Add permissions: contents: read.
  • Medium – No dependency vulnerability scan – None of the CI workflows run a scanner. Add dependency-review-action or osv-scanner.
  • Medium – Checkout persists credentials – .github/workflows/js-sdk-tests.yml lacks persist-credentials: false. Add the flag.
  • Low – Missing job timeouts – Same workflow omits timeout-minutes. Define realistic limits.

Additional observations: tests exist for both SDKs, CI runs on GitHub Actions, a LICENSE file is present, and no secrets were found in the repository. The repo lacks a Dockerfile, so container builds must be added manually if required.

The Bottom Line

The project delivers a functional, language‑agnostic desktop sandbox with clear SDK boundaries and usable examples. Code health is solid but CI security practices need tightening. It is suitable for teams that want to let LLMs control a GUI in an isolated environment, provided they are comfortable adding the missing CI safeguards.