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 deletes a sandbox automatically. Set one when you create a sandbox, so a sandbox your application forgets to delete doesn’t keep running. Set the policy when you create the sandbox. The CLI has no expiration flag, so use the dashboard’s Time to live or one of these interfaces. These examples delete the sandbox 1 hour after creation:

TypeScript
Python
Go
API

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 }],
  },
});
console.log(sandbox.name);

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))]
        ),
    )
    print(sandbox.name)

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},
            },
        },
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(sb.Name())
}

Add a policy to lifecycle.expiration_policies in the create request:

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

A sandbox’s expires_in field shows the seconds until it expires. Each policy type measures time differently:

TTL_MAX_AGE: deletes the sandbox a set duration after creation. Idle time counts, and activity doesn’t extend it. Time to live in the dashboard sets this policy.
TTL_IDLE: deletes the sandbox after a set duration without activity.
DATE: deletes the sandbox at an ISO 8601 timestamp, such as 2026-10-02T18:00:00Z.

You can combine types, one policy of each. Baseten deletes the sandbox when the first condition occurs. Choose a duration that covers setup, execution, and retrieving results. The sandbox’s detail page 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

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