FreestyleVM Configuration
Overview of all configuration options for Freestyle VMs.
When creating a VM, you can configure many aspects of its behavior and contents. This section covers all available configuration options.
Quick Reference
| Option | Description | Page |
|---|---|---|
additionalFiles | Add files to the VM filesystem | Files and Repos |
git / repo() | Clone git repositories | Files and Repos |
systemd | Define background services and startup tasks | Systemd Services |
domains | Map custom domains to VM ports | Domains |
users | Create Linux users | Users and Groups |
groups | Create Linux groups | Users and Groups |
persistence | Control VM storage strategy | Persistence |
recreate | Allow automatic recreation | Persistence |
idleTimeoutSeconds | Auto-suspend after inactivity | VM Lifecycle |
rootfsSizeGb | Root filesystem size | Hibernation Behavior |
waitForReadySignal | Wait for VM to be fully ready | Hibernation Behavior |
Configuration Methods
Direct Configuration
Pass options directly to freestyle.vms.create():
const { vm } = await freestyle.vms.create({
workdir: "/app",
idleTimeoutSeconds: 600,
additionalFiles: {
"/app/config.json": { content: "{}" },
},
});Using Specs
Put configuration in a VmSpec for reuse. Use it as a snapshot layer when you want caching:
import { VmSpec } from "freestyle";
const spec = new VmSpec()
.workdir("/app")
.repo("owner/app", "/app")
.systemdService({
name: "web",
mode: "service",
exec: ["npm start"],
workdir: "/app",
});
// Create a VM directly from the spec (no caching)
const { vm } = await freestyle.vms.create(spec);
// Use the spec as a snapshot layer to cache it
const { vm: vm2 } = await freestyle.vms.create({ snapshot: spec });See Specs and Snapshots for more details on caching.
Combining Both
Apply dynamic configuration on top of a spec (or a cached snapshot layer):
const { vm } = await freestyle.vms.create({
spec, // Base configuration (not cached unless used as a snapshot)
// Dynamic config applied on top
additionalFiles: {
"/app/.env": { content: `API_KEY=${process.env.API_KEY}` },
},
idleTimeoutSeconds: 300,
});