Expiration policies

While Blaxel is designed for you to keep your sandboxes in standby perpetually, it also supports automatic deletion of sandboxes based on specific expiration policies. This is useful if you want to avoid keeping snapshot storage for a long tail of sandboxes that will never be reactivated again.

Blaxel has a quota tiering system that unlocks higher limits and features on the platform as your tier progresses. Some quota tiers enforce expiration dates (Tier 0 and 1, with respectively up to 7 and 30 days). In higher tiers, unlimited persistence is permitted.

Automatic deletion differs from the automatic standby (scale-to-zero) which happens to all sandboxes when inactive and where the memory and filesystem are snapshotted to be resumed instantly.

The following options are available for sandbox expiry and deletion:

expire after a total maximum lifetime (time-to-live or TTL) from creation using the ttl parameter
expire at a specific date using the expires parameter
expire based on a combination of one or more lifecycle policies, specified with the lifecycle.expirationPolicies / lifecycle.expiration_policies parameter
- ttl-max-age: Delete after total lifetime from creation (equivalent to ttl) (1h, 24h, 7d)
- ttl-idle: Delete after period of inactivity from last active time (1h, 24h, 7d)
- date: Delete at a specific date (equivalent to expires)

If these parameters are absent, sandboxes will not be deleted.

The sandbox metadata includes a read-only parameter, expiresIn, that computes the number of seconds until a sandbox is terminated due to its TTL or lifecycle policy.

Configure sandbox expiry rules at creation

You can define a sandbox’s time-to-live (TTL) configuration at creation time:

import { SandboxInstance } from "@blaxel/core";

// Create a new sandbox
const sandbox = await SandboxInstance.create({
  name: "my-sandbox",
  image: "blaxel/base-image:latest",
  memory: 4096,
  ports: [{ target: 3000, protocol: "HTTP" }],
  region: "us-pdx-1",
  ttl: "24h", // Total duration before auto-deletion. Supported units: h, d, w
  // OR
  // expires: new Date(Date.now() + 86400000) // Alternative: set a date at which it will be deleted
  // OR / AND
  lifecycle: {
    expirationPolicies: [
      {
        type: "ttl-idle",
        value: "24h",  // Delete after 24 hours of inactivity. Supported units: h, d, w
        action: "delete"
      }
    ]
  }
});

Important notes:

Three lifecycle expiration policies are supported: ttl-idle, ttl-max-age and date. Check out the API reference for full documentation.
The ttl, ttl-idle and ttl-max-age parameters accept a string with the following time units: h (hours), m (minutes), d (days), and w (weeks).
You can combine multiple expiration policies. Whichever condition is met first will trigger the deletion.

Update sandbox expiry rules

You can update a sandbox’s time-to-live (TTL) configuration after it has been created:

import { SandboxInstance } from "@blaxel/core";

// Update sandbox TTL
const sandbox = await SandboxInstance.updateTtl("my-sandbox", "30m");

You can also update the expiration policy of a sandbox after it has been created:

import { SandboxInstance } from "@blaxel/core";

// Update sandbox expiration policy
await SandboxInstance.updateLifecycle("my-sandbox", {
  expirationPolicies: [
    { type: "ttl-max-age", value: "30m", action: "delete" }
  ]
});

Clear sandbox expiry rules

To make a sandbox persist again, clear its TTL or lifecycle policies. Clearing does not recreate the sandbox or affect its filesystem. Pass null (or an empty string) to updateTtl to remove the TTL:

import { SandboxInstance } from "@blaxel/core";

// Clear the sandbox TTL
const sandbox = await SandboxInstance.updateTtl("my-sandbox", null);

Pass null to updateLifecycle to remove all expiration policies:

import { SandboxInstance } from "@blaxel/core";

// Remove all expiration policies
await SandboxInstance.updateLifecycle("my-sandbox", null);