Domain Mappings

Create, list, and delete mappings from custom domains to VM ports.

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

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:

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

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

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:

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.