Skip to main content
Each organization can run up to 10 sandboxes at once. To raise this limit, contact support.
A sandbox runs while it receives work and goes on standby when it’s idle. Set an expiration policy so Baseten deletes the sandbox when it expires, even if your application stops before cleanup.

Active and standby

A sandbox goes on standby when it stops receiving requests. On standby, it keeps its files and running processes, and you pay only for its storage. Processes pause until the next request resumes the sandbox where it left off. To keep the sandbox active while a background process runs, start the process with keep-alive. For example, run the following command:
For the SDK equivalents, see Run a background process. Standby doesn’t delete a sandbox. An expiration policy or a delete request removes the sandbox and its files, whether it’s active or on standby.

Deployment status

The status field tracks deployment and deletion. It doesn’t show whether a sandbox is active or on standby: a sandbox on standby reports DEPLOYED.
  • DEPLOYING: deployment is in progress.
  • DEPLOYED: the sandbox is ready. A create request returns once the sandbox reaches this status.
  • FAILED: deployment failed. Inspect the sandbox’s logs before retrying.
  • DELETING: deletion is in progress.
  • TERMINATED: deletion has completed.
DEPLOYED means the environment is ready, not that a task succeeded. Confirm a task by its command’s exit code and output. Deletion is asynchronous. A delete request returns DELETING. Repeat the get request until the status is TERMINATED or the sandbox is no longer found. To check a sandbox’s status, see Get a sandbox.

Expiration policy

An expiration policy automatically deletes a sandbox. By default, sandboxes expire 7 days after creation. Select a policy type to control when the sandbox expires:
  • TTL_MAX_AGE: a duration after creation. Activity doesn’t extend it.
  • TTL_IDLE: a duration without activity.
  • DATE: a specific timestamp.
You can set one policy of each type. Baseten deletes the sandbox when the first condition is met. In the dashboard, Time to live sets TTL_MAX_AGE when you create a sandbox, and Date of termination shows when the sandbox expires. In the CLI, --max-age sets TTL_MAX_AGE, --idle-ttl sets TTL_IDLE, and --expires-at sets DATE.

Set an expiration policy

Set up your SDK, API token, or CLI before running these examples. In the SDKs, set the duration in milliseconds with afterMs in TypeScript, as a timedelta with after in Python, and as a time.Duration with After in Go. In the API and the CLI, set it as a duration string, such as 1h. To create a sandbox that expires after 1 hour:
Run the following code:
To change a policy, update the sandbox. The new list of policies replaces the previous one and can’t be empty, so include every policy you want to keep. TTL_MAX_AGE always counts from creation, not from the update. To update a sandbox’s expiration policy: This example keeps the 1-hour maximum age and adds a 30-minute idle limit.
Run the following code:
To confirm the policy, get the sandbox. The API’s expires_in field shows the time until the sandbox expires, in seconds. For more information, see baseten sandbox update and Update a sandbox.

Local data

Deletion and expiration permanently remove files stored on the sandbox. A new sandbox from the same image starts with the image’s contents, not the deleted sandbox’s working files. To keep files across sandboxes, mount a sandbox volume. Otherwise, save outputs outside the sandbox before it expires. If a sandbox expires before your work completes, create a new one with an expiration policy that covers your work, and restore the outputs you saved.