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.

flowchart LR
    M[("Monitor")] ---|"your network"| C["Connector<br/>next to Monitor"]
    C -->|"outbound HTTPS, port 443"| H["connector.colleag.ai"]
    H --- A["Colleag"]

• 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 reads one Monitor company — the company number you entered. Give its Monitor user access to that company only and Monitor enforces the boundary itself. See Limiting what Colleag sees.
• 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 and no copy of your ERP database on our side.

Data moves 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 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.

	What	Where it stays
Kept	A search mirror of the article register — number, description, unit, lifecycle status, type — and the article number each product is linked to	In Colleag's database. Re-synced at any time, emptied when the integration is disconnected
Read when asked	Stock, prices, orders, invoices and everything else an agent looks up	Only in the conversation, or in a document someone asked for
Never	Writes to Monitor, scheduled exports, a copy of the ERP database	—

The one copy we do keep

Product search needs to find an article by name without calling your ERP on every keystroke, so Colleag keeps a search mirror of your article register: article number, description, unit, lifecycle status and type. Nothing else — no prices, no stock levels, no orders, no customers and no suppliers.

It is filled when someone asks for it or when the picker fills it on first search, it can be re-synced at any time because every row came from your ERP, and it is emptied when the integration is disconnected.

One more thing is stored per product: the article number a product workspace is linked to, which is what lets the ERP structure be fetched for it.

Everything else an agent reads from Monitor is used to answer and then kept only inside the conversation or inside a document someone asked it to write.

Where else your ERP figures can travel

• Into documents. A report an agent writes — a supplier assessment, a monthly report — is stored, versioned and searchable like any other document, with its figures in it.
• Into the search index. Document text is chunked and embedded so it can be searched by meaning. The embeddings are computed by an embedding model — Azure OpenAI within the EU in SaaS — so figures written into a document travel there the same way the document's words do. See The search index.
• Into operational logs. The API logs which entity it queried and with what filter, which can include an article number or a date range. Logs are kept for 30 days and are not part of the product's own search.
• Into backups. The database is backed up automatically, with 35 days of history in production.

Limiting what Colleag sees with Monitor companies

Monitor divides its data into companies, each with its own company number such as 001.1. Colleag is connected to one company at a time: the login and every read go to the company number entered under Settings → Integrations, and the article search mirror is filled from that company only.

That makes the company the simplest boundary you have. Keep the boundary on your side as well: give Colleag's Monitor user access to the chosen company only. Monitor then enforces the limit itself, whatever is configured in Colleag. If civil and defence work sit in different companies, Colleag can be connected to the civil one without the other ever becoming visible.

flowchart LR
    U["Colleag's Monitor user"] -->|"reads"| B
    U -. "no access" .- A
    subgraph S["Monitor server — example"]
        A["001.1 Defence products"]
        B["002.1 Civil products"]
        T["900.1 Test company"]
    end

Your Monitor	What to do
Civil and protected work in separate companies	Connect Colleag to the civil company and give the Monitor user access there only.
A test company	A test company is usually a copy of production, and a copy is as sensitive as the original. Clean out sensitive articles, customers and orders first, or set up a pilot company that holds only the pilot product's articles and structures.
Everything in one company	The company cannot limit anything: within a company, Colleag can read the whole article register. Start with a cleaned test or pilot company, or choose an on-premises installation, where nothing leaves your network.

To move to another company later, for example once the security review is done, change the company number in Colleag, give the Monitor user access to the new company, and re-sync the article mirror.

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.

LinuxWindows

The straightforward case. Docker or Podman, the docker run command from the setup panel, and a restart policy so it comes back after a reboot. Nothing else is required.

The agent works on Windows, with one thing to know: it is a Linux container — Alpine with a small tunnel binary — so Docker has to be running in Linux-containers mode. That is Docker Desktop's default, backed by WSL 2. If Docker is switched to Windows containers the image will not start, and the error mentions the operating system rather than anything about Colleag.

Two practical notes:

Use the PowerShell command, not the bash one. The setup panel shows both. PowerShell does not treat \ as a line continuation, so pasting the Linux block produces invalid reference format. The PowerShell block uses a backtick instead.

Think about who is logged in. On Windows 10 and 11, Docker Desktop runs inside a user session — it starts when someone signs in, and a server that reboots unattended comes back with no agent running until somebody logs on. --restart unless-stopped restarts the container, but only once Docker itself is up. If the connector needs to survive reboots on its own, use one of these instead:

• Windows Server with the WSL 2 backend, where Docker runs as a service.
• A small Linux VM on the same network — often the least surprising option.
• A machine that is already a container host in your environment.

None of that changes what the agent does or what it can reach. It is the same image and the same outbound tunnel either way.

Next: Settings & Admin →