Understanding Sandbox TTL and Expiration Policies

Last updated: March 24, 2026

Blaxel provides several ways to automatically manage sandbox lifecycles through TTL (Time To Live) and expiration policies. This helps you control costs and keep your workspace clean by automatically deleting unused sandboxes.

Types of TTL Policies

There are three main types of TTL policies you can configure:

  • ttl-idle: Deletes sandboxes after a specified period of inactivity

  • ttl-max-age: Deletes sandboxes after a maximum age regardless of activity

  • date: Deletes sandboxes at a specific date

It's also possible to define sandbox TTL as sandbox parameters:

  • The ttl parameter (simpler max-age TTL)

  • The expires parameter (absolute date)

Setting Up TTL Policies

You can configure TTL policies when creating a sandbox using the ttl, expires or lifecycle parameter:

import { SandboxInstance } from "@blaxel/core";  
  
const sandbox = await SandboxInstance.create({  
  name: "my-sandbox",  
  image: "my-image",  
  ttl: "24h",  
  // OR  
  // expires: new Date(Date.now() + 86400000)  
  // OR / AND  
  lifecycle: {  
    expirationPolicies: [  
      { type: "ttl-idle", value: "1h", action: "delete" }  
    ]  
  }  
});

Important Behavior Notes

TTL-Idle Timing

The ttl-idle timer only starts counting after the first call is made to the sandbox. If a sandbox is created but never used, the idle TTL won't trigger until it receives its first API call or connection.

Processing Frequency

TTL enforcement doesn't operate at the second level. The cleanup process runs approximately every 60 seconds.

Computed Termination Time

The sandbox metadata includes a read-only parameter, expiresIn / expires_in that returns the number of seconds until a sandbox will be automatically terminated due to its TTL or lifecycle policy.

Deletion Process

When a sandbox expires:

  1. The sandbox is first terminated

  2. It remains in "terminated" state for some period of time (the retention period can be configured depending on tier)

  3. Finally, it gets deleted completely

Quota Limits and TTL

Different account tiers have different TTL restrictions:

  • Tier 0: Maximum TTL of 7 days is enforced regardless of your configuration

  • Tier 1: Maximum TTL of 30 days is enforced regardless of your configuration

  • Tier 2+: No maximum TTL limits - you can set any value you want

Working with createIfNotExists

If you're using createIfNotExists with the same sandbox name, the system will automatically replace any existing terminated sandbox with a new one. Make sure you're using the latest SDK version:

  • TypeScript: v0.2.45 or later

  • Python: v0.2.21 or later

Updating TTL on Existing Sandboxes

You can apply TTL policies to already existing sandboxes using the updateTtl method or lifecycle updates. This is useful for cleaning up sandboxes that were created without TTL policies.

Preview Cleanup

When a sandbox is deleted (including automatic deletion via TTL), all associated preview URLs are automatically cleaned up. You don't need to manually delete previews - they're scoped to the sandbox and removed as part of the deletion process.