WireGuard: firewall connection
The firewall connection is the route for firewalls with WireGuard support: 9brains builds an encrypted WireGuard tunnel to your firewall. What the On-Premises Connector does and how the two connection routes differ is described in the overview.
Requirements
Section titled “Requirements”- You are an administrator in the workspace or hold the right “Manage the on-premises connector”
- Your workspace has a Business or Max license
- Your firewall supports WireGuard (pfSense, OPNsense, Sophos, Fortinet, Unifi, MikroTik or similar)
- A UDP port on the firewall is reachable from the outside (default: 51820)
No WireGuard on the firewall? Use the connector software in your network instead. For that you need neither WireGuard nor an open port.
How it works
Section titled “How it works”Your company network 9brains Cloud┌──────────────────────┐ ┌──────────────────────┐│ │ WireGuard tunnel │ ││ Database ───────────│═══════════════════►│── Integration/Skill ││ ERP system ─────────│═══════════════════►│── Code execution ││ File server ────────│═══════════════════►│── Data indexing ││ │ (encrypted) │ │└──────────────────────┘ └──────────────────────┘- You configure a WireGuard tunnel between your firewall and 9brains
- You set up services, each service points to an internal system (e.g. database on port 5432)
- You set up an integration or a skill that uses the service
- The AI can address the system through the encrypted tunnel
Important: The connection is outbound only, 9brains connects to your systems. Your network cannot initiate connections to us.
Create a tunnel
Section titled “Create a tunnel”- Go to Settings → On-Premises Connector
- Click “Create tunnel”
- Fill in the fields:
| Field | Description |
|---|---|
| Name | A meaningful name (e.g. “Main site Munich”) |
| Endpoint | The public address of your firewall with the WireGuard port (e.g. vpn.mycompany.com:51820) |
| Customer firewall public key | The WireGuard public key of your firewall, found in the WireGuard configuration of your firewall |
| Source Peer IP | A free address in your firewall’s tunnel network that 9brains appears under there (e.g. 10.0.0.2) |
- Click “Create tunnel”
- A public key is displayed, you need to enter this as a peer in your firewall
Configure the firewall
Section titled “Configure the firewall”Add a new peer in the WireGuard configuration of your firewall:
| Field | Value |
|---|---|
| Public Key | The displayed public key from 9brains (copy button) |
| Allowed IPs | The Source Peer IP from 9brains with /32 (e.g. 10.0.0.2/32) |
| Endpoint | Not required, 9brains initiates the connection |
Note: The exact configuration varies depending on the firewall vendor. Check your firewall’s documentation for the WireGuard peer configuration.
Add services
Section titled “Add services”A service describes a specific system that is reachable through the tunnel.
- Open the tunnel in the detail view
- Click “Add service”
- Fill in the fields:
| Field | Description |
|---|---|
| Name | Display name (e.g. “ERP database”) |
| Protocol | Type of service (PostgreSQL, HTTP, SMB, LDAP etc.) |
| Remote host | The internal IP or the hostname of the target system (e.g. 192.168.10.5) |
| Remote port | The port of the target system, filled with the standard one once you pick a protocol |
| Description | What does this system contain? The AI sees this information in the chat |
- Click “Add service”
- The service then appears in the tunnel’s list. In integrations and data sources you pick it by name, 9brains sets address and port itself (see Use the service in an integration, skill or data source)
Tip: Write a meaningful description. The AI uses this information to decide which system is relevant for a question. For example: “Contains revenue, customer and article data since 2019.”
Test the connection
Section titled “Test the connection”- In the tunnel detail view, click “Test connection”
- For each service it shows:
- Reachable: Connection successful, latency in milliseconds
- Not reachable: Connection failed, with the reason in plain words and the system’s own message below it; use “Copy details” to paste both, including the error ID, into a support request
If a service is not reachable, check:
- Is the WireGuard tunnel active on your firewall?
- Is the target system switched on and reachable?
- Are the Allowed IPs correctly configured on the firewall?
- Does the firewall allow traffic from the WireGuard interface to the target system?
Security
Section titled “Security”- Encryption: All data is transmitted encrypted through the WireGuard tunnel using state-of-the-art cryptography
- Outbound only: The connection can only be initiated by 9brains, your network is not reachable from the outside
Tenant isolation and minimal permissions apply to both connection routes, they are described in the overview.
Common problems
Section titled “Common problems”Tunnel shows “Error” instead of “Connected”
Section titled “Tunnel shows “Error” instead of “Connected””9brains names the reason on the tunnel and in the overview, for example when the firewall does not answer the WireGuard handshake. Usually it is one of these:
- Firewall peer not configured: Enter the displayed public key as a peer in your firewall
- UDP port not reachable: Make sure that the WireGuard port (e.g. 51820) is reachable from the outside
- Wrong public key: Compare the “Customer firewall public key” in 9brains with the actual public key of your firewall
Service not reachable despite active tunnel
Section titled “Service not reachable despite active tunnel”- Firewall rules: Check whether traffic from the WireGuard interface to the internal system is allowed
- Allowed IPs: The tunnel IP from 9brains must be in the Allowed IPs of the peer on your firewall
- Access list in front of it: If a server in front of the service (e.g. an nginx) or the target system itself only admits certain source addresses, our address has to be allowed there. You find it on the tunnel under Source address for firewall rules
- Target system: The system must be switched on and listening on the specified port. If a service does not answer twice in a row, 9brains refuses connections to it until it answers again; the service then says so
Feature not visible
Section titled “Feature not visible”The license and rights you need for the On-Premises Connector are described in the overview.