VM storage and resources

Choose VM locations, CPU and memory limits, and inspect disk usage.

Choose an existing writable directory for VM working disks. It can be on an external drive. Keep prepared base images wherever you prefer; basePath locates the source and storagePath chooses where disposable instances are created.

Example environment.json for an already prepared Linux image:

{
  "id": "ubuntu",
  "name": "Ubuntu ARM64",
  "os": "linux",
  "basePath": "/Volumes/CI/Images/ubuntu-arm64.img",
  "storagePath": "/Volumes/CI/VMs",
  "cpu": 2,
  "memoryMiB": 4096,
  "state": "ready"
}

Register it and start a VM:

vectis environment register --file environment.json --wait --json
vectis environment start ubuntu --wait --json

The original base image is preserved. The instance receives its own working disk and directory. Stopping an owned instance removes its disposable working directory, preserving the selected parent directory and base image.

For Linux runner access, use an image from Linux preparation. Its registration includes sshUser, sshKeyPath and sshHostKeyMode: "instance". Custom Linux images must install the SSH identity from Vectis instance setup media before starting SSH; a shared image host key is not accepted.

Change defaults or one VM

Change defaults for future instances:

vectis environment configure ubuntu --cpu 4 --memory-mib 8192 --storage-path /Volumes/CI/VMs --wait --json

Override just one start without changing defaults:

vectis environment start ubuntu --cpu 2 --memory-mib 4096 --wait --json

Running instances keep the resources and location they started with. Changing a path does not move existing disks. CPU and memory settings are per-VM ceilings, fixed until the VM stops. Vectis allows CPU overcommit: their sum may exceed host cores, while each VM must fit the host core count. Unused guest memory is allocated lazily. For a suitable host, generous ceilings such as Linux 8 vCPUs / 12288 MiB, Windows 8 / 16384 MiB, and macOS 6 / 12288 MiB let builds grow without reserving the full ceiling at admission. A single VM ceiling still cannot exceed 75 percent of host RAM.

Shared memory budget

vectis machine configure --memory-budget-mib 36864 sets the shared admission budget, for example 36 GiB on a 48 GiB host. The allowed range is 2048 MiB to total host RAM; an unset budget defaults to 75 percent of host RAM. Combine it with --max-runners <N> or change either independently. These machine settings persist across service restarts and apply to local, MCP and remote commands.

Admission counts every non-stopped VM at the larger of its measured process RSS and a startup floor: 2048 MiB for Linux, 4096 MiB for macOS or Windows, capped by its memory ceiling. Fresh VMs without a PID and accepted runners reserve that estimate before boot. An unavailable measurement falls back to the configured ceiling. Footprints and host pressure are cached for five seconds.

A new VM starts only if its estimate fits the remaining budget and host memory pressure is normal. Warning or critical returns memory_pressure; insufficient budget returns memory_budget_exceeded, both with next steps. Unknown pressure is treated as normal and exposed as pressureKnown: false. Startup separately checks available host memory against the same estimate, rather than the full ceiling. Inspect vectis status --json for runnerCapacity.budget and per-environment slots.

This budget gates new starts; running VMs can grow beyond it and are not stopped when it is lowered or pressure rises. Memory touched by a guest may remain allocated until the disposable VM exits. Free host memory or stop idle VMs before retrying a refused start. The two-macOS-VM limit remains unchanged.

If a selected directory disappears, Vectis reports storage_unavailable. Reconnect the drive before retrying. It does not silently recreate a missing selected directory on the system disk. Storage is currently identified by path, so verify that the intended drive is mounted there.

Understand disk usage

vectis storage --json

The report separates base images from active and interrupted instances and includes a host-file breakdown when inspection succeeds.

Sparse files can have a large capacity and use fewer host blocks. Copy-on-write clones can share blocks, so summing allocatedBytes does not measure exclusive physical consumption. Guest filesystem breakdown is currently unavailable: the report cannot yet tell you how much space is used by guest packages, caches, or build files inside a disk image.

Background access to external storage

A path that works from Terminal may still be inaccessible to the installed background runtime. Keep the volume mounted and check the runtime’s access under System Settings > Privacy & Security > Files and Folders. Selecting a folder in the desktop does not by itself prove that the independent service has permission to read it. Vectis does not grant Full Disk Access or change system privacy settings automatically.

Storage measurements run in a separate owned process with a deadline. A blocked or unavailable volume returns an unavailable result with next steps instead of leaving the measurement pending indefinitely. Concurrent requests share the current measurement, and stopping the service cancels it. This protects inspection; it does not bypass permission requirements for VM startup or image preparation.

Before starting a VM, Vectis also checks image reads and storage-directory access in a separate process. If access cannot be confirmed within five seconds, startup returns action_required with storage_access_required. No VM or work directory is created by that failed preflight. Resolve the permission or mount issue, then retry with a new operation key. This check cannot guarantee that a volume will remain connected or accessible throughout a later job.