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

JavaScript and Python

JavaScript and Python can optionally be included in a vm using the with property. This will install the required dependencies on the VM, cache them in a base layer, and provide helper utilities for interacting with them. The first time you create a vm with a unique configuration, it may take longer while we create cache. To learn more about how with works and how to create your own VmWith classes, see Composing VMs (VmWith).

If you're exclusively need to execute JavaScript or TypeScript, you should also consider using Execute Api.

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

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

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

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. If you plan to make many VMs with similar configuration, see Templates and Snapshots.

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",
});