Skip to main content

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.

​
Configuration

Vers uses TOML configuration files to define VM specifications. The primary configuration file is vers.toml, which controls how VMs are created.
The vers CLI will first look for a vers.toml file corresponding to the current project (from the folder in which the CLI is run from) or refer to the file in ~/.vers which was written as part of CLI authentication.

​
Configuration File Structure

​
Complete vers.toml Example

[machine]
mem_size_mib = 2048           # VM memory allocation in MiB
vcpu_count = 4                # Number of virtual CPU cores
fs_size_mib = 4096         # VM filesystem size in MiB

[rootfs]
name = "default"              # Base filesystem image name

[kernel]
name = "default.bin"          # Kernel image file name

​
Minimal Configuration

[machine]
mem_size_mib = 512

[rootfs]
name = "default"

​
Configuration Sections

​
[machine] Section

Controls VM hardware specifications and resource allocation.

​
Memory Configuration

  • mem_size_mib - RAM allocation per VM in mebibytes
  • Range - Typically 512-16384 MiB, depending on system capacity
[machine]
mem_size_mib = 1024    # 1 GB RAM per VM

​
CPU Configuration

  • vcpu_count - Number of virtual CPU cores per VM
  • Range - 1-16 cores typical, limited by host system
[machine]
vcpu_count = 2         # 2 CPU cores per VM

​
Storage Configuration

  • fs_size_mib - Storage allocated to VMs
[machine]
fs_size_mib = 2048         # 2 GB per VM

​
[rootfs] Section

Defines the base filesystem image for VMs.
  • name - Identifier for the rootfs image
  • “default” - Uses system default image
[rootfs]
name = "default"

​
[kernel] Section

Specifies the kernel image for VM boot.
  • name - Kernel image filename
  • Default - “default.bin” for standard kernel
[kernel]
name = "default.bin"

​
Default Values

When values are omitted, Vers uses these defaults: 
[machine]
mem_size_mib = 512
vcpu_count = 1
fs_size_mib = 512

[rootfs]
name = "default"

[kernel]
name = "default.bin"

​
Loading Behavior

# If vers.toml exists: load values, use defaults for missing sections
# If vers.toml missing: use all defaults (with warning)
vers run
# Warning: vers.toml not found, using default configuration

​
Configuration Override Hierarchy

​
Precedence Order (highest to lowest)

  1. Command-line flags - Direct flag values
  2. Configuration file - vers.toml values
  3. System defaults - Built-in fallbacks

​
Flag Override Examples

# Override memory from command line
vers run --mem-size 4096
# Uses 4096 MiB regardless of vers.toml value

# Override multiple values
vers run --mem-size 2048 --vcpu-count 4 --rootfs custom-image

​
Configuration Validation

​
Validation Rules

  • Positive integers - Memory, CPU, and storage values must be > 0
  • Resource constraints - Values must be within system capabilities
  • Image availability - Referenced images must exist

​
Common Validation Errors

vers run --mem-size -1
# Error: Invalid memory size (must be positive)

​
Environment-Specific Configurations

​
Development Configuration

# vers-dev.toml
[machine]
mem_size_mib = 1024
vcpu_count = 2
fs_size_mib = 2048

[rootfs]
name = "default"

​
High-Performance Configuration

# vers-perf.toml
[machine]
mem_size_mib = 4096
vcpu_count = 8
fs_size_mib = 8192

[rootfs]
name = "default"

​
Configuration Best Practices

​
Resource Planning

# Plan resources based on your workload
[machine]
mem_size_mib = 1024           # Per VM
vcpu_count = 2                # Per VM
fs_size_mib = 1024         # Per VM

​
Troubleshooting Configuration Issues

​
Common Problems

Configuration not loading: 
vers run
# Uses defaults instead of vers.toml values
# Cause: TOML syntax errors or file permission issues
# Solution: Validate TOML syntax and file permissions
Resource allocation failures: 
vers run
# Error: Insufficient system resources
# Cause: Configuration requests more resources than available
# Solution: Reduce memory/CPU requirements or free system resources
Image not found errors: 
vers run --rootfs custom-image
# Error: rootfs image 'custom-image' not found
# Cause: Image name doesn't exist
# Solution: Use "default" or verify the image name exists

​
See Also