Managing Your Sandbox
Once you have created a sandbox, you can manage its lifecycle, monitor its performance, and take a snapshot. This guide covers the essential tasks for maintaining your sandboxes.
By default, a sandbox runs for 5 minutes before automatically timing out. You can adjust this duration to suit your workload, up to a maximum of 5 hours for Pro and Enterprise plans, or 45 minutes for Hobby plans. To learn more about the maximum duration, see the Pricing and Limits page.
To configure the timeout, pass the timeout option when creating the sandbox:
When the sandbox is running, you can extend the duration using the extendTimeout method. You can extend the duration as many times as you need, until the maximum duration has been reached.
Once the sandbox reaches the maximum runtime duration, it stops automatically.
The SDK uses Vercel OIDC tokens to authenticate whenever available. This is the recommended way to authenticate with your sandbox.
When developing locally, you can download a development token to .env.local by connecting to a Vercel project and running vercel env pull. This allows you to pull environment variables, including the development token, for authentication.
In production, Vercel manages token expiration for you.
If you want to use the SDK from an environment where VERCEL_OIDC_TOKEN is
unavailable, you can also authenticate using an access token. You will need:
- Your Vercel team ID
- Your Vercel project ID
- A Vercel access token with access to the above team
Set your team ID, project ID, and token to the environment variables VERCEL_TEAM_ID, VERCEL_PROJECT_ID, and VERCEL_TOKEN. Then, pass these items to the Sandbox.create() method:
Visit the Sandboxes page to view your sandboxes by project, inspect command history, and access sandbox URLs.
This view shows information on a per-project basis, and for each project shows:
- How many sandboxes are created
- How many are currently running
- How many are stopped
To track compute usage for your sandboxes across projects, go to the Usage tab of your Vercel dashboard.
The Usage dashboard measures:
- Sandbox Provisioned Memory: The amount of memory allocated to your sandboxes.
- Sandbox Data Transfer: The amount of data transferred in and out of your sandboxes.
- Sandbox Active CPU: The amount of CPU time your sandboxes have used.
- Sandbox Creations: The number of sandboxes you have created.
Refer to the Pricing page to help understand how each of these works to determine your usage and therefore cost.
To stop a sandbox, you can:
- Navigate to the Sandboxes page in the Observability tab.
- From the list, select your sandbox.
- Click the Stop Sandbox button.
If you do not stop the sandbox manually, it stops automatically after the configured timeout elapses.
The SDK also provides the stop method to programmatically stop a running sandbox. This is useful for ensuring resources are cleaned up after your code finishes execution, rather than waiting for the timeout.
Take a snapshot of a running sandbox to save its state and resume later from that exact point. Snapshots expire after 7 days, so plan to recreate them if you need them longer.
Snapshots are useful for:
- Faster startups: Skip dependency installation by snapshotting after setup.
- Checkpointing: Save progress on long-running tasks.
- Sharing environments: Give teammates an identical starting point.
To take a snapshot, use the snapshot method:
The sandbox must be running to create a snapshot. Once you call snapshot(), the sandbox shuts down automatically and becomes unreachable. You do not need to call stop() afterwards, and any subsequent commands to the sandbox will fail.
Retrieve a previously created snapshot using Snapshot.get():
Delete a snapshot you no longer need:
Was this helpful?