Persistence

Freestyle lets you control how long your VMs are stored after they're suspended. You can choose between ephemeral, cache, and persistent storage strategies.

Persistence Types

Ephemeral

VMs are deleted after they're suspended or when they reach their idle timeout. No storage costs after the VM is suspended.

import { freestyle } from "freestyle-sandboxes";

const { vm } = await freestyle.vms.create({
  persistence: {
    type: "ephemeral",
  },
});

You can also specify when the VM should be deleted with deleteEvent:

const { vm } = await freestyle.vms.create({
  persistence: {
    type: "ephemeral",
    deleteEvent: "onSuspend", // or "onIdleTimeout"
  },
});

Cache (Sticky)

VMs are stored temporarily with a priority system. Lower priority VMs are deleted first, followed by higher priority VMs with the oldest last access time. Not guaranteed to persist indefinitely.

const { vm } = await freestyle.vms.create({
  persistence: {
    type: "sticky",
    priority: 5, // 0-10, default is 5
  },
});

Higher priority values mean the VM is less likely to be evicted:

// High priority - keep around longer
const { vm: highPriority } = await freestyle.vms.create({
  persistence: {
    type: "sticky",
    priority: 10,
  },
});

// Low priority - evict first
const { vm: lowPriority } = await freestyle.vms.create({
  persistence: {
    type: "sticky",
    priority: 1,
  },
});

Persistent

VMs are stored indefinitely until you manually delete them. Use with caution as you won't be able to create new VMs if your storage quota is reached.

const { vm } = await freestyle.vms.create({
  persistence: {
    type: "persistent",
  },
});

When to Use Each Type

Ephemeral is ideal for:

• Temporary workbenches that don't need to persist
• Long-running tasks where the result is stored elsewhere
• Testing and experimentation
• Cost optimization when storage isn't needed

Cache (Sticky) is ideal for:

• AI coding agents and dev environments
• Scenarios where the VM is not the source of truth
• Fast startup times with pre-configured environments
• Balancing performance and cost

Persistent is ideal for:

• VMs that are the source of truth for data
• Long-running applications requiring state across restarts
• Production workloads
• Critical development environments

Default Behavior

If you don't specify persistence, VMs default to sticky with priority 5:

// These are equivalent
const { vm: vm1 } = await freestyle.vms.create();
const { vm: vm2 } = await freestyle.vms.create({
  persistence: { type: "sticky", priority: 5 },
});