Skip to content
by Shift Engineering

Connect your network to a private install

Admin guide

A private install has no public address: people and agents reach Greenlight only from your company’s network. This page is for whoever connects that network. It works the same on Azure, Google Cloud, and AWS, with the differences called out where they matter.

  1. Decide before you install. How people reach Greenlight, whether its egress goes through your firewall, and its network range.
  2. Connect your network, through Private Link or peering.
  3. Publish internal DNS for Greenlight’s two names.
  4. Verify from your network and from the internet.
  5. Keep it working as accounts and networks change.

The desktop installer app walks you through steps 2 to 4 at the end of a private install, and sends your answers to the setup wizard once this computer reaches Greenlight. If you get stuck, email the Greenlight team at support@shifthq.ai.

1. Decide before you install

Section titled “1. Decide before you install”
Private Link (recommended) Peering
How it connects An endpoint in your network, one way into Greenlight The two networks are joined and route both ways
Address ranges May overlap with Greenlight’s Must not overlap
Who connects Only the accounts you list Anything that can route to Greenlight’s network

You can run both side by side, for example Private Link for most people and peering for a network that needs it.

  • Egress through your firewall needs peering, because Greenlight’s route to your firewall runs over it, even when people come in through Private Link. It is available on Azure today; on Google Cloud and AWS the installer refuses --egress-next-hop and egress leaves the way a public install’s does.
  • Greenlight’s network range is fixed once installed. It must not overlap yours if you peer, and on Google Cloud and AWS it must be a /20 or wider.
  • Accounts allowed to connect (Private Link only): your Azure subscription IDs, Google Cloud project IDs, or AWS account IDs.
  • Your firewall’s private address, if egress goes through it.
  • Who your users are: the networks they come from (offices, VPN pools, overlay connectors such as Tailscale or Twingate). They need TCP 443, and TCP 80 for the first install’s setup wizard.
  • Who owns internal DNS for the Greenlight host, for example greenlight.acme.com.

A marketplace install is public. A private install comes from the desktop installer app or the terminal installer.

More detail: AI clients that cannot reach a private install

Tools whose calls come from a vendor’s cloud cannot reach a private install: Claude.ai connectors, Claude Code on the web, and cloud agents. Desktop and command-line tools running on the company network can: Claude Code CLI and the Desktop Code tab, Cursor desktop, and Codex desktop.

2. Connect your network

Section titled “2. Connect your network”
Section titled “Private Link”

In one of the accounts you listed, create an endpoint in a network you own, aimed at the service identifier the installer printed. The connection is approved on its own, and an endpoint from any other account cannot connect. No routes are exchanged between the networks, and the endpoint is billed to your account.

The installer prints the Private Link Service’s alias. The endpoint can sit in any region.

In the Azure portal, create a private endpoint in your virtual network. Under Resource, choose Connect to an Azure resource by resource ID or alias and paste the alias.

Make sure your VPN, office, and overlay traffic can reach the endpoint’s subnet on TCP 443 and 80.

Peering

Section titled “Peering”
  • Peer your hub network with Greenlight’s network, or attach it through a transit gateway.
  • Add routes in both directions: your client ranges into Greenlight’s network, and Greenlight’s range from every entry point into yours.
  • Filter at your own firewall. Peering exposes every Greenlight subnet, and Greenlight’s load balancer accepts TCP 80 and 443 from anything that can route to it.
More detail: egress through your firewall (Azure)

The installer points Greenlight’s default route at your firewall. Also route Greenlight’s range through the firewall from every entry point into your network (the VPN gateway, your core network). Otherwise replies take a different path from requests, and a stateful firewall drops them: the dashboard times out over the VPN while the installer’s own checks pass.

Allow Greenlight’s outbound destinations, which the Azure guide lists, plus each integration you register, since Greenlight calls its upstream through the firewall too. Internal Health → Cluster health has an Egress section showing which destinations are reachable.

3. Publish internal DNS

Section titled “3. Publish internal DNS”

In your internal DNS, create two records for the names the installer printed:

Name What it serves Points at
greenlight.acme.com The dashboard and MCP Your endpoint’s private address (Private Link), or the internal load balancer address the installer printed (peering)
*.greenlight.acme.com Every app The same address

Make both names resolve from every network your people use: set your VPN’s DNS servers, and add forwarders from on-premises DNS if the zone lives in the cloud. If you use both paths, different groups of users can point at different addresses, and both work.

4. Verify

Section titled “4. Verify”
  • On the company network or VPN: both names resolve to the private address, and https://greenlight.acme.com loads with a valid certificate. On a first install, the setup wizard opens.
  • On the public internet: both names return “does not exist” (NXDOMAIN).
  • In Greenlight: the installer’s readiness check passed, and Greenlight’s outbound destinations are reachable.

Then, in the GitHub App’s settings, clear the webhook’s Active checkbox. GitHub cannot reach a private install, and a delivery log full of failures is the sign of leaving it on.

5. Keep it working

Section titled “5. Keep it working”
  • Changing the allowed accounts: rerun the installer with the new list. A removed account cannot make new connections; its existing endpoint keeps working until you reject that connection.
  • Turning Private Link off: this deletes the service and closes every endpoint’s connection. Turned on again later, the service gets a new identifier, so every endpoint is recreated and DNS updated.
  • Keep in place Greenlight’s view of the public zone.
  • Never change Greenlight’s network range.
More detail: rate limits, and reaching the cluster for installer reruns

Rate limits. Greenlight sees every Private Link connection arrive from one translated address, so all Private Link traffic shares one per-address rate limit, as it would behind any VPN that translates addresses. Sign-in, permissions, and audit identify people by their credentials, not by address.

Reaching the cluster. Installer reruns and your operators still call the cluster’s Kubernetes API from outside Greenlight’s network:

  • Azure: the API keeps a public endpoint that requires Azure sign-in.
  • Google Cloud: fetch credentials with --dns-endpoint; see the Google Cloud guide.
  • AWS: --kubernetes-api-allowed-ranges limits which addresses may call the API; see the AWS guide.

Switching an existing public install to private is a separate procedure, done in a maintenance window: see the private network section of the Azure, Google Cloud, or AWS guide.