> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vers.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Pause

# vers pause

Pause a running VM to preserve its state while freeing up resources.

## Synopsis

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers pause                           # Pause current HEAD VM
vers pause <vm-id>                   # Pause specific VM
```

## Description

The `pause` command suspends a running VM, preserving its complete state (memory, filesystem, running processes) while freeing up computational resources. This is useful for temporarily stopping work on a VM without losing any progress.

## Basic Usage

### Pause Current VM

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers pause
```

Pauses whatever VM your HEAD is currently pointing to.

### Pause Specific VM

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers pause vm-abc123
```

Pauses the specified VM directly.

## What Happens When You Pause

When you pause a VM:

* **State Preserved**: All memory, running processes, and open files are saved
* **Resources Released**: CPU and active memory are freed up
* **Quick Resume**: VM can be quickly resumed exactly where it left off
* **Network Disconnected**: SSH connections are terminated but can be re-established after resume

## Understanding Output

When pausing successfully:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers pause vm-abc123
Pausing VM 'vm-abc123'...
✓ VM 'vm-abc123' paused successfully
VM state: Paused
```

This confirms:

* Which VM was paused
* The operation completed successfully
* The current state of the VM

## VM State Requirements

### Can Pause

* **Running** VMs can be paused
* VMs with active SSH connections (connections will be terminated)
* VMs with running processes (processes are suspended)

### Cannot Pause

* **Already Paused** VMs (no effect, but not an error)
* **Stopped** VMs (different state, use resume for paused VMs)

## Error Handling

### VM Not Found

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers pause vm-nonexistent
# Error: failed to pause VM 'vm-nonexistent': not found
```

### No Current VM

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers pause
# Error: no VM ID provided and HEAD not found
```

**Solution**: Run `vers checkout` to select a VM or provide specific VM ID.

### Already Paused

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers pause vm-already-paused
# May show success but VM remains in paused state
```

## Tips

* Use `vers status` to see which VMs are paused
* Pausing frees resources for other VMs to run
* Long-running scripts will pause mid-execution and resume when VM resumes

## Common Patterns

### Pause all running VMs to save cost

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
for vm in $(vers status --format json | jq -r '.[] | select(.state == "Running") | .vm_id'); do
  vers pause "$vm"
done
```

### Pause HEAD before stepping away

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers pause              # pauses HEAD
# ...come back later...
vers resume             # resumes HEAD
```

## See Also

* [vers resume](resume) - Resume paused VMs
* [vers status](status) - Check VM states
* [vers connect](connect) - Connect to running VMs