Skip to main content

​
vers run

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

​
Usage

vers run [cluster]                   # Start with default configuration
vers run --mem-size 1024             # Override memory settings
vers run --cluster-alias prod         # Set cluster alias

​
Options

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

​
Examples

​
Start with default configuration

vers run
Sending request to start cluster...
Cluster (ID: cluster-abc123) 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 cluster...
Cluster (ID: cluster-xyz789) started successfully with root vm 'vm-abc123'.
HEAD now points to: vm-abc123

​
Use custom aliases

vers run --cluster-alias production --vm-alias web-server
Sending request to start cluster...
Cluster (ID: cluster-def456) 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-cluster 2048
Sending request to start cluster...
Cluster (ID: cluster-mno234) 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 cluster: Makes API call to create a new cluster with the specified settings
  4. Updates HEAD: Sets your local HEAD to point to the new root VM
  5. Confirms success: Shows cluster ID and root VM information

​
Configuration integration

The command respects your vers.toml configuration: 
[machine]
mem_size_mib = 512
vcpu_count = 1
fs_size_cluster_mib = 1024
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 cluster: Fresh cluster with your specified configuration
  • Root VM: The primary VM in the cluster 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
Cluster (ID: cluster-abc123) 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

​
Team environment setup

# Create labeled environments
vers run --cluster-alias team-alpha --vm-alias frontend-dev
vers run --cluster-alias team-beta --vm-alias backend-dev

​
Prerequisites

  • Project initialized with vers init
  • Valid vers.toml configuration file
  • Authenticated with Vers platform
  • Network connectivity
  • Sufficient resources for cluster creation

​
See Also