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

# Run

# vers run

Start a Vers development environment according to the configuration in vers.toml.

## Usage

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers run                             # Start with default configuration
vers run --mem-size 1024             # Override memory settings
vers run --vm-alias web-server       # Set VM alias
```

## Options

| Option           | Description                       |
| ---------------- | --------------------------------- |
| `--mem-size`     | Override memory size (MiB)        |
| `--vcpu-count`   | Override number of virtual CPUs   |
| `--rootfs`       | Override rootfs name              |
| `--kernel`       | Override kernel name              |
| `--fs-size-vm`   | Override VM filesystem size (MiB) |
| `--vm-alias, -N` | Set an alias for the root VM      |

## Examples

### Start with default configuration

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers run
Sending request to start environment...
Environment started successfully with root vm 'vm-def456'.
HEAD now points to: vm-def456
```

### Override resource settings

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers run --mem-size 2048 --vcpu-count 4
Sending request to start environment...
Environment started successfully with root vm 'vm-abc123'.
HEAD now points to: vm-abc123
```

### Use custom alias

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers run --vm-alias web-server
Sending request to start environment...
Environment started successfully with root vm 'vm-ghi789'.
HEAD now points to: web-server
```

### Override images and storage

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers run --rootfs ubuntu-dev --kernel custom.bin --fs-size-vm 2048
Sending request to start environment...
Environment started successfully with root vm 'vm-pqr567'.
HEAD now points to: vm-pqr567
```

## How it works

The `run` command:

1. **Loads configuration**: Reads settings from `vers.toml`
2. **Applies overrides**: Uses command-line flags to override configuration values
3. **Creates environment**: Makes API call to create a new environment with the specified settings
4. **Updates HEAD**: Sets your local HEAD to point to the new root VM
5. **Confirms success**: Shows environment and root VM information

## Configuration integration

The command respects your `vers.toml` configuration:

```toml theme={"theme":{"light":"min-light","dark":"min-dark"}}
[machine]
mem_size_mib = 512
vcpu_count = 1
fs_size_mib = 512

[rootfs]
name = "default"

[kernel]
name = "default.bin"
```

Command-line flags take precedence over configuration file values.

## What gets created

* **New environment**: Fresh environment with your specified configuration
* **Root VM**: The primary VM with your settings
* **Local HEAD**: Updated to point to the new root VM

## Error handling

### Missing configuration

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers run
Error: failed to load configuration: vers.toml not found
```

**Solution**: Run `vers init` first to create configuration.

### Invalid settings

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers run --mem-size 0
Error: invalid memory size
```

### Rootfs not found

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers run --rootfs nonexistent-image
Error: rootfs 'nonexistent-image' not found
```

### No .vers directory

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers run
Environment started successfully...
Warning: .vers directory not found. Run 'vers init' first.
```

**Solution**: Run `vers init` in your project directory.

## Use cases

### Quick development startup

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# Start with your default configuration
vers run
vers connect
# Begin development work
```

### Resource experimentation

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# Test with different memory allocations
vers run --mem-size 1024  # Standard development
vers run --mem-size 2048  # Memory-intensive work
vers run --mem-size 512   # Lightweight testing
```

### Custom environment testing

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# Test different rootfs images
vers run --rootfs ubuntu-dev
vers run --rootfs alpine-minimal
vers run --rootfs my-custom-image
```

### Named environments

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# Create labeled environments
vers run --vm-alias frontend-dev
vers run --vm-alias backend-dev
```

## Prerequisites

* Project initialized with `vers init`
* Valid `vers.toml` configuration file
* Authenticated with Vers platform
* Network connectivity

## Notes

* Aliases set with `--vm-alias` are stored locally at `~/.vers/aliases.json`
* Use `vers alias` to view all your aliases

## Common Patterns

### Boot then branch immediately (golden VM)

Create one configured VM, then fan out N independent copies:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
ROOT=$(vers run --vm-alias golden --wait --format json | jq -r .root_vm_id)
vers execute "$ROOT" -- bash -c "apt-get update && apt-get install -y deps"

for i in $(seq 1 5); do
  vers branch "$ROOT" --vm-alias "worker-$i"
done
```

### Boot with resource overrides for one-off work

Ignore `vers.toml` for a single run:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers run --mem-size 8192 --vcpu-count 4 --fs-size-vm 8192 --vm-alias heavy-job
```

### Boot, run something, commit, throw away

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
VM=$(vers run --wait --format json | jq -r .root_vm_id)
vers execute "$VM" -- ./setup.sh
COMMIT=$(vers commit "$VM" --format json | jq -r .commit_id)
vers kill -y "$VM"
echo "Reusable commit: $COMMIT"
```

## See Also

* [vers alias](/cli-reference/alias) - View and look up aliases
* [vers init](/cli-reference/init) - Initialize project configuration
* [vers connect](/cli-reference/connect) - Connect to running VMs