Skip to main content

​
vers run

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

​
Usage

vers run                             # Start with default configuration
vers run --mem-size 1024             # Override memory settings
vers run --vm-alias web-server       # Set VM alias

​
Options

OptionDescription
--mem-sizeOverride memory size (MiB)
--vcpu-countOverride number of virtual CPUs
--rootfsOverride rootfs name
--kernelOverride kernel name
--fs-size-vmOverride VM filesystem size (MiB)
--vm-alias, -NSet an alias for the root VM

​
Examples

​
Start with default configuration

vers run
Sending request to start environment...
Environment started successfully with root vm 'vm-def456'.
HEAD now points to: vm-def456

​
Override resource settings

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

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

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: 
[machine]
mem_size_mib = 512
vcpu_count = 1
fs_size_vm_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

vers run
Error: failed to load configuration: vers.toml not found
Solution: Run vers init first to create configuration.

​
Invalid settings

vers run --mem-size 0
Error: invalid memory size

​
Rootfs not found

vers run --rootfs nonexistent-image
Error: rootfs 'nonexistent-image' not found

​
No .vers directory

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

# Start with your default configuration
vers run
vers connect
# Begin development work

​
Resource experimentation

# 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

# Test different rootfs images
vers run --rootfs ubuntu-dev
vers run --rootfs alpine-minimal
vers run --rootfs my-custom-image

​
Named environments

# 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

​
See Also