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 |
ports | Expose services to the internet | Ports and Networking |
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 Templates
Put configuration in a VmTemplate for automatic caching:
import { VmTemplate } from "freestyle-sandboxes";
const template = new VmTemplate({
workdir: "/app",
gitRepos: [{ repo: "owner/app", path: "/app" }],
systemd: {
services: [
{ name: "web", mode: "service", exec: ["npm start"], workdir: "/app" },
],
},
});
// First call builds and caches the template
const { vm } = await freestyle.vms.create({ template });
// Subsequent calls are instant
const { vm: vm2 } = await freestyle.vms.create({ template });See Templates and Snapshots for more details on caching.
Combining Both
Apply dynamic configuration on top of a template:
const { vm } = await freestyle.vms.create({
template, // Base configuration (cached)
// Dynamic config applied on top
additionalFiles: {
"/app/.env": { content: `API_KEY=${process.env.API_KEY}` },
},
idleTimeoutSeconds: 300,
});