Getting Started with VMs

Sign up at admin.freestyle.sh, create an api key, and configure it in your environment.

FREESTYLE_API_KEY=your-api-key

npm i freestyle-sandboxes@beta

Creating a VM

Calling create in the vms namespace will create and start a vm. This VM will be created from the default snapshot configured for your account. This should usually take less than 2 seconds, but your first VM may take longer while we provision dedicated cache for your account.

import { freestyle } from "freestyle-sandboxes";

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

// exec a shell script
await vm.exec("echo 'hello world'");
await vm.fs.writeTextFile("/tmp/hello-world.txt", "Hello World!");

Code Execution

VMs can execute code with built-in language support for Node.js, Python, Bun, Ruby, Java, and more. See Integrations for the full list.

import { freestyle } from "freestyle-sandboxes";
import { VmNodeJs } from "@freestyle-sh/with-nodejs";
import { VmPython } from "@freestyle-sh/with-python";

const { vm } = await freestyle.vms.create({
  with: {
    js: new VmNodeJs(),
    python: new VmPython(),
  },
});

await vm.js.runCode(`console.log("Hello World!")`).then(console.log);
await vm.python.runCode(`print("Hello World!")`).then(console.log);

The first time you create a VM with a unique configuration, it may take longer while we build and cache the environment. Subsequent VMs with the same configuration start instantly.

For languages without a prebuilt integration, you can build your own. If you exclusively need to execute JavaScript or TypeScript without a full VM, consider using Serverless Runs for lower latency.

More complex VM creation

We allow you to configure files, repos, workdir, and much more in the same request you create the VM so you can minimize chatter and maximize reliability. In addition to the VM class, we also return data specific to the create api call which can be accessed in the returned object. See VM Configuration for all available options, or Templates and Snapshots if you plan to make many VMs with similar configuration.

import { freestyle } from "freestyle-sandboxes";

const { vmId, vm, domains, consoleUrl } = await freestyle.vms.create({
  additionalFiles: {
    "/repo/README.md": {
      content: "# Hello World",
    },
  },
  gitRepos: [
    {
      repo: "https://github.com/freestyle-sh/freestyle-base-nextjs-shadcn",
      path: "/repo",
    },
  ],
  workdir: "/repo",
});