Freestyle VMs

Create and control fast Linux virtual machines for agent workspaces and user sessions.

Freestyle VMs are full Linux virtual machines designed for long running, complex tasks. They start quickly, can stop when idle, and can be started again by API calls, SSH, or network activity.

Create A VM

import { freestyle } from "freestyle";

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

const result = await vm.exec("echo 'hello from freestyle'");
console.log(result);

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);

Size A VM

VMs start with 4 vCPU, 8 GB RAM, and a 20 GB root filesystem by default. To size a VM for your workload, call vm.resize() after creating it.

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

Clone A Repository

VMs work well with Freestyle Git repositories. Create or import code into Git, grant access through your application, then clone and run it inside the VM.

const { repoId } = await freestyle.git.repos.create({
  name: "workspace",
});

const { identity } = await freestyle.identities.create();
await identity.permissions.git.grant({ repoId, permission: "read" });
const { token } = await identity.tokens.create();

const { vm } = await freestyle.vms.create();
await vm.exec("mkdir -p /workspace");
await vm.exec(
  `git clone https://x-access-token:${token}@git.freestyle.sh/${repoId} /workspace`,
);

await vm.exec("ls -la");

Common Operations

await vm.exec("pwd");
await vm.start();
await vm.stop();
await freestyle.vms.delete({ vmId });

Route Web Traffic

Attach a custom domain to a VM service by mapping a public hostname to a VM port.

await freestyle.domains.mappings.create({
  domain: "app.example.com",
  vmId,
  vmPort: 3000,
});

See VM Domains for verification, DNS, and mapping setup.