VM Lifecycle

Understand the VM states Freestyle exposes: running, stopped, forked, and deleted.

Freestyle VMs are meant to be controlled as durable runtime objects. Your application can start work, stop it, start it again later, fork it for parallel exploration, and delete it when it is no longer needed.

Running

The VM is executing and can accept commands, SSH sessions, and network traffic.

const { vm } = await freestyle.vms.create();

await vm.exec("echo running");

Stopped

Stopping shuts the VM down. Disk state is preserved, but memory is not. Use stop() when you explicitly want a fresh boot.

await vm.stop();
await vm.start();

Resize

Use resize() to size a VM for your workload after it exists. Pass any of cpu, memory, and storage to change the VM’s CPU, memory, or root filesystem size.

await vm.resize({
  cpu: 8,
  memory: 16,
  storage: 80,
});

If the VM is running, Freestyle stops it during the resize and starts it again afterward. Disk state is preserved, but in-memory process state is not. cpu and memory must be powers of two, storage can grow the root filesystem but cannot shrink it, and requested sizes are subject to your account limits.

Forked

Forking creates a new VM from the current running state. Use it when an agent needs to explore multiple branches of work from the same environment.

const { forks } = await vm.fork({
  count: 1,
  persistence: { type: "ephemeral" },
});

const [{ vm: forked }] = forks;

await forked.exec("echo 'work in parallel'");

Idle Timeout

Configure an idle timeout to let Freestyle reclaim VMs that have no network activity.

await vm.start({ idleTimeoutSeconds: 600 });

Set idleTimeoutSeconds to null only for workloads that should stay running until you stop or delete them.

Delete

Delete VMs when the workspace is finished.

await freestyle.vms.delete({ vmId });

Deleting is permanent for the VM. Keep source code and important state in Freestyle Git or another durable system before deleting the VM.