VM Lifecycle

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

Freestyle VMs are meant to be controlled as durable runtime objects. Your application can start work, pause it, resume it 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");

Suspended

Suspending a VM pauses it while preserving memory state. Use this for most idle periods because resume is much faster than a full reboot.

await vm.suspend();

// Later, resume explicitly.
await vm.start();

A suspended VM can also resume when it receives an SSH connection, network request, or exec command.

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();

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 { vm: forked } = await vm.fork();

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

Idle Timeout

Configure an idle timeout to suspend VMs that have no network activity.

const { vm } = await freestyle.vms.create({
  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: vm.id });

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