Freestyle VMs

Freestyle VMs are full Linux virtual machines designed for long-running, complex tasks. They start quickly, persist their files, can preserve memory while paused, and wake in response to API calls or network traffic.

Create A VM

import { Freestyle } from "freestyle";

const freestyle = new Freestyle();
const { vm, vmId, data } = await freestyle.vms.create({
  // Required: a VM reaches nothing it has not been allowed to.
  firewall: { rules: [{ action: "allow", source: {}, destination: { public: true } }] },
  slug: "development",
  metadata: { project: "website" },
});

const result = await vm.exec("echo 'hello from freestyle'");
console.log(vmId, data.state, result.stdout, result.statusCode);

IDs and your account-local slugs are accepted anywhere the SDK asks for a VM. Use freestyle.vms.ref("development") to construct a handle without fetching the VM first.

displayName is there for a slug that does not read as a name — one minted per run or per tenant. It is shown in place of the slug.

Work With Files

await vm.fs.writeTextFile("/tmp/hello.txt", "Hello from Freestyle");

const content = await vm.fs.readTextFile("/tmp/hello.txt");
console.log(content);

See Files for binary files, large resumable uploads, streaming downloads, directories, and the CLI.

Resize A VM

CPU is measured in vCPUs; memory and storage are measured in MiB.

await vm.resize({
  cpu: 8,
  memory: 16 * 1024,
  storage: 80 * 1024,
});

All three dimensions are grow-only. CPU and memory resize live on a running VM; disk growth requires a running VM. See VM Lifecycle.

Common Operations

const current = await vm.data();
await vm.update({ idleTimeoutSeconds: 600 });
await vm.pause();
await vm.start();
await vm.delete();

To stop a persistent VM without deleting it, power it off from inside the guest. vm.exec() accepts a command string or an object with command, timeoutMs, env, and base64-encoded stdin. The maximum timeout is five minutes; use a PTY session for longer interactive work.

Networking And Domains

Attach a VM to a private network at creation time, or route a public HTTPS domain to a guest port with a TLS rule:

const { vm: privateVm } = await freestyle.vms.create({
  // Required: a VM reaches nothing it has not been allowed to.
  firewall: { rules: [{ action: "allow", source: {}, destination: { public: true } }] },
  networks: [{ vpc: "private-workers", ipv4: true }],
});

await freestyle.tls.rules.create({
  action: "allow",
  domain: "app.example.com",
  source: { public: true },
  destination: { vmId, port: 3000 },
});

See VPCs, tunnels, TLS, and VM Domains.