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 |
gitRepos | 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 |
idleTimeoutSeconds | Auto-suspend after inactivity | Lifecycle |
rootfsSizeGb | Root filesystem size | Lifecycle |
workdir | Default working directory | Lifecycle |
waitForReadySignal | Wait for VM to be fully ready | Lifecycle |
recreate | Allow automatic recreation | Lifecycle |
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-sandboxes";
const spec = new VmSpec({
workdir: "/app",
gitRepos: [{ repo: "owner/app", path: "/app" }],
systemd: {
services: [
{ 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,
});