Sandbox lifecycle and expiration

A sandbox’s deployment status tells you whether it’s ready for work. Set an expiration policy so Baseten deletes the sandbox and its local data when it expires, even if your application stops before cleanup. Retrieve the task’s result before the sandbox’s deadline, then delete the sandbox.

Deployment status

A create request returns once the sandbox is DEPLOYED. Check status later with Get a sandbox, or on the sandbox’s detail page in the dashboard.

DEPLOYING: deployment is in progress.
DEPLOYED: the sandbox is ready.
DEACTIVATING: the sandbox is going idle.
DEACTIVATED: the sandbox is on standby. Its files and processes persist, and the next request resumes it.
FAILED: deployment failed.
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 status 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.

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. Set the policy when you create a sandbox using the dashboard’s Time to live, an SDK, or the create request’s lifecycle field. Time to live sets TTL_MAX_AGE; the CLI has no expiration flag. To change a policy, use an SDK or the update request’s lifecycle field. Include every policy you want to keep: the new list replaces the previous one and can’t be empty. TTL_MAX_AGE always counts from creation.

Create a sandbox with a lifetime of 1 hour

Set up your SDK and API key before running an SDK example.

TypeScript
Python
Go
API

Set afterMs in milliseconds.To create a sandbox with a lifetime of 1 hour:Run the following code:

import { SandboxClient } from "@basetenlabs/sandbox";

const client = new SandboxClient({ apiKey: process.env.BASETEN_API_KEY! });
const sandbox = await client.create({
  name: "hello-world",
  lifecycle: {
    expirationPolicies: [{
      type: "TTL_MAX_AGE",
      afterMs: 3_600_000,
      action: "DELETE",
    }],
  },
});
console.log(sandbox.name);

Set after to a timedelta.To create a sandbox with a lifetime of 1 hour:Run the following code:

import os
from datetime import timedelta

from baseten.sandbox import (
    SandboxClient,
    SandboxExpirationPolicyMaxAge,
    SandboxLifecycle,
)

with SandboxClient(api_key=os.environ["BASETEN_API_KEY"]) as client:
    sandbox = client.create(
        name="hello-world",
        lifecycle=SandboxLifecycle(expiration_policies=[
            SandboxExpirationPolicyMaxAge(
                after=timedelta(hours=1), action="DELETE"
            )
        ]),
    )
    print(sandbox.name)

Set After to a time.Duration.To create a sandbox with a lifetime of 1 hour:Run the following code:

package main

import (
    "context"
    "fmt"
    "log"
    "os"
    "time"

    "github.com/basetenlabs/baseten-go/sandbox"
)

func main() {
    ctx := context.Background()
    client, err := sandbox.NewClient(sandbox.ClientOptions{
        APIKey: os.Getenv("BASETEN_API_KEY"),
    })
    if err != nil {
        log.Fatal(err)
    }
    sb, err := client.Create(ctx, sandbox.CreateOptions{
        Name: "hello-world",
        Lifecycle: &sandbox.Lifecycle{
            ExpirationPolicies: []sandbox.ExpirationPolicy{{
                Type: sandbox.ExpirationPolicyTypeTTLMaxAge,
                After: time.Hour,
                Action: sandbox.ExpirationActionDelete,
            }},
        },
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(sb.Name())
}

Set value to a duration string, such as 1h. Set a sandbox access token in SANDBOX_TOKEN.To create a sandbox with a lifetime of 1 hour:Run the following command:

curl --request POST \
  --url https://api.baseten.co/v1/sandboxes/instances \
  --header "Authorization: Bearer $SANDBOX_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "hello-world",
    "lifecycle": {
      "expiration_policies": [
        {"type": "TTL_MAX_AGE", "value": "1h", "action": "DELETE"}
      ]
    }
  }'

{
  "name": "hello-world",
  "lifecycle": {
    "expiration_policies": [
      {"type": "TTL_MAX_AGE", "value": "1h", "action": "DELETE"}
    ]
  }
}

For more information, see the create request’s lifecycle field.

Get the sandbox to confirm its policy. The API’s expires_in field shows the remaining lifetime in seconds. Delete the sandbox when you’re finished.

The dashboard shows the deadline as Date of termination.

Local data

Deletion and expiration permanently remove a sandbox’s local data. A new sandbox from the same image starts with the image’s contents, not the deleted sandbox’s working files. Save outputs outside the sandbox before its deadline. If a sandbox expires before your work completes, create a new one with a lifetime that covers your work, and restore the outputs you saved outside it.

Get started

Model APIs

Inference

Frontier Gateway

Training

Sandboxes

Development

Deployment

Engines

Model Labs

Organization

Hosting options

Observability

Troubleshooting

Sandbox lifecycle and expiration

Deployment status

Expiration policy

Local data

​Deployment status

​Expiration policy

​Local data

Deployment status

Expiration policy

Local data