Integrations

Integrations are composable packages that extend your VMs with additional capabilities. They handle installation, configuration, caching, and expose convenient helper methods. Use them to add language runtimes, databases, headless browsers, third-party services, and more.

You can add as many integrations as you need to a single VM.

Available Integrations

Node.js

JavaScript/TypeScript runtime via NVM

Python

Python 3 runtime

Deno

Secure JavaScript/TypeScript runtime with npm and JSR support

Bun

Fast JavaScript runtime and toolkit

Ruby

Ruby runtime via RVM

uv

Fast Python package management and runtime

Java

Java runtime via Amazon Corretto

PostgreSQL

Declarative PostgreSQL server, databases, and SQL scripts

OpenCode

AI-powered coding assistant

Web Terminal

Interactive web-based terminals via ttyd

Usage

Add integrations using the with property when creating a VM:

import { freestyle, VmSpec } from "freestyle";
import { VmNodeJs } from "@freestyle-sh/with-nodejs";

const { vm } = await freestyle.vms.create(
  new VmSpec().with("js", new VmNodeJs()),
);

// Use the integration's helper methods
const res = await vm.js.runCode({
  code: 'console.log(JSON.stringify({ hello: "world" }))'
});

console.log(res.result); // { hello: "world" }

Caching

Integrations are automatically cached. The first VM with a specific integration configuration takes longer while the environment is built. Subsequent VMs with the same configuration start instantly.

Multiple Integrations

You can combine as many integrations as you need in a single VM:

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

const { vm } = await freestyle.vms.create({
  spec: new VmSpec()
    .with("node", new VmNodeJs())
    .with("python", new VmPython())
    .with("bun", new VmBun()),
});

// Each integration is available on the vm object
await vm.node.runCode({ code: 'console.log("Node.js")' });
await vm.python.runCode({ code: 'print("Python")' });
await vm.bun.runCode({ code: 'console.log("Bun")' });

Custom Integrations

You can create your own integrations by extending the VmWith class. See Custom Integrations for details.