Connector software in your network

The connector software is the second way to connect your company network to 9brains. Instead of configuring the connection on your firewall, a small piece of software runs on a device in your network and builds the connection to 9brains on its own. This means it does not matter whether your firewall supports WireGuard, and you do not have to open any port.

For firewalls with WireGuard support, the firewall connection is usually the simpler choice. Both routes lead to the same result: internal services become reachable for the AI through an encrypted, outbound-only connection.

When this route fits

• Your firewall does not support WireGuard (e.g. older Sophos UTM devices). The firewall stays completely untouched.
• You only want to make a single machine reachable, for example a Mac or PC running a line-of-business application.
• You want to get started quickly, without coordinating changes on the firewall.

Requirements

• You are an administrator in the workspace
• Your workspace has a Business or Max license
• A device in the network that stays switched on (computer, server, NAS or a VM) and can reach the internet
• No open port required, the connection only goes outbound

What the firewall must allow outbound

Outbound, the connector needs exactly three destinations, all over the normal HTTPS port 443:

Destination	Purpose
connect.9brains.de	Signing the connector in
relay1.9brains.de	Data connection when no direct path is available
relay2.9brains.de	Fallback if the first one cannot be reached

UDP port 3478 to the same two relay addresses helps as well. Everything still works without it, but transfers get slower because they always take the detour via 9brains instead of running directly.

In many corporate networks outbound HTTPS is open anyway, in which case there is nothing to do. If your firewall restricts outbound connections, allow these three addresses.

You do not need to allow tailscale.com. Many security teams block those addresses on purpose because they are abused for unapproved VPN tunnels. You can keep that block during operation, the 9brains connector works without it. Only during setup does the installation download the software once: on Linux from tailscale.com and pkgs.tailscale.com, on Windows from tailscale.com, and on a Synology NAS in the update step from pkgs.tailscale.com. The Docker variant pulls its image from Docker Hub. If these addresses are blocked, allow them briefly for the setup, or download the software on another computer and install it from there, on a Synology NAS in the Package Center via “Manual Install”.

How it works

Your company network                         9brains Cloud
┌──────────────────────┐                    ┌──────────────────────┐
│  ┌────────────────┐  │     encrypted      │                      │
│  │ Connector      │  │     connection     │── Integration/Skill  │
│  │ software       │──│═══════════════════►│── Code execution     │
│  └───────┬────────┘  │   (outbound only)  │── Data indexing      │
│  Database, ERP,      │                    │                      │
│  line-of-business... │                    │                      │
└──────────────────────┘                    └──────────────────────┘

The connector software registers with 9brains on its own. Through it, 9brains reaches exactly the services you release, and nothing else. Your network, in turn, cannot establish a connection to us.

Two variants

When creating the connection you choose under “What should be reachable?” between:

• “Only this machine”: The software runs directly on the target machine, that is, on the computer where the desired service lives. This is the most common case and works regardless of whether the machine has a fixed or a changing (DHCP) IP.
• “Routing into the network”: The software runs on one device and makes several systems behind it reachable (an entire subnet). Suitable when you want to connect, for example, a database, ERP and file server through a single device.

Create a connector

1. Go to Settings → On-Premises Connector
2. Click “Create tunnel”
3. Under Connection type, choose “Connector software in your network”
4. Give it a name (e.g. “CAD machine engineering”)
5. Under “What should be reachable?” choose the appropriate variant

Variant “Only this machine”

After saving, 9brains walks you through the setup. Pick the operating system of the target machine at the top, and the steps you need appear one after another, each with its own copy button. Work through them on the target machine in order. You can choose between macOS, Windows, Linux and Synology NAS. On a Synology NAS, Tailscale comes from the DSM Package Center, and you run the connection command via SSH with an administrator account.

The last step contains your personal access key, so do not pass it on. If you would rather take everything at once, “Save as file” gives you the steps as a script.

As soon as the last command has finished, the connector signs in to 9brains. It appears as connected in the overview once you have added a service and checked it once via “Test connection”. After that, 9brains checks the connection regularly on its own.

Is Tailscale already running on the machine? Then append --force-reauth to the command. This switches the machine into the 9brains network.

Variant “Routing into the network”

1. Enter the network range (subnet) the connector should make reachable, e.g. 192.168.1.0/24. For a single machine, enter its IP as /32, e.g. 192.168.1.50/32.
2. Save the docker-compose.yml shown to you on a device in the network that runs Docker (VM, server or NAS). You can copy the contents or use “Save as file”. The file contains your access key, so do not pass it on.
3. Run docker compose up -d in the same folder.

As soon as the connector is running, the connection appears in the overview.

Add services

A service describes a specific system (a port) that should be reachable through the connector.

1. Open the connection in the detail view
2. Click “Add service”
3. Pick the protocol type; the port is then pre-filled with the protocol’s standard port (e.g. 445 for SMB). If your service uses a different one, just overwrite it. Then enter:
   • “Only this machine”: The port of the service is enough (e.g. 5432 for PostgreSQL). The target is the machine itself on which the connector runs.
   • “Routing into the network”: Additionally the remote host, that is the internal IP within the specified subnet (e.g. 192.168.1.50).
4. After saving, the service appears in the connection’s list. In the Microsoft SQL Server, PostgreSQL, Oracle Database and E-mail (IMAP/SMTP) integrations, in integrations with a server address such as DATEV, FileMaker, Odoo or Umami, in skills of your own and in data sources you pick it directly (see below).

Using the service in an integration

For the Microsoft SQL Server, PostgreSQL, Oracle Database and E-mail (IMAP/SMTP) integrations and for integrations with a server address such as DATEV, FileMaker, Odoo or Umami, 9brains first asks how the target is reachable:

• Publicly reachable: For servers that can be reached directly from the internet. You enter address and port yourself, as before.
• Through the on-premises connector: You pick one of the services created here. The address and port fields disappear, because both come from the service. Of a server address like the one of DATEV you only enter the path on the server (/datev/api/dms/v2), including a subfolder that Matomo or Magento, for example, is installed in; host and port come from the service. For FileMaker, Odoo and Umami the service is the whole address, so you enter none there. Next to every service you can see whether the connector currently reaches it.

If there is no matching service yet, a note with a link back to this page appears instead. Create the service first, then return to the integration.

Two things that help:

• The list only shows services with the matching protocol. For the SQL server the service must be set to MSSQL, for a mailbox to IMAP, for sending to SMTP, otherwise it never appears even though it exists.
• E-mail (IMAP/SMTP) needs two services: one with IMAP for incoming mail and one with SMTP (usually port 587) for sending. Select them under Service for incoming mail and Service for sending. Without a service for sending, the SMTP server entered in the integration is used; if that field stays empty, 9brains saves replies as drafts in the mailbox.
• Admins and the integration’s owner make the selection, during setup or later on the integration’s General tab. Every other account then confirms the new address once: a personal account its owner, a company account an admin or the integration’s owner. Your own account with a key or password counts as confirmed with the switch; with an OAuth sign-in, you sign in again once. Creating services stays reserved for administrators.

For a skill of your own you pick the service on the skill’s Settings tab, above the host; all that is left to enter there is the path on the server. When the AI builds a connection to a system in the company network in the chat, it takes the service itself. Nobody types an address of the connector by hand any more. Integrations that only run at their provider, such as Jira, Confluence, DocuWare Cloud or Shopify, do not offer the connector.

For how to turn a service into a usable AI feature (PostgreSQL integration, ERP skill and more), see the Set up an integration or skill section of the overview.

Security

• Encryption: The connection is fully encrypted using modern cryptography
• Outbound only: The software builds the connection outward, your network is not reachable from the outside and no port needs to be opened
• Tenant isolation: Every workspace has its own connection. Other workspaces cannot access your systems
• Minimal permissions: 9brains only reaches the services you release, no access to other devices in your network
• Setup command valid for one week: Anyone holding the command can sign a device in with it, so it is only valid for 7 days. A connector that is set up keeps running after that; for a new setup, 9brains shows a fresh command automatically
• One device per connector: If another device signs in with the same command, the connector keeps using its current one. It only switches once you take over the new device (see Another device is waiting for confirmation)

Common problems

The setup command “hangs”

Tailscale is probably already running on the target machine (e.g. from a previous use). Append --force-reauth to the command, then the machine switches into the 9brains network.

Another device is waiting for confirmation

A second device signed in with this connector’s setup command, for example because you set up the connector software on a new machine or ran the command on the wrong machine by mistake. The connector keeps using its current device.

• You moved the connector on purpose: Open the connector and click “Take over device” under “Another device signed in”. All services then run through the new device.
• The command ran on the wrong machine: Don’t take the device over. Run the right connector’s command there.
• You don’t recognise the device: Don’t take it over and contact support.

Service not reachable although the connection is “connected”

• Service only listens locally: Some programs are reachable only via localhost (127.0.0.1) out of the box. For the connector to reach them, the service must listen on all network addresses (often 0.0.0.0 in the program’s configuration).
• Local firewall: A firewall on the target machine itself (e.g. the Windows firewall) can block the port. Release the port there. A Synology NAS running DSM 7 needs no rule, because the connection arrives there from the NAS’s own address. On DSM 6 you add it under Control Panel → Security → Firewall: the service’s port, source IP 100.64.0.0, subnet mask 255.192.0.0.
• Access list in front of it: If a server sits in front of the service (e.g. an nginx), or a firewall only admits certain source addresses, the right address has to be allowed there. Which one that is appears on the connector under Source address for firewall rules, and it depends on the variant: with “Only this machine” it is our address, with “Routing into the network” it is the local network address of the machine the connector runs on. The rule belongs on the target machine itself or in the service’s access list, not on your firewall at the network edge: our traffic never arrives there as a connection of its own.
• Wrong port or host: Check the port and, for “Routing into the network”, the internal IP.

The connector does not connect although the machine is online

If the connector is gone for more than a few minutes, the tunnel and the overview show since when it has been offline. Check whether your firewall restricts outbound connections. The connector needs the three addresses from What the firewall must allow outbound. The quickest place to see this is your firewall log: blocked connections to connect.9brains.de or relay1.9brains.de show up there.

The connection does not appear in the overview

• The machine or device running the connector must be switched on and have internet access.
• For the Docker variant: check with docker compose logs whether the connector has started. If 9brains reports on the tunnel that the network is not approved, the network range in docker-compose.yml does not match the one you entered when creating it.

Changing IP address (DHCP)

With “Only this machine” you do not need to worry about this: the connector keeps a stable address even if the machine receives a new local IP via DHCP. With “Routing into the network” you reach the target systems via their internal IP, so it is best to assign fixed IPs or DHCP reservations there.

Feature not visible

• The On-Premises Connector is available from a Business license upwards.
• Only administrators can configure connections and services.