Bring Node sandbox features in line with Python SDK - #122
Merged
Merged
Conversation
Add remote/local image builds (Dockerfile context manifests, Docker image manifests, deterministic fingerprints, ready-image reuse and build joining), streamed process start with complete output collection, configurable image builder resources, and transient GET retries on the control transport.
|
I'll fix CI failures and address comments from users with write access. I'll skip comments containing "(aside)".
|
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
Contributor
Author
|
@claude review this PR thoroughly and find any problems with it |
Collected output now survives the replay window on the original handle (410 only applies to a re-attached handle), local wait timeouts raise wait_timeout, and snapshot list limits respect the server's 100 maximum.
…ty' into codex/sandbox-parity-pr122 # Conflicts: # tests/sandbox/e2e/process.test.ts
Dingway98
changed the title
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes using default effort and found 2 potential issues.
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit 6c67ce7. Configure here.
Dingway98
changed the title
Dingway98
approved these changes
Sep 28, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Bring Node sandbox functionality in line with Python SDK 1.9.1. Commands collect complete output from the initial stream and report incomplete output explicitly. Image helpers support remote Dockerfile builds, local Docker imports, deterministic identities, cache reuse, and joining compatible builds.
Add streaming file transfers, resumable watch handles, snapshot startup, runtime sessions, and consistent request deadlines, cancellation, retries, and cleanup. Preserve existing Node APIs and gVisor support. Public helpers and handles are available through root and subpath exports. Tests are organized into unit, local integration, and live E2E projects in one Vitest config; default and watch commands run only local tests.
Validation
Live volume tests are excluded by request; local volume contracts remain covered. Windows and additional Docker versions are unverified. Python-specific Pydantic models and sync/async entry points use native TypeScript contracts and Promises.
Streamed command starts require receiver support. Nullable response types and local launch validation can require consumer updates; release as the next minor version. This PR does not publish a package.
Note
High Risk
Large changes to sandbox runtime transport, process/file streaming, and new image-build upload paths; behavior and nullable API shapes may break consumers expecting the old request/response exec model.
Overview
This PR brings the Node sandbox client toward parity with the Python SDK: streaming process execution, image build/reuse, streaming files and watches, plus clearer errors, retries, and test layout.
Processes:
exec()andprocesses.start()now open a single SSE stream from process start and collect full stdout/stderr locally (withmaxOutputBytes, sequence checks, and structured errors). Localwait()timeouts do not stop collection;disconnect()/AbortSignalstop local collection without killing the remote process.RuntimeTransportgainsopenSSE(including POST starts), read-idle timeouts, and binarystreamBytes.Files & watches: Adds
uploadStream/downloadStream, publicSandboxFileWatchHandlewithrefresh, resumableevents()(ws/stream routes),getWatch, renameoverwrite, and convenience aliases (stat,mkdir,move,delete).Image builds: New
@hyperbrowser/sdk/image-builds(and root exports) for Dockerfile context fingerprinting/packaging,.dockerignorematching, locallinux/amd64Docker import via CLI, deterministicimageBuildName, artifact upload, and sandboxes helpers such asgetOrBuildImage()with reuse/join/create flows (documented in README).Platform:
HyperbrowserErrormoves toerror.tswith optionalmethod/path; control-plane GETs retry 429/5xx and transient network errors;HYPERBROWSER_BASE_URLoverrides the API base. Package addsengines(Node ≥20.20.2),typecheck, subpath exports forsandbox/image-builds, and Vitest unit / integration / e2e projects so defaultyarn testneeds no API key or Docker.Reviewed by Cursor Bugbot for commit 156b495. Bugbot is set up for automated code reviews on this repo. Configure here.