---
title: "Domain Mappings"
description: "Create, list, and delete mappings from custom domains to VM ports."
url: "/docs/vms/domain-mappings"
---

A domain mapping connects one public hostname to one port inside a VM. Use mappings when you want to attach or move domains after a VM already exists.


## Create A Mapping

```ts
import { freestyle } from "freestyle";

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

The VM service must listen on `vmPort`. For web servers, bind to `0.0.0.0` so traffic from outside the VM can reach the process.


## Map During VM Creation

When you already know the ports at create time, pass `domains` to `freestyle.vms.create`:

```ts
const { vmId, domains } = await freestyle.vms.create({
  domains: [
    { domain: "app.example.com", vmPort: 3000 },
    { domain: "admin.example.com", vmPort: 4000 },
  ],
});

console.log(vmId);
console.log(domains);
```


## List Mappings

```ts
const { mappings } = await freestyle.domains.mappings.list({
  domain: "app.example.com",
  limit: 50,
});

for (const mapping of mappings) {
  console.log(mapping.domain, mapping.vmId, mapping.vmPort);
}
```


## Delete A Mapping

```ts
await freestyle.domains.mappings.delete({
  domain: "app.example.com",
});
```

Deleting a mapping stops new traffic from routing to that VM port. It does not delete the VM, DNS record, or domain verification.


## Multiple Ports

Use separate domains for separate VM services:

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

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

Each domain gets HTTPS automatically after DNS and mapping are in place.