Tailscale is a super-simple VPN that is easy to set up, and works well with BYOC satellites. This page documents the required configuration within Tailscale to enable BYOC.


  • Configure a subnet router to provide access to satellites for users on the VPN. This is required because satellites never join a VPN directly, and may change IP/DNS addresses frequently.

  • Configure Restricted Nameservers (Split DNS) to resolve custom DNS names, as required by your cloud provider.

  • If you are running Earthly from within a Kubernetes pod, or GHA runner; you may need to make use of the userspace networking mode.

    • When using userspace networking, you need to add a Global nameserver to your DNS settings.

Because network configuration can vary wildly across organizations and cloud providers, we've provided some further general guidance below.


  • Step-by-step instructions to configure a subnet router in AWS

    • If you have multiple cloud installations sharing a single subnet, the single subnet router can be shared.

  • It is required to add a Split DNS entry for the <aws-region>.compute.internal TLD, because Earthly uses the AWS internal DNS addresses to resolve satellites. To do this:

    • In the modal that appears, use:

      • x.x.0.2 as the nameserver address, where x is corresponds to the CIDR block allocated to your VPC.

      • Check the box for "Restrict to domain" to enable Split DNS.

Last updated