VPCs

VPCs let Freestyle VMs communicate over private IP addresses. Use them when a group of VMs should share an internal network for databases, services, worker pools, or agent environments that should not depend on public VM domains.

Terms

• A VPC is a private network for your VMs. VMs in the same VPC can talk to each other without using public domains.
• A private IP is an address that only works inside the VPC, like 192.168.10.10.
• A CIDR is the address range for the VPC. 192.168.10.0/24 means addresses from 192.168.10.1 through 192.168.10.254 are available for VMs.
• A NIC is a network interface on a VM. Attaching a NIC to a VPC is how the VM joins the private network.

Create A VPC

import { freestyle } from "freestyle";

const { vpcId, vpc } = await freestyle.vpc.create({
  name: "workspace-network",
  cidr: "192.168.10.0/24",
});

console.log(vpcId);

The VPC CIDR is the private address range available to VMs attached to the network. Pick a range that does not overlap with your home, office, or VPN network.

Attach VMs

Attach a VM by passing a routed network interface in vms.create:

const { vm: apiVm } = await freestyle.vms.create({
  internet: "disabled",
  nics: [
    {
      default: true,
      vpc: vpcId,
      mode: "routed",
      ipv4: "192.168.10.10",
      routes: [{ cidr: "0.0.0.0/0", via: "192.168.10.1" }],
    },
  ],
});

const { vm: workerVm } = await freestyle.vms.create({
  nics: [
    {
      default: true,
      vpc: vpcId,
      mode: "routed",
      ipv4: "192.168.10.11",
    },
  ],
});

Use default: true when the VPC interface should be the VM’s default route. Use mode: "routed" for VPC networking.

Set internet: "disabled" when the VM should not receive Freestyle’s host-provided internet route. Use NIC routes to configure guest routes through another VM in the VPC, such as a router VM at 192.168.10.1. If internet is omitted, VMs keep the existing host NAT internet behavior.

Test Private Connectivity

VMs in the same VPC can reach each other by private IP:

const result = await apiVm.exec("ping -c 3 192.168.10.11");
console.log(result.stdout);

Run services on 0.0.0.0 inside the destination VM when other VMs should connect to them. Run it under systemd so it stays up across the VM’s life:

const python = (await workerVm.exec("command -v python3")).stdout!.trim();

await workerVm.fs.writeTextFile(
  "/etc/systemd/system/http.service",
  `[Service]
ExecStart=${python} -m http.server 8080 --bind 0.0.0.0
Restart=always
[Install]
WantedBy=multi-user.target`,
);
await workerVm.exec("systemctl daemon-reload && systemctl enable --now http");

Then connect from another VM over the VPC address:

const response = await apiVm.exec("curl http://192.168.10.11:8080");
console.log(response.stdout);

Connect From Your Computer

Use VPNs to create an ephemeral WireGuard connection from your computer into a VPC.

Current Limits

• VPC VM interfaces use mode: "routed".
• A VM can attach one routed VPC interface.
• Choose a VPC CIDR that does not overlap with networks your VM or VPN client already uses.