---
title: "Freestyle VMs"
description: "Create and control fast Linux virtual machines for agent workspaces and user sessions."
url: "/docs/vms"
---

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

```ts
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

```ts
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.

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


## Clone A Repository

VMs work well with [Freestyle Git](https://www.freestyle.sh/docs/git) repositories. Create or import code into Git, grant access through your application, then clone and run it inside the VM.

```ts
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

```ts
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.

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

See [VM Domains](https://www.freestyle.sh/docs/vms/domains) for verification, DNS, and mapping setup.