Lifecycle

Working Directory

Set the default directory for commands and file operations:

import { freestyle } from "freestyle-sandboxes";

const { vm } = await freestyle.vms.create({
  workdir: "/app",
  gitRepos: [
    { repo: repoId, path: "/app" },
  ],
});

// Commands run in /app by default
await vm.exec("npm install"); // Runs in /app
await vm.exec("ls"); // Lists /app contents

Without a working directory, commands run in /root:

const { vm } = await freestyle.vms.create();
await vm.exec("pwd"); // Output: /root

Idle Timeout

Automatically suspend VMs after a period of network inactivity (default: 300 seconds):

const { vm } = await freestyle.vms.create({
  idleTimeoutSeconds: 600, // 10 minutes
});

Set to null to disable idle timeout:

const { vm } = await freestyle.vms.create({
  idleTimeoutSeconds: null, // Never auto-suspend
});

Cost consideration: VMs with no idle timeout continue running (and billing) indefinitely. Use persistence settings to control storage costs when suspended.

Root Filesystem Size

Control the size of the VM's root filesystem (default: 16 GB):

import { VmSpec } from "freestyle-sandboxes";

const spec = new VmSpec({
  rootfsSizeGb: 32,
});

const { vm } = await freestyle.vms.create({ spec });

Resizing After Creation

The filesystem can be resized after creation:

await vm.resize({ rootfsSizeGb: 64 }); // Resize to 64 GB

Note: You can only increase the size, not decrease it.

Ready Signals

Control when the VM creation API call returns by waiting for the VM to be fully ready:

const { vm } = await freestyle.vms.create({
  waitForReadySignal: true,
  readySignalTimeoutSeconds: 120, // Default: 120 seconds
});

By default (waitForReadySignal: false), the API returns as soon as the serial console shows the login prompt. This typically takes 1-2 seconds.

When waitForReadySignal: true, the API waits for the VM to be fully booted and ready to accept commands before returning.

Note: In the future, this will be configurable to wait for custom readiness conditions like systemd service health checks or application-specific signals.

Recreate

Allow the VM to be recreated automatically if deleted:

const { vm, vmId } = await freestyle.vms.create({
  recreate: true,
  gitRepos: [
    { repo: repoId, path: "/app" },
  ],
});

// Delete the VM
await freestyle.vms.delete({ vmId });

// The VM can be recreated with the same ID and configuration
const recreated = await vm.start(); // Automatically recreates

This is useful for:

Serverless-style workloads
Cost optimization (delete when not in use)
Automatic recovery from failures

Common Patterns

Development VM with long timeout

const { vm } = await freestyle.vms.create({
  workdir: "/workspace",
  idleTimeoutSeconds: 3600, // 1 hour
  gitRepos: [
    { repo: repoId, path: "/workspace" },
  ],
});

Production VM (never suspend)

const { vm } = await freestyle.vms.create({
  idleTimeoutSeconds: null,
  persistence: { type: "persistent" },
  waitForReadySignal: true,
});

Serverless-style VM

const { vm } = await freestyle.vms.create({
  recreate: true,
  idleTimeoutSeconds: 60, // Suspend quickly
  persistence: { type: "ephemeral" },
});

Large data processing VM

const spec = new VmSpec({
  rootfsSizeGb: 100,
});

const { vm } = await freestyle.vms.create({
  spec,
  idleTimeoutSeconds: null, // Don't suspend during processing
});

// Resize if needed later
await vm.resize({ rootfsSizeGb: 200 });