From d7f676b2b66505497f6f9ed6788f67e1cd8f5ec7 Mon Sep 17 00:00:00 2001
From: Anas Khan <anxkhn28@gmail.com>
Date: Tue, 14 Jul 2026 19:45:25 +0530
Subject: [PATCH] fix(js-sdk): use commands.run in Sandbox.getHost() example
 (#1531)

The JSDoc `@example` on the public `Sandbox.getHost()` method calls
`sandbox.commands.exec(...)`, but the `Commands` class has no `exec`
method. It
exposes `run`. Copy-pasting the documented snippet therefore throws:

```
TypeError: sandbox.commands.exec is not a function
```

### Where

`packages/js-sdk/src/sandbox/index.ts`, in the `getHost()` doc comment:

```ts
/**
 * ...
 * @example
 * ```ts
 * const sandbox = await Sandbox.create()
 * // Start an HTTP server
 * await sandbox.commands.exec('python3 -m http.server 3000')  // <- no such method
 * // Get the hostname of the HTTP server
 * const serverURL = sandbox.getHost(3000)
 * ```
 */
```

The `Commands` class (`packages/js-sdk/src/sandbox/commands/index.ts`)
exposes
`list`, `sendStdin`, `closeStdin`, `kill`, `connect`, and `run` (four
`run`
overloads), plus a private `start`. There is no `exec`. The correct
method here
is `run`, which is what every other example already uses, including the
sibling
`@example` in this same file (the `commands.run(...)` snippet a few
methods up)
and both Python SDK mirrors (`get_host` in `sandbox_sync/main.py` and
`sandbox_async/main.py` already use `commands.run`).

### Fix

One token, `exec` -> `run`:

```ts
- await sandbox.commands.exec('python3 -m http.server 3000')
+ await sandbox.commands.run('python3 -m http.server 3000')
```

Documentation only. No behavior or type change.

### Parity with the Python SDK

The repo guidelines ask that SDK changes be mirrored across the JS and
Python
SDKs. Here the Python `get_host` examples already use `commands.run`
correctly,
so this defect exists only in the JS SDK doc comment and no Python
change is
needed to reach parity.

### Tests

This is a JSDoc `@example` correction with no runtime code path to
exercise, so
it adds no test, matching the repo's existing precedent for
documentation-only
fixes (e.g. `.changeset/sandbox-list-docstring.md`, and merged doc-fix
PRs such
as #1511 / #1500 / #1260, none of which added a regression test).
Correctness is
that the example now names the real public API: after the change,
`commands.exec`
no longer appears anywhere in the SDK source, and `commands.run` matches
the
`Commands` class and the sibling examples.

Offline gates run locally (Node 20, pnpm 9.15.5):

```
pnpm --filter e2b run lint        # oxlint, clean
pnpm --filter e2b run typecheck   # tsc --noEmit, clean
pnpm --filter e2b run build       # tsc + tsup, ESM/CJS/DTS built
prettier --check src/sandbox/index.ts  # clean
```

A changeset (`e2b`, patch) is included.

---

## Linked issues

- None. There is no existing GitHub issue for this; it is a self-evident
public
doc-example defect (the documented snippet throws at runtime). Not
filing a
  separate issue for a one-token doc fix.

## Pre-flight checklist (repo AGENTS.md / CLAUDE.md gates)

- [x] `pnpm run format` - `prettier --check` clean on the changed file
- [x] `pnpm run lint` - oxlint clean (exit 0)
- [x] `pnpm run typecheck` - tsc --noEmit clean (exit 0)
- [x] `pnpm run build` - tsc + tsup clean
- [x] Changeset generated - `.changeset/fix-gethost-example-command.md`
(`e2b`: patch)
- [x] Conventional Commit message (`fix(js-sdk): ...`, reuses `js-sdk`
scope)
- [ ] Test added - not applicable (doc-only `@example`; see Tests
section for precedent)
- [ ] DCO / CLA - no sign-off required by this repo; CLA is signed via
`@cla-bot`
      on the PR after opening (as on prior PRs #1518 / #1519 / #1507)

Signed-off-by: Anas Khan <83116240+anxkhn@users.noreply.github.com>
---
 .changeset/fix-gethost-example-command.md | 5 +++++
 packages/js-sdk/src/sandbox/index.ts      | 2 +-
 2 files changed, 6 insertions(+), 1 deletion(-)
 create mode 100644 .changeset/fix-gethost-example-command.md

diff --git a/.changeset/fix-gethost-example-command.md b/.changeset/fix-gethost-example-command.md
new file mode 100644
index 0000000000..e2c2f8c556
--- /dev/null
+++ b/.changeset/fix-gethost-example-command.md
@@ -0,0 +1,5 @@
+---
+"e2b": patch
+---
+
+Fix the `Sandbox.getHost()` documentation example so it can be copy-pasted. The `@example` called `sandbox.commands.exec(...)`, which is not a method on the `Commands` class (it exposes `run`), so running the snippet threw `TypeError: sandbox.commands.exec is not a function`. It now uses `sandbox.commands.run(..., { background: true })`, allowing the long-running HTTP server to start before the example calls `getHost()`. Documentation only, no behavior change.
diff --git a/packages/js-sdk/src/sandbox/index.ts b/packages/js-sdk/src/sandbox/index.ts
index 56caea6300..41b233043b 100644
--- a/packages/js-sdk/src/sandbox/index.ts
+++ b/packages/js-sdk/src/sandbox/index.ts
@@ -425,7 +425,7 @@ export class Sandbox extends SandboxApi {
    * ```ts
    * const sandbox = await Sandbox.create()
    * // Start an HTTP server
-   * await sandbox.commands.exec('python3 -m http.server 3000')
+   * await sandbox.commands.run('python3 -m http.server 3000', { background: true })
    * // Get the hostname of the HTTP server
    * const serverURL = sandbox.getHost(3000)
    * ```