Install a Gateway

A Gateway in your network runs as a service on a Windows or Linux machine next to the systems your agents use. It only ever connects out to Gatelion: nothing connects in from the internet. Allow about 10 minutes.

What you need#

• A machine in your network running one of:
  • Windows Server 2019 or later, or Windows 10/11 (x64).
  • Linux with systemd, such as Ubuntu 20.04+, Debian 11+ or RHEL 8+ (x64 or ARM64).
• Administrator rights on it: Administrator on Windows, sudo on Linux.
• Outbound HTTPS from that machine to the Gatelion Control Plane.
• About 200 MB of disk space.

There's nothing else to install. The package includes everything it needs to run.

1. Add the Gateway in the console#

If the code expires before you install, click Not registered yet: get a new code on the Gateway's row. The panel shows new commands with the new code.

Without a new code on screen, the same panel is shown at the bottom of the Gateways page as Install a Gateway in your network. Its commands don't include a code, so the installer asks for one.

2. Install it#

Pick your system's tab, then either click Download for … and run the installer yourself, or copy the commands. The commands download the package, check its checksum, unpack it and run the installer.

Linux#

On the server, the commands look like this:

curl -fLO <download address from the console>
echo "<sha-256 from the console>  <package file name>" | sha256sum -c -
tar -xzf <package file name>
cd <package folder>
sudo ./install.sh --control-plane <your Control Plane address> --code gwreg_…

There are separate packages for x64 and ARM64 machines. Pick the tab that matches yours: Linux (x64) or Linux (ARM64).

Windows#

In PowerShell as Administrator, the commands look like this:

Invoke-WebRequest <download address from the console> -OutFile <package file name>
if ((Get-FileHash <package file name> -Algorithm SHA256).Hash -ne "<SHA-256 FROM THE CONSOLE>") { throw "The download is damaged. Download it again." }
Expand-Archive <package file name> -DestinationPath . -Force
cd <package folder>
powershell -ExecutionPolicy Bypass -File .\install.ps1 -ControlPlaneUrl <your Control Plane address> -RegistrationCode gwreg_…

-ExecutionPolicy Bypass lets this one script run on machines that block downloaded scripts. It changes nothing else.

What the installer asks#

The installer asks for anything the command didn't give it.

Options#

What the installer does#

1. Installs the program.
2. Writes the settings file.
3. Creates the service, which starts with the machine and restarts after a failure.
4. Starts it and waits until the Gateway has registered with Gatelion.

At the end it prints the address agents connect to. Within a minute, the Gateway's row on the Gateways page shows a recent Last sync and its version.

3. Connect agents#

Agents connect to https://<this machine>:5200/mcp (or the port you chose), with an agent token from Tools & agents → Agents. Without a certificate the address starts with http://. See Agents and tokens and Connect an MCP client.

4. Give it your systems' secrets#

In the console, a connection to a system only names its secrets, for example ERP_API_KEY. The values never leave this machine: they live in the Secrets section of the Gateway's settings file, gateway.json.

{
  "Urls": "http://0.0.0.0:5200",
  "Gateway": {
    "ControlPlaneUrl": "<your Control Plane address>",
    "RegistrationCode": "gwreg_…",
    "AllowedPrivateNetworks": [ "10.0.0.0/8" ]
  },
  "Secrets": {
    "ERP_API_KEY": "<the API key>",
    "ERP_TOKEN": { "Value": "<a token only sent to one host>", "AllowedHosts": [ "erp.internal.example" ] }
  }
}

• A secret is either "NAME": "value", or an object with Value and AllowedHosts. With AllowedHosts, the Gateway sends the secret only to those hosts.
• Names must match the names in the connection exactly.
• Edit the file as an administrator, then restart the Gateway.

If a secret is missing, calls to that system fail with credential_missing and nothing is sent. See Connect a system.

Where things are#

The service runs as its own account with no other rights: the gatelion user on Linux, in a systemd sandbox that can write only its data folder, and NT SERVICE\GatelionGateway on Windows. Only that account and administrators can read the settings and data.

Use HTTPS#

Agents send their token to the Gateway with every call. Over plain HTTP, anyone who can watch your network traffic can read it. Give the Gateway a certificate, and agents connect over HTTPS instead. From version 0.3.0, the installer sets this up.

The certificate:

• It's for the name agents use to reach this machine, for example gateway.corp.example.
• It's issued by an authority your agents' machines trust, such as your company's certificate authority.
• On Linux: a PEM certificate and its private key, the key without a password.
• On Windows: a .pfx file with its password, or a PEM certificate and key.

At install, give it when the installer asks, or on the command line:

sudo ./install.sh --certificate cert.pem --certificate-key key.pem

.\install.ps1 -Certificate gateway.pfx

On a Gateway that's already installed, run the same version's installer with just the certificate options. It keeps the settings and registration, copies the certificate next to the settings, and restarts the Gateway.

What changes:

• The same port then serves HTTPS only, so give agents the https:// address.
• The Gateway's row on the Gateways page stops showing Plain HTTP after its next sync.
• To renew the certificate, run the installer again with the new files.
• To go back to plain HTTP, run it with --no-https or -NoHttps.

If a reverse proxy you already run adds HTTPS in front of the Gateway, you don't need a certificate on the Gateway. The Gateways page still shows Plain HTTP, because the Gateway only knows how it listens itself.

If the Gateway doesn't start after you add a certificate:

• check that the key matches the certificate;
• on Linux, check that the key has no password;
• on Windows, check the .pfx password.

The log says which.

Upgrade#

The Gateways page marks a Gateway update available when a newer version is out. To upgrade:

The installer sees the existing settings file and asks nothing. It stops the Gateway, replaces the program and starts it again. Settings, secrets, key, registration and port are kept. Within a minute, the Gateway's row shows the new version.

Uninstall#

Without the purge option, settings and data stay, so installing again later picks up the same registration, as long as you haven't retired the Gateway. With it, the key and registration are gone, and a new install needs a new registration code.

Then, on the Gateways page, turn off the Gateway's Running switch and click Retire under it. A retired Gateway is refused for good and no longer counts toward your limits; its history stays. See Retire a Gateway.

Troubleshooting#

Related: Gateways · Connect a system

Still stuck? Contact support from the console.