Add a Grid

A Grid is the device that serves as the entry and exit point of your VPN network, and you can place one at each location, such as your home and your parents’ home, or your home and your office. HomeGrid VPN lets you register a Grid from the dashboard in one of three ways: the Linux install command, Docker, or the virtual appliance (ISO). Pick the method that fits the device, then follow its steps below.

Register your first Grid from the “Grid Setup” panel on the dashboard. For your second and later Grids, use “Add a Grid” inside the same panel. The methods and steps are the same either way.

What changes when you add a Grid

When you add a Grid, it appears in the “Grid Setup” list. Only one Grid in the list serves as the exit to the internet. You can choose which Grid is the exit from the list after registering it.

A Grid you add appears in the list and can be selected as the exit

Choose a method

Choose one of the three methods based on the device that will be the Grid.

Method	Suitable devices	Dashboard panel
Linux install command	A Linux machine that uses apt and systemd (such as Ubuntu)	The panel with the “Generate install command” button
Docker	A native Linux host with Docker installed (such as a NAS or another Linux machine), or Docker Desktop on a stationary Windows PC or Mac (with conditions)	“Setting up with Docker (NAS, Linux, or Docker Desktop on Windows / Mac)”
Virtual appliance (ISO)	Your own VM (Proxmox, VMware, and so on) or a mini PC	“Set up with a virtual appliance (ISO)”

The Docker version also runs on Docker Desktop for Windows (using WSL 2) and for macOS. Use it under these conditions:

Use a stationary machine (such as a Mac mini, iMac, Mac Studio, or a desktop Windows PC). Laptops that you carry around, such as a MacBook, are not supported.
Set Docker Desktop to start automatically when you sign in.
Turn off sleep.

After a restart (for an OS update, a power outage, and so on), the Grid does not run until you sign in once.

Before you begin

Connect the device that will be the Grid to the LAN of your home router.
Giving the Grid a name makes it easier to tell apart in the list. Use lowercase letters, numbers, and hyphens (for example, parents-house).

Method A: Linux install command

Sign in to the dashboard and open the “Grid Setup” panel. For your second and later Grids, use “Add a Grid” inside the panel.

Screenshot (to be replaced): the “Add a Grid” panel on the dashboard
Enter a name in “Grid name (optional)”. If you leave it blank, the name shown in light text in the field (“Defaults to …”) is used.
Click “Generate install command”.
Run the command shown under “Run the following command on your Grid device:” on the device that will be the Grid.

Screenshot (to be replaced): the generated install command, with the command itself blurred

The generated command contains information for registering your Grid. Do not show it to anyone or paste it into chats or social media.
The dashboard shows “Waiting for Grid to connect… (checking every 5 seconds)”. Keep the page open and wait until the Grid connects.

Method B: Docker

In the “Setting up with Docker (NAS, Linux, or Docker Desktop on Windows / Mac)” panel, click “Generate a serial number and the install command”.
Check that “Serial number:” is shown.
In “Your home LAN subnet (CIDR)”, enter the subnet of the home LAN where the Grid is placed, in CIDR notation.

The subnet you enter is registered as a LAN ACL destination (Grid LAN).
Click “Copy docker run command”.

Screenshot (to be replaced): the Docker panel, with the serial number and the command blurred
Run the copied command on the machine where Docker runs (a Linux host, or Docker Desktop on Windows or Mac).

Do not show the serial number or the docker run command to anyone.

Method C: Virtual appliance (ISO)

In the “Set up with a virtual appliance (ISO)” panel, click “Go to virtual appliance setup →”. The “Virtual Appliance Setup” page opens.
Click “Download appliance image (~2.9GB)” to download the ISO.
For a virtual machine, attach the ISO as a CD-ROM and boot from it. For physical hardware (such as a mini PC), write the ISO to a USB drive and boot from the USB drive. The installation runs automatically and the machine restarts when it finishes.

On physical hardware, the whole PC becomes a dedicated appliance. It cannot keep an existing OS or data alongside the appliance, so use a PC that you can wipe. After the installation finishes and the machine restarts, remove the USB drive.
Connect the device to your home router’s LAN. For a virtual machine, set its network to bridged networking.
Go back to the setup page and enter a name in “Grid name”.
Click “Issue an activation token”.
Click “Copy” next to the token that appears.

Screenshot (to be replaced): the activation token panel, with the token blurred
When the device’s console shows Please enter your Node Token:, enter the token. When registration finishes, the console shows that the device has connected.

A token is valid for one hour and can be used only once. If it expires, click “Issue an activation token” again.

Check that the Grid was added

For your first Grid, it is connected when the status at the top right of the “Grid Setup” panel changes from “Pending” to “Active”.
For your second and later Grids, the name of the Grid you added appears in the “Grid Setup” list. It is connected when the status to the right of the name changes from “Pending” to “Active”.

Screenshot (to be replaced): the list showing the Grid you added

To switch the exit

Adding a Grid does not change the exit. Choose the exit Grid from the list. The steps are in “Switch the internet exit”.