> ## 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 > Define VM memory, vCPUs, disk, and boot image with vers.toml. 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 ```toml theme={"theme":{"light":"min-light","dark":"min-dark"}} [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 ```toml theme={"theme":{"light":"min-light","dark":"min-dark"}} [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 ```toml theme={"theme":{"light":"min-light","dark":"min-dark"}} [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 ```toml theme={"theme":{"light":"min-light","dark":"min-dark"}} [machine] vcpu_count = 2 # 2 CPU cores per VM ``` #### Storage Configuration * **`fs_size_vm_mib`** - Storage allocated to VMs ```toml theme={"theme":{"light":"min-light","dark":"min-dark"}} [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 ```toml theme={"theme":{"light":"min-light","dark":"min-dark"}} [rootfs] name = "default" ``` ### \[kernel] Section Specifies the kernel image for VM boot. * **`name`** - Kernel image filename * **Default** - "default.bin" for standard kernel ```toml theme={"theme":{"light":"min-light","dark":"min-dark"}} [kernel] name = "default.bin" ``` ## Default Values When values are omitted, Vers uses these defaults: ```toml theme={"theme":{"light":"min-light","dark":"min-dark"}} [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 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} # 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 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} # 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 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} vers run --mem-size -1 # Error: Invalid memory size (must be positive) ``` ## Environment-Specific Configurations ### Development Configuration ```toml theme={"theme":{"light":"min-light","dark":"min-dark"}} # vers-dev.toml [machine] mem_size_mib = 1024 vcpu_count = 2 fs_size_vm_mib = 2048 [rootfs] name = "default" ``` ### High-Performance Configuration ```toml theme={"theme":{"light":"min-light","dark":"min-dark"}} # vers-perf.toml [machine] mem_size_mib = 4096 vcpu_count = 8 fs_size_vm_mib = 8192 [rootfs] name = "default" ``` ## Configuration Best Practices ### Resource Planning ```toml theme={"theme":{"light":"min-light","dark":"min-dark"}} # 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**: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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**: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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**: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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 Create a new project and generate the initial `vers.toml`. Boot a VM from your configuration. See configuration sized for real parallel-agent workloads. How VM resources map onto the underlying hypervisor.