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";

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. Freestyle regularly optimizes nodes and clears sticky VMs to free up resources. Lower priority VMs are deleted first, followed by higher priority VMs with the oldest last access time. Sticky VMs are not guaranteed to persist — treat them as a cache that improves startup time, not as durable storage.

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

Recreate

When recreate: true is set, calling start() on a deleted VM will automatically recreate it from its original configuration instead of failing. If the VM was created from a declarative snapshot, the snapshot is also recreated before starting the VM from it.

const { vm, vmId } = await freestyle.vms.create({
  recreate: true,
  gitRepos: [{ repo: repoId, path: "/app" }],
});

// Later — VM gets deleted (manually, or via ephemeral/sticky cleanup)
await freestyle.vms.delete({ vmId });

// Calling start() recreates the VM from its original config
await vm.start();

This is useful for serverless-style patterns where VMs are disposable but need to come back on demand with the same setup.

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 },
});