Connecting to On-Prem Systems

Use the superglue Secure Gateway when an agent needs to work with a system that is reachable only from your private network. A lightweight gateway process runs inside that network and opens an outbound encrypted connection to superglue. You do not need to expose the target publicly or add inbound firewall rules.

When to use the gateway

The gateway is intended for systems such as:

• Internal APIs and legacy applications behind a corporate firewall.
• PostgreSQL, SQL Server, Redis, or MongoDB instances in private subnets.
• SFTP servers and Windows file shares that are available only on the local network.
• Services inside a private cloud VPC or Kubernetes network.

Once connected, a private system behaves like any other superglue system: agents can configure its authentication and tools can read or write data through it.

How the connection works

1. The gateway connects to superglue over WebSocket Secure using an API key.
2. It registers only the target aliases listed in its configuration.
3. You create a Private System and select one connected gateway and target.
4. When an agent or tool calls that system, superglue opens a tunnel to the selected target for the request.

The gateway needs network access to its configured targets and outbound access to the configured WebSocket endpoint. Hosted superglue uses port 443. The gateway does not listen for inbound internet traffic.

Set up the gateway from superglue

This is the quickest way, and it needs no configuration file.

1. Open Systems, select Connect system, then Private System.
2. Select Set up a gateway (or Set up another gateway when one is already connected). Enter a gateway name, the targets, and the operating system of the machine. For QuickBooks Desktop or Sage 100 on Windows, also allow the script runner.
3. Copy the command and run it on the machine. On Windows, use PowerShell opened with Run as administrator. On Linux, use a terminal; the command needs curl or wget, and uses sudo when you are not root.
4. Keep the page open. It shows Connected when the gateway connects, and whether the gateway reaches each target. Then select Continue to create the private system.

You can also ask the superglue agent to connect a private system. When no gateway is connected, the agent shows the same setup in the chat with its suggestions filled in, and it continues on its own when the gateway connects.

The command downloads the gateway and installs it as a service that starts with the machine (a Windows service or a systemd unit). On Linux without systemd, for example in a container, it saves the program and the configuration and prints the command to start the gateway with your own process manager. It contains an API key named Gateway: <name> with the API & CLI: Write permission, which acts with the permissions of the person who created it. The command is shown only once. To disconnect the gateway, select Remove gateway next to it under Private System, or next to the tunnel status of a private system. This disconnects it and deletes the API keys you select (its Gateway: <name> keys are selected), and can also delete the private systems that use it. The gateway then stops and connects again only after a restart, and only if its key still exists. Older gateway versions reconnect unless their key is deleted. Each command creates a new key; delete older Gateway: <name> keys that you no longer use. To change the targets, set up the gateway again with the same name and run the new command on the same machine. To remove it, run sudo /usr/local/bin/superglue-gateway uninstall on Linux (without sudo as root), or & "C:\Program Files\superglue Gateway\superglue-gateway.exe" uninstall in PowerShell opened as administrator on Windows. On Windows, the service runs as the system account, so scripts from an enabled script runner run with full rights on that machine.

!

The install command contains a secret. Run it only on the target machine, and do not paste it into tickets or chats.

Set up the gateway by hand

1. Create an API key

Open API Keys under Control Panel, select New API Key, and copy the value into the gateway configuration. Use a separate, clearly named key for each gateway deployment.

!

Treat the gateway API key as a secret. Do not commit config.yaml, and rotate the key if it is exposed.

2. Download the gateway

Check the architecture of the host that will run inside your private network:

uname -m

Linux x86_64

curl -L https://downloads.superglue.cloud/superglue-gateway-linux-x86_64 -o superglue-gateway
chmod +x superglue-gateway

Linux arm64

curl -L https://downloads.superglue.cloud/superglue-gateway-linux-arm64 -o superglue-gateway
chmod +x superglue-gateway

Windows x86_64

Invoke-WebRequest -Uri https://downloads.superglue.cloud/superglue-gateway-windows.exe -OutFile superglue-gateway.exe

3. Configure allowed targets

The quickest way is the setup page. On Windows, double-click superglue-gateway.exe: when no valid config.yaml exists next to it, the gateway opens the setup page in your browser. On Linux, or to change an existing configuration, run ./superglue-gateway setup.

On the setup page, paste the API key, select superglue cloud or enter your self-hosted server, and test the connection. Then set the tunnel ID and add the targets. The page checks that each target is reachable from the gateway host and shows the system URL to use in superglue. Save and connect writes config.yaml and starts the gateway; the page then shows the connection status and the recent log. The page is reachable only from the gateway host, through the link the gateway opens or prints.

To configure the gateway by hand instead, create config.yaml next to the executable:

tunnel_id: "berlin-office"
server_url: "wss://api.superglue.cloud/ws/tunnels"
api_key: "sg_your_api_key"

targets:
  internal-api: "api.internal.example.com:443"
  finance-db: "10.20.0.15:5432"
  files: "10.20.0.30:445"

tunnel_id is a name you choose for this gateway, for example the site or host it runs on. It identifies the gateway when you connect a private system in superglue. Give each gateway its own tunnel_id: two gateways with the same ID replace each other’s connection.

You choose the targets freely. A target can be any destination the gateway host can reach on the network: a database, an internal API, a file server, or any other TCP service. Each entry maps a name you pick to a plain host:port address. The name is only an alias; it becomes the hostname in the system URL later. The protocol is also set later by the system URL in superglue, not by the gateway configuration.

Use lowercase letters, digits, -, and _ in target names. The setup page rejects other names. One gateway can register multiple targets, but it cannot reach destinations that are not explicitly listed, so the list doubles as an allowlist. To expose another destination, add a line and restart the gateway. For HTTPS and other TLS destinations, use the target’s real hostname instead of an IP address; the gateway uses it to establish the TLS connection.

For a self-hosted deployment, replace server_url with your superglue API WebSocket endpoint ending in /ws/tunnels.

To test a configuration without starting the gateway, run ./superglue-gateway check. It tests every target and the connection to superglue, prints the fix for each failure, and exits with a nonzero code when a test fails.

4. Start the gateway

./superglue-gateway -config /path/to/config.yaml

On Windows, run .\superglue-gateway.exe -config C:\path\to\config.yaml. If config.yaml is next to the executable, the -config argument is optional, and you can also start the gateway with a double-click. If the gateway cannot start, its window stays open and shows the reason. A successful startup logs Connected to server and then Registration sent, waiting for tunnel requests. The process reconnects automatically when its control connection drops.

Enable the script runner (optional)

Some integrations drive a local automation interface on the gateway host rather than a network target. To allow this, add one line to config.yaml:

enable_script_runner: true

When enabled, the gateway registers a built-in target named runner and accepts scripts sent from superglue over the tunnel (the script:// protocol, e.g. a system URL of script://runner/vbs32). No targets entry is needed for it. The runner is Windows-only and is reachable only through the tunnel, never from the host.

!

The script runner executes code sent from superglue on the gateway host, so it is off by default. Enable it only on a gateway you intend to use for a script-based integration.

Connect the private system

1. Open Systems and select Connect system.
2. Choose Private System.
3. Select the connected gateway and one of its registered targets.
4. Confirm the system name and URL.
5. Create the system, then let the system agent configure authentication for you.

The URL hostname must exactly match the target alias, and the URL scheme selects the protocol. For example, the finance-db target above could use postgres://finance-db:5432/accounting, and the internal-api target could use https://internal-api/reports. Enter requested secret values through the secure credential form rather than placing them in the gateway configuration or agent chat.

Run it reliably

The install command from superglue already runs the gateway as a service that starts with the machine and restarts after a failure. For a gateway you set up by hand, run it under your existing service manager, container platform, or workload orchestrator, and configure automatic restart. In both cases, give the gateway only the network access it needs:

• Outbound access to the configured superglue WebSocket endpoint (443 for hosted superglue).
• Access from the gateway host to the specific target hosts and ports.
• Read access to config.yaml, with the file restricted to the service account.
• No inbound public listener or broad access to the surrounding private network.

Troubleshooting

The gateway does not appear in superglue

Run ./superglue-gateway check, or open the setup page, and follow the message. An HTTP 401 means the API key is wrong, was deleted, or belongs to another organization or server. An HTTP 403 means the key needs full access or the API & CLI: Write permission. After a 401 or 403 the gateway retries less often, up to once a minute; restart it to connect at once. “No answer” means a firewall blocks outbound connections to the server. A message about the same tunnel ID means two gateways use one tunnel_id.

The gateway connects but the target call fails

Test the target from the gateway host, verify its firewall or security-group rules, and confirm that the system URL hostname matches the configured target alias. Run the gateway with -debug for connection details.

./superglue-gateway -config /path/to/config.yaml -debug

The connection drops repeatedly

Check the gateway logs and the network path to the superglue API. Proxies and firewalls must allow long-lived outbound WebSocket connections; the gateway automatically retries every five seconds after a disconnect.