Skip to content

Connector security

This page is written for the people who have to approve the secure connector — IT, security, or whoever owns the network Monitor runs on. It describes exactly what the connector does, what it cannot do, and how to shut it off.

If you are setting the connector up rather than reviewing it, start at Integrations and your ERP.

The short version

A small container runs on your network next to Monitor. It dials out to Colleag and holds that connection open. Colleag sends read requests back down the same connection.

  • No inbound firewall rule. No port forwarding. No VPN. No public address on your side.
  • The tunnel reaches one host and one port — the Monitor instance you named. Not the subnet, not the machine it runs on.
  • Colleag only reads. Nothing is written back to your ERP.
  • You can revoke it from Colleag at any time, and the connection dies immediately.

What actually runs

A single container, published publicly so your team can inspect it before running anything:

ghcr.io/colleag-ai/erp-connector:stable

It runs chisel, an open-source TCP tunnel over HTTP. The command it executes is printed in its own startup log, and it is this:

chisel client --auth <connector-id>:<secret> --keepalive 25s \
  https://connector.colleag.ai R:<port>:<monitor-host>:<monitor-port>

R: is a reverse tunnel. It tells the hub "requests arriving on this port belong to that host and port on my side". The mapping is fixed at startup from the MONITOR_URL you set. The agent cannot be told to reach anything else without you changing that variable and restarting it.

Direction of travel

The connection is established from your network outwards, over TLS to connector.colleag.ai:443. Your firewall needs to allow that egress and nothing more.

Nothing listens on your network. If the agent is stopped, the tunnel closes and Colleag simply reports the connector as offline; there is no fallback path into your systems.

What leaves your network

The agent is a tunnel, not a synchronisation. There is no scheduled export, no mirror of your ERP, and no copy of your database on our side.

Data moves only when an agent in Colleag makes a specific read — a stock level, an order history, a supplier's invoices — in response to something a user asked. The reply to that query travels back and is used to answer the question. Colleag stores the conversation, so figures that appear in an answer are kept as part of that conversation, the same as anything else an agent writes.

The hub is not an open door

connector.colleag.ai terminates your tunnel, but it will not forward traffic into it for anyone who asks. The forwarding endpoints require an internal proxy key (X-Colleag-Proxy-Key) held only by the Colleag API. A request without it is rejected before it reaches your tunnel.

Each connector is also bound to its own assigned port, scoped to one organisation. One customer's tunnel is not reachable from another's.

Credentials

Two separate secrets are involved, and neither gives access to the other.

The connector token authenticates the agent to the hub. It has the form connector-id:secret and is what you paste into COLLEAG_TOKEN. It grants one thing: the right to open a tunnel for one connector on one port.

Your Monitor credentials are what Colleag uses to query the ERP itself. They are stored encrypted at rest (Fernet) and are never sent to the agent — the agent moves bytes and never sees them in the clear.

Use a dedicated Monitor user

Create a Monitor account for Colleag with read access only, rather than reusing a person's login. It keeps the audit trail in Monitor honest and means revoking access is a single action on your side as well as ours.

Revoking access

In Colleag, open Settings → Integrations, find the Secure connector row and choose Revoke. The token is invalidated immediately and the hub drops the tunnel; a running agent will keep retrying and keep failing until it is stopped.

Rotating instead of revoking issues a new token and invalidates the old one in the same step, so a compromised token can be replaced without a maintenance window.

Stopping the container on your side has the same practical effect from your network's point of view, and needs no action in Colleag.

If the machine running the agent were compromised

Worth stating plainly, because it is the question that decides most reviews.

An attacker with the container and its token could open a tunnel to the same Monitor host and port the agent was already configured for — nothing else on your network. They could not reach other hosts, other ports, or other customers' tunnels, and they could not use the token to sign in to Colleag or read anything stored there.

They would still need valid Monitor credentials to get data out of the ERP, and those live encrypted on our side rather than on the machine.

Revoking the token in Colleag closes that path immediately.

Where to run it

Any machine or VM on a network segment that can reach Monitor and make outbound HTTPS calls. It is a small, long-running process; a container host you already operate is the usual choice.

It reconnects on its own after a network drop or a restart — chisel keeps the connection alive with a 25-second keepalive and retries when it fails. After a reboot of the host, start the container again and the tunnel re-establishes without any action in Colleag.

The status badge in Settings → Integrations shows online with a last-seen timestamp, which is the quickest way to confirm it is healthy.

Next: Settings & Admin →