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.

A connection that uses the gateway behaves like any other connection: 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. A connection selects the gateway, and its URL hostname names one of the gateway’s targets.
4. When an agent or tool uses that connection, superglue opens a tunnel to the 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. Ask the superglue agent to connect the private system, for example “Connect the Sage 100 database on the client’s office server.”
2. The agent shows the gateway setup in the chat with its suggestions filled in. Confirm the gateway name and the targets. For QuickBooks Desktop, Sage 100, or Sage 300 CRE on Windows, also allow the script runner. Then select Create install command.
3. Select the tab for the machine and follow its steps:
   • Web (Windows): on the machine, download superglue-gateway.exe from the link and open it. The gateway opens a page in the browser. Paste the code from the chat and select Connect. Windows asks once for administrator rights.
   • Windows: copy the command and run it in PowerShell. When PowerShell does not run as administrator, the command asks Windows for administrator rights and continues in a new window.
   • Linux: copy the command and run it in a terminal. The command needs curl or wget, and uses sudo when you are not root.
4. Keep the chat open. The setup shows Connected when the gateway connects, and whether the gateway reaches each target. The agent then continues and creates the connection.

With the Web tab, the gateway page asks only for the code. After Connect, it checks the code, the connection to superglue, and the targets, then installs the gateway as a Windows service.

With a command, keep the PowerShell window or terminal open until the command finishes; the service then runs without it. If the command stopped or the window closed before the gateway connected, run the same command again.

Every tab installs the gateway 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. The code and the commands contain an API key named Gateway: <name> with the API & CLI: Write permission, which acts with the permissions of the person who created it. The code and the commands are shown only once. To disconnect the gateway, open a connection that uses it on the Connections page and select Remove gateway. This disconnects it and deletes the API keys you select (its Gateway: <name> keys are selected), and can also delete the connections 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 setup 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 install it again 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 code and the install commands contain a secret. Use them only on the target machine, and do not paste them 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 code that superglue shows in the gateway setup (the install token, sgi1.…) and select Connect. On Windows, the page asks Windows for administrator rights once and installs the gateway as a service that starts with the machine. On Linux, the page runs the gateway while the program runs; for a service, use the install command. Advanced setup at the bottom of the page holds the manual configuration: API key, server, tunnel ID, targets and script runner. It checks that each target is reachable from the gateway host and shows the system URL to use in superglue. The page is reachable only from the gateway host, through the link the gateway opens or prints.

The page and a gateway saved there run only while the gateway program runs, so keep its window or terminal open. To run the gateway without a window, use the install command from superglue. If the program stops, the page shows how to start it again. The new page fills in the values that you did not save yet, except the API key.

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 a connection selects it 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 connection URL later. The protocol is also set later by the connection 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 connection 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

Ask the agent to connect the system. It reads the connected gateways and their targets, then creates a connection that uses the gateway and sets its URL. To move an existing connection to a gateway, open it on the Connections page, select the gateway under Secure Gateway, and update the URL.

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 in the secure connection 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 connection 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.