Configuration

Vers uses a TOML file — vers.toml — to describe how a VM should be created. vers run, vers build (FROM scratch), and other commands all read it. Command-line flags override the file; missing values fall back to built-in defaults.

Quick Reference

Section	Key	Default	Description
`[machine]`	`mem_size_mib`	`512`	RAM per VM in MiB
`[machine]`	`vcpu_count`	`1`	Number of virtual CPUs
`[machine]`	`fs_size_vm_mib`	`1024`	Root filesystem size in MiB
`[rootfs]`	`name`	`"default"`	Base rootfs image name
`[kernel]`	`name`	`"default.bin"`	Kernel image filename
`[builder]`	`name`	`"docker"`	Builder implementation
`[builder]`	`dockerfile`	`"Dockerfile"`	Dockerfile path (relative to project)

Flag precedence (highest to lowest): CLI flags → vers.toml → built-in defaults.

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_vm_mib = 4096         # VM filesystem size in MiB

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

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

[builder]
name = "docker"               # Builder implementation
dockerfile = "Dockerfile"     # Dockerfile path, relative to project root

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_vm_mib - Storage allocated to VMs

[machine]
fs_size_vm_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_vm_mib = 1024

[rootfs]
name = "default"

[kernel]
name = "default.bin"

[builder]
name = "docker"
dockerfile = "Dockerfile"

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)

Command-line flags - Direct flag values
Configuration file - vers.toml values
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_vm_mib = 2048

[rootfs]
name = "default"

High-Performance Configuration

# vers-perf.toml
[machine]
mem_size_mib = 4096
vcpu_count = 8
fs_size_vm_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_vm_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

What’s next

vers init

Create a new project and generate the initial vers.toml.

vers run

Boot a VM from your configuration.

Agent swarms

See configuration sized for real parallel-agent workloads.

Architecture

How VM resources map onto the underlying hypervisor.

​Quick Reference

​Configuration File Structure

​Complete vers.toml Example

​Minimal Configuration

​Configuration Sections

​[machine] Section

​Memory Configuration

​CPU Configuration

​Storage Configuration

​[rootfs] Section

​[kernel] Section

​Default Values

​Loading Behavior

​Configuration Override Hierarchy

​Precedence Order (highest to lowest)

​Flag Override Examples

​Configuration Validation

​Validation Rules

​Common Validation Errors

​Environment-Specific Configurations

​Development Configuration

​High-Performance Configuration

​Configuration Best Practices

​Resource Planning

​Troubleshooting Configuration Issues

​Common Problems

​What’s next