sandbox: Add support for images - #252
Merged
Merged
Conversation
Adopt the Sandbox team's updated requirements by replacing the legacy runtime selector with image and using Sandbox API v3 for creation. Keep the Python SDK aligned with the JS SDK's custom-image design.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
There was a problem hiding this comment.
Pull request overview
This PR updates the vercel-sandbox Python SDK to support creating sandboxes from Vercel Container Registry (VCR) images via an image parameter, replacing the legacy runtime selector. It also migrates sandbox creation to the Sandbox API v3 and exposes the resolved image reference on returned sandbox handles.
Changes:
- Replace
runtimewithimageacross public sync/async sandbox creation APIs and internal plumbing, and exposeSandbox.image. - Switch sandbox creation requests from
POST /v2/sandboxestoPOST /v3/sandboxes. - Update tests, docs, and examples to reflect the new API and default image behavior.
Reviewed changes
Copilot reviewed 20 out of 20 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| src/vercel-sandbox/vercel/sandbox/sync.py | Public sync API now accepts image for sandbox creation and forwarding into internal runtime layer. |
| src/vercel-sandbox/vercel/sandbox/_internal/sync_runtime.py | Internal sync runtime entrypoints updated to pass image instead of runtime and remove runtime update support. |
| src/vercel-sandbox/vercel/sandbox/_internal/state.py | Replace stored sandbox runtime with image in returned state shapes. |
| src/vercel-sandbox/vercel/sandbox/_internal/service.py | Service layer forwards image into creation calls and keeps get-or-create semantics. |
| src/vercel-sandbox/vercel/sandbox/_internal/runtime_common.py | Public handle surface switches from .runtime to .image for sandbox handles. |
| src/vercel-sandbox/vercel/sandbox/_internal/async_runtime.py | Internal async runtime entrypoints updated for image creation and remove runtime update support. |
| src/vercel-sandbox/vercel/sandbox/_internal/api_client.py | Request/response models updated for image; create now targets v3/sandboxes; runtime fields removed from payloads. |
| src/vercel-sandbox/vercel/sandbox/init.py | Promoted async API updated to accept image and forward it to internals. |
| src/vercel-sandbox/tests/test_sandbox_public_flow.py | Expand/adjust public flow tests for v3 create endpoint, default image behavior, and image serialization/parity. |
| src/vercel-sandbox/tests/test_sandbox_process.py | Update process tests to create sandboxes via v3 endpoint and remove runtime usage. |
| src/vercel-sandbox/tests/test_sandbox_filesystem.py | Update filesystem tests to create sandboxes via v3 endpoint and remove runtime usage. |
| src/vercel-sandbox/tests/live/_sandbox_scenarios.py | Live scenarios no longer depend on specifying a runtime during sandbox creation. |
| src/vercel-sandbox/README.md | Document default image and add “Custom images” section with async/sync examples. |
| src/vercel-sandbox/examples/sandbox_06_streaming_files.py | Example no longer specifies runtime when creating sandboxes. |
| src/vercel-sandbox/examples/sandbox_05_sessions_and_resume.py | Example no longer specifies runtime when creating sandboxes. |
| src/vercel-sandbox/examples/sandbox_04_dev_server.py | Dev server example switches CLI/config from --runtime to --image. |
| src/vercel-sandbox/examples/sandbox_03_snapshot_restore.py | Example no longer specifies runtime when creating sandboxes. |
| src/vercel-sandbox/examples/sandbox_02_sync_script_runner.py | Example no longer specifies runtime when creating sandboxes. |
| src/vercel-sandbox/examples/sandbox_01_async_code_review.py | Example no longer specifies runtime when creating sandboxes. |
| changes/vercel-sandbox/201.breaking.md | News fragment documenting the breaking API change from runtime to image and v3 creation. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
The default directory behavior is different in the new base image.
ricardo-agz
approved these changes
Aug 7, 2026
nsidnev
added a commit
that referenced
this pull request
Aug 7, 2026
Release Packages vercel-internal-core -------------------- 0.1.2 - 2026-08-07 ------------------ Internal -------- - Key session service options by logical service so synchronous and asynchronous variants share configuration safely. (#242) - Absorb `typeutils` from `vercel-queue`: the annotation predicates and runtime forward-reference resolution now live in `vercel._internal.core.typeutils`, where more than one package can reach them. (#261) vercel-oidc ----------- 0.8.0 - 2026-08-07 ------------------ Features -------- - Add OIDC token signature verification. `vercel.oidc.verify_vercel_oidc_token` and its async twin `vercel.oidc.aio.verify_vercel_oidc_token` verify a Vercel OIDC token against the JWKS at `oidc.vercel.com`, pinning the issuer, requiring RS256, and checking the project, environment, owner, and audience claims. `vercel.oidc.extract_bearer_token` reads the credential out of request headers. Verification fails closed: when the expected project or environment cannot be resolved from the arguments or the environment, every token is rejected. (#205) - Claims are compared for equality only. There is no project wildcard: `"*"` is an ordinary string, so a token cannot widen its own scope to every project in a team. (#205) - The issuer is pinned to Vercel's OIDC service and is not configurable. Both the root issuer `https://oidc.vercel.com` and the team-scoped `https://oidc.vercel.com/<team>` are accepted, since Vercel mints both and one global key signs them; the JWKS URL is a constant, so a token can never influence where signing keys come from. (#205) - `vercel.oidc.resolve_vercel_oidc_token_identity`, and its async twin, return an opaque, stable identity for a token. A token is a signature over an identity plus an expiry, so one identity is issued many tokens over time; this is what to key identity-scoped client state on. The signature, issuer and expiry are verified before anything is read, but no claim is checked and none is returned, so it is not an authorization check. (#205) - This requires the new `verify` extra, which pulls in `pyjwt[crypto]`: (#205) - pip install "vercel-oidc[verify]" (#205) - The extra keeps `cryptography` off installs that do not verify tokens. (#205) Bug Fixes --------- - Record JWKS refetch outcomes before allowing another caller to fetch, avoiding duplicate requests under concurrency. (#242) vercel-connect -------------- 0.1.0 - 2026-08-07 ------------------ Features -------- - Add `vercel.connect`, a Python SDK for Vercel Connect: short-lived third-party credentials brokered through the deployment's Vercel OIDC identity, with token caching, authorization flows, connector metadata, and inbound trigger verification. (#205) vercel-internal-telemetry ------------------------- 0.7.2 - 2026-08-07 ------------------ - Update dependencies. vercel-queue ------------ 0.7.3 - 2026-08-07 ------------------ Internal -------- - Take `typeutils` from `vercel._internal.core` rather than carrying a private copy. Adds a dependency on `vercel-internal-core`. (#261) vercel-sandbox -------------- 0.4.0 - 2026-08-07 ------------------ Breaking Changes ---------------- - Require synchronous credential factories when configuring `vercel.sandbox.sync`; use asynchronous factories only with the async Sandbox API. (#242) - Replace the legacy `runtime` selector with `image` when creating sandboxes. Sandbox creation now uses API v3, defaults to `vercel/sandbox/universal:latest`, and supports custom Vercel Container Registry images. (#252) Internal -------- - Run Sandbox examples through the package-owned workspace Poe task. (#234) vercel-cache ------------ 0.7.2 - 2026-08-07 ------------------ - Update dependencies. vercel ------ 0.9.0 - 2026-08-07 ------------------ Breaking Changes ---------------- - The local workflow world now stores its `.workflow-data` files as JSON in the same format the TypeScript `@workflow/world-local` package uses, instead of CBOR. Runs, steps, hooks and events written by either SDK are now readable by the other. Existing `.workflow-data` directories are not readable in the new format and should be deleted. (#226) - Workflow payloads now use the devalue wire format of the TypeScript `@workflow/core` package. (#243) - Workflow steps now ride the `__wkf_workflow_*` queue as a `stepId` on the workflow invoke payload, matching the TypeScript SDK; the separate `__wkf_step_*` queue is gone. (#251) Features -------- - Workflow payloads can now carry native `Decimal`, `UUID`, `date`, `time`, `timedelta` and `Path`, and `@serializable` (or `register_serializable()`) is offered for custom classes. (#224) - Add sync and async clients with typed models for managing project-level routing rules and versions. (#219) Bug Fixes --------- - Allow workflows on Python 3.12 and earlier to import `uuid` by safely exposing `platform.system()` while continuing to block host-specific platform inspection. (#242) - Prevent errors when tasks waiting on steps or hooks are cancelled. (#250) - The Vercel world now honours `VERCEL_WORKFLOW_SERVER_URL` and `WORKFLOW_VERCEL_BACKEND_URL`, which previously had no effect in Python, so a preview deployment reaches the same workflow-server as its TypeScript peers. (#248) Internal -------- - Use a consistent isolated event-loop lifecycle for workflow execution on Python 3.10. (#242) - Run workflows on a dedicated event loop that advances execution when the loop becomes idle. (#242) - Avoid invoking the workflow event loop's idle hook after the loop begins stopping. (#242) vercel-apscheduler ------------------ 0.1.0 - 2026-08-07 ------------------ Features -------- - Add the durable Redis driver for running APScheduler schedules through delayed Vercel Queue messages. (#242) - Add Redis-backed APScheduler subscribers for Vercel Queues. The integration patches `scheduler.start()`, `scheduler.pause()`, and `scheduler.resume()` with durable, deployment-scoped lifecycle transitions and atomic single-chain fencing. Paused occurrences are skipped on resume, and interrupted successor publication is repaired on retry. Production schedules activate on the first request, and opted-in previews stop after a durable idle timeout. Jobs that do not choose a `misfire_grace_time` run their occurrences whenever the wake arrives: the stock one-second grace assumes in-process wakeup precision that queue delivery cannot meet. (#238) - Add a Vercel Runtime Cache backend and use it by default when Redis is not configured, so schedulers run with zero infrastructure. Jobs stay defined in code; the cache document only coordinates the chain (generation, start and wake bookkeeping, lifecycle flags). Because cache entries are evictable and per-region, the queue messages remain the authority: an evicted document is rebuilt from the arriving wake, idempotency keys still fence duplicate starts, and pause/resume flags additionally ride the start topic. Scheduler identity comes from the builder-assigned subscriber id, with a declared-subscriber lookup for web processes. Under `vercel dev` the backend falls back to a per-process in-memory cache and activates on the first request like production, using a stable deployment id derived from the project directory. (#245) Bug Fixes --------- - Fix the Runtime Cache backend to work under `vc dev`. (#253) vercel-celery ------------- 0.7.3 - 2026-08-07 ------------------ - Update dependencies. vercel-dramatiq --------------- 0.7.2 - 2026-08-07 ------------------ - Update dependencies.
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
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.
Replace the legacy
runtimeselector withimagewhen creating sandboxes. Sandbox creation now uses API v3, defaults tovercel/sandbox/universal:latest, and supports custom Vercel Container Registry images.Closes #201