> ## Documentation Index
> Fetch the complete documentation index at: https://www.agent37.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# VM instances

> Run Docker, Kubernetes, databases, and Android emulators on a full virtual machine.

A `vm` instance is a whole Linux machine with its own kernel, not a sandbox. Everything on this
reference works the same way: the same keys, the same endpoints, the same URLs, the same billing.
What changes is what runs inside.

Reach for it when your workload needs the kernel itself:

* **Docker, Compose, and buildx.** Build and run containers, including ones that need privileged
  mode or their own networks.
* **Kubernetes.** k3s runs with its node Ready and pod networking working.
* **Databases.** Postgres, MySQL, Redis, anything with its own storage engine.
* **Android emulators.** `/dev/kvm` is present inside the machine, so an AVD boots with hardware
  acceleration instead of crawling.

A default instance is the right choice for everything else, and it starts faster.

## Create one

```bash curl theme={null}
curl -X POST https://api.agent37.com/v1/instances \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "template": "agent37-ubuntu",
    "type": "vm",
    "resources": { "cpu": 4, "memory": 8, "disk": 20 }
  }'
```

`agent37-ubuntu` is Ubuntu 26.04 with Docker, Compose, and buildx installed and `dockerd` already
running. It is built for this type, so it only runs as a `vm` and a create without
`"type": "vm"` is a `400`.

Your own [custom image](/docs/agents-api/custom-image) works too: pass `"type": "vm"` with any template.
Two things to know first:

* **A container runtime inside the machine must keep its data on your billed disk.** The writable
  root is an overlay, and pulling an image onto one fails. Point Docker at `$HOME` with
  `dockerd --data-root "$HOME/docker"` (or `/etc/docker/daemon.json`), and k3s with
  `--data-dir "$HOME/k3s"`. `agent37-ubuntu` already does this.
* **Your entrypoint is PID 1, and there is no init system.** An image whose entrypoint *is*
  systemd is not supported, the same as on Docker. Run your processes from your entrypoint, or
  install them and start them over [SSH](/docs/agents-api/ssh).

## Getting in

There is no routed web port by default: `agent37-ubuntu` serves nothing, so its `default_port` is
`null` and the bare instance URL has nothing behind it. Use [SSH](/docs/agents-api/ssh) for an
interactive shell (one `agent37 ssh setup` first), or [exec](/docs/agents-api/exec) for one-off
commands:

```bash curl theme={null}
ssh root@ab12cd34ef.agent37.app
```

Anything you do serve gets a URL like every other instance: `{id}-{port}.agent37.app` for your
workspace's keys, or a [public port](/docs/agents-api/public-ports) for an unauthenticated one.

## Sizing and price

The same four [shapes](/docs/agents-api/instance-sizing), and compute meters at 4x the default rate,
like a [Performance instance](/docs/agents-api/billing#default-and-performance-instances): a VM's RAM is
reserved for it alone and its vCPUs are its own. Disk is unchanged at \$0.09 per GB per month.

| cpu | memory | disk | Price at the default disk |
| - | - | - | - |
| 2 | 4 GB | 2-12 GB | \$17.96 per month |
| 4 | 8 GB | 2-20 GB | \$35.74 per month |
| 8 | 16 GB | 2-40 GB | \$71.48 per month |
| 16 | 32 GB | 2-80 GB | \$142.96 per month |

A funded workspace is required: add balance before the first create.

## Lifecycle

`stop`, `start`, `restart`, `update`, and `resize` all work, and your billed disk survives every
one of them. The machine cold-boots on `start` and on any `resize`, so in-memory state is lost:
anything that has to outlive a restart belongs in a file under `$HOME`.

Growing the disk extends it in place and your filesystem grows into the new space on the next
boot, so the data is kept. Disk only grows, as on every instance.

## Backups

[Backups](/docs/agents-api/instance-backups) work exactly as they do on any other instance: a week of
daily restore points plus one you take on demand, listed and restored by id, and a restore
replaces the data it finds rather than merging into it.

Two things are worth knowing on a VM. A backup is taken from the machine's disks, so it captures
what your programs have written to disk, not what they are still holding in memory: a database is
backed up the way pulling the power cord would leave it, and recovers on the next start the same
way. That is the same guarantee a VPS snapshot gives you, and it is why a backup that has to be
exact should be taken with the machine stopped, or alongside your database's own dump. And a
restore cold-boots the machine, so in-memory state is lost either way.

## What is not available yet

| | |
| - | - |
| [Auto-sleep](/docs/agents-api/instance-auto-sleep) | A VM stays running while idle. `stop` and `start` work and release the compute charge; `auto_sleep` is refused. |
| Fork | Not yet available on a VM. |
| Changing type | An instance is a VM or it is not, for its whole life. To move, create the one you want and copy your data across. |

Everything else on this reference behaves identically: [public ports](/docs/agents-api/public-ports),
[domains](/docs/agents-api/domains), [SSH keys](/docs/agents-api/ssh), [logs](/docs/agents-api/logs),
[metrics](/docs/agents-api/metrics), and [exec](/docs/agents-api/exec). [Crons](/docs/agents-api/crons) post a
prompt to an agent's chat API, so they need a template that serves one: `agent37-ubuntu` does not
and refuses them, while your own image takes them like any other instance.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.