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({
  nics: [
    {
      default: true,
      vpc: vpcId,
      mode: "routed",
      ipv4: "192.168.10.10",
    },
  ],
});

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.

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:

await workerVm.exec(
  "nohup python3 -m http.server 8080 --bind 0.0.0.0 >/tmp/http.log 2>&1 &",
);

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.