# 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.

Freestyle VM lifecycle
A created VM becomes Running. Running can suspend to and resume from Suspended, stop to and start from Stopped, and fork into a new Running fork. Running, Suspended, and Stopped VMs can all be deleted.

- suspend / resume
- stop / start
- fork()
- delete()
- create
- Suspended
- Running
- Stopped
- Running fork
- Deleted

## Running

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

```javascript
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.

```javascript
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.

```javascript
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.

```javascript
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.

```javascript
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.

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

Deleting is permanent for the VM. Keep source code and important state in [Freestyle Git](/content/docs/git/index.html) or another durable system before deleting the VM.