Skip to content

Support "use workflow" serialization for Sandbox and Command #72

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
cramforce wants to merge 9 commits into
base: main
Choose a base branch
from
Open

Support "use workflow" serialization for Sandbox and Command #72

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
4e45f2d
Support "use workflow" sealization for Sandbox and Command
cramforce Jan 24, 2026
2ff3c72
Use .get
cramforce Mar 1, 2026
7defb61
Formatting
cramforce Mar 1, 2026
26397e5
e2e test
cramforce Mar 1, 2026
6577fb8
rename
cramforce Mar 1, 2026
f2d4050
changeset
cramforce Mar 1, 2026
f4efc7e
comments
cramforce Mar 1, 2026
32ac1ff
refactor sandbox serde to use snapshot-based sync rehydration
Schniz Mar 2, 2026
017ca93
test: remove unsafe cast in command serde test
Schniz Mar 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/icy-nights-bet.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"@vercel/sandbox": patch
---

Support useworkflow serialization for sandboxes and commands
20 changes: 20 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -142,6 +142,26 @@ const sandbox = await Sandbox.create({
});
```

## Workflow DevKit integration

`Sandbox` and `CommandFinished` support serialization with the
[Workflow DevKit](https://vercel.com/docs/workflow). When a sandbox instance
crosses a step boundary the SDK serializes sandbox metadata and routes, then
rehydrates synchronously from that snapshot.

Because the workflow runtime deserializes in a new execution context,
credentials are not carried over. Call `setSandboxCredentials` in the module
scope so deserialized instances can make API calls when needed:

```ts
import { Sandbox, setSandboxCredentials } from "@vercel/sandbox";

setSandboxCredentials({
token: process.env.VERCEL_TOKEN!,
teamId: process.env.VERCEL_TEAM_ID!,
});
Comment on lines +159 to +162
Copy link

@pranaygp pranaygp Mar 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there a way we can avoid having the user do this? the deserialization should be able to reconstruct the credentials each time, the same way we do in non-workflow context

now that we have e2e encryption in workflow, we can also serialize and pass credentials across the wire if that's a limitation

Copy link
Collaborator

@Schniz Schniz Mar 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yeah that what bothers me the most. but if you use OIDC or any short-term token it might not be good enough :sad:

```

## Limitations

- Max resources: 8 vCPUs. You will get 2048 MB of memory per vCPU.
Expand Down
20 changes: 20 additions & 0 deletions packages/vercel-sandbox/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -142,6 +142,26 @@ const sandbox = await Sandbox.create({
});
```

## Workflow DevKit integration

`Sandbox` and `CommandFinished` support serialization with the
[Workflow DevKit](https://vercel.com/docs/workflow). When a sandbox instance
crosses a step boundary the SDK serializes sandbox metadata and routes, then
rehydrates synchronously from that snapshot.

Because the workflow runtime deserializes in a new execution context,
credentials are not carried over. Call `setSandboxCredentials` in the module
scope so deserialized instances can make API calls when needed:

```ts
import { Sandbox, setSandboxCredentials } from "@vercel/sandbox";

setSandboxCredentials({
token: process.env.VERCEL_TOKEN!,
teamId: process.env.VERCEL_TEAM_ID!,
});
```

## Limitations

- Max resources: 8 vCPUs. You will get 2048 MB of memory per vCPU.
Expand Down
2 changes: 2 additions & 0 deletions packages/vercel-sandbox/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,7 @@
"license": "Apache-2.0",
"dependencies": {
"@vercel/oidc": "3.2.0",
"@workflow/serde": "4.1.0-beta.2",
"async-retry": "1.3.3",
"jsonlines": "0.1.1",
"ms": "2.1.3",
Expand All @@ -46,6 +47,7 @@
"@types/ms": "2.1.0",
"@types/node": "22.15.12",
"@types/tar-stream": "3.1.4",
"@workflow/core": "4.1.0-beta.62",
"dotenv": "16.5.0",
"factoree": "^0.1.2",
"typedoc": "0.28.5",
Expand Down
Loading