---
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 be suspended when idle, and can be resumed 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);
```


## Clone A Repository

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

```ts
const { repo } = await freestyle.git.repos.create({
  import: {
    type: "files",
    commitMessage: "initial commit",
    files: {
      "README.md": { content: "# Hello" },
    },
  },
});

const { vm } = await freestyle.vms.create({
  gitRepos: [
    {
      repo: repo.id,
      path: "/workspace",
    },
  ],
  workdir: "/workspace",
});

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


## Common Operations

```ts
await vm.exec("pwd");
await vm.suspend();
await vm.start();
await vm.stop();
await freestyle.vms.delete({ vmId: vm.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: vm.vmId,
  vmPort: 3000,
});
```

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