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

1. Create an API key

Open API Keys from your organization menu, 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

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"

Each entry exposes one named destination through the gateway as a plain host:port address. The protocol is set later by the system URL in superglue, not by the gateway configuration. One gateway can register multiple targets, but it cannot reach destinations that are not explicitly listed. 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.

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. 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 Add 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

For persistent use, run the gateway under your existing service manager, container platform, or workload orchestrator. Configure automatic restart and give the process 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

Confirm that the process reports a successful connection and registration. Then check the API key, server_url, outbound WebSocket access (443 for hosted superglue), and that the key belongs to the expected organization.

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.