Peaky Connector (On-premise Systems)

Some systems run on your own servers, behind a firewall that lets nothing in from the internet. A Peaky Connector lets Peaky reach them without opening your firewall or whitelisting any address. You run it on a machine in your own network; it connects out to Peaky and passes on only the requests its configuration allows.

Peaky's sync works the same as for any other integration. The connector only carries its requests the last step, from the edge of your network to your system. It holds no credentials of its own and keeps no copy of your data.

This page covers what is the same however you run the connector. How to install and run it is on Run on Docker, Run on Linux, Run on Windows and Run on Kubernetes, and each integration that can go through one has its own page: the target to add to the connector's configuration, and how to connect the integration through it.


Supported Integrations

Integration

What to set up

Odoo

An Odoo on your own network, reached with the odoo-readonly profile, which lets Peaky read and nothing else

Dynamics NAV

A Dynamics NAV (or Business Central on-premises) on your own network, reached with the nav-readonly profile, which lets Peaky read its OData web services and nothing else

SAP Business One

A SAP Business One Service Layer on your own network, signed in with a username and password and reached with the sap-b1-readonly profile, which lets Peaky sign in and read and nothing else

If you run another system on your own servers, contact support.


How It Works

 Your network                                    |  Peaky
                                                 |
 Your system  <-- your network --  Peaky Connector  ==== HTTPS, outbound on port 443 ====>  Peaky
                            (on a machine you run)
  • The connector opens one connection to Peaky, on port 443, and keeps it open. Nothing connects to your network from outside.

  • Every system the connector may reach is a target you name in its configuration file. Peaky only ever knows the target's name, never its address, so it cannot reach anything you have not listed.

  • For each target you decide what is allowed. A profile brings ready-made rules for a kind of system — for Odoo, odoo-readonly lets Peaky read and nothing else.

  • The connector writes every request to an audit log on your machine.


Before You Start

You need:

  • Somewhere in your network to run the connector that can reach your system: a Linux machine — a small virtual machine is enough — with Docker or without it, a Windows Server, or a Kubernetes cluster.

  • Outbound HTTPS from there to connect.eu.peaky.ai on port 443. If your network sends outgoing traffic through a proxy, the connector uses it (see Proxies and certificates).

  • The Create right on integrations in Peaky. See Team & Roles.


Add a Connector

  1. On the Integrations page, open the Connectors tab and click Add connector.

  2. Give it a Name you will recognise, such as the machine it runs on, and click Add.

  3. Peaky shows Install … with two things to copy: a configuration file, and the commands to start the connector the way you choose — Docker, Docker Compose, Linux service, Windows service, Kubernetes or Helm (see Run it). The commands hold a one-time install token. It works once, for 24 hours, and Peaky does not show it again — if you lose it, ask for a new one with New install token (see Manage connectors).

The new connector is listed as Not installed until it has been started with the token.


Run It

It is the same connector however you run it; only how it is started differs.

Way

Use it when

How

Docker

You have a machine with Docker and want the fewest steps. One command

Run on Docker

Docker Compose

You keep your machine's services in Compose files, or want the settings in a file rather than a command

Run on Docker

Linux service

You have a Linux machine without Docker, or prefer not to run containers. The connector runs as a system service

Run on Linux

Windows service

You have a Windows Server, without Docker. The connector runs as a Windows service, installed with a Windows installer that is not code-signed yet

Run on Windows

Helm

You run Kubernetes. The recommended way there

Run on Kubernetes

Kubernetes

You run Kubernetes and apply plain YAML yourself, with kubectl, kustomize or a GitOps tool

Run on Kubernetes

Whichever you choose:

  • Keep its storage. On its first start the connector creates its own key, registers it with Peaky using the token, and keeps it in its storage — a Docker volume, a folder on the Linux machine or Windows Server, or a volume in Kubernetes. If that storage is lost, the connector cannot start again and you have to Reinstall it in Peaky.

  • Run one copy. Two copies of the same connector keep taking the connection to Peaky from each other. For a second machine, add a second connector.

  • The token works once. After the first start it is useless, and you can delete it.

Within a minute of starting, the connector shows as Connected on the Connectors tab, with the machine's name, its version and the targets it reported.


The Configuration File

The configuration Peaky shows you starts with peaky_url, where the connector connects to Peaky: keep it as Peaky gives it to you. Each [[target]] below it is one system Peaky may reach. Take the target from your integration's page (see Supported integrations) and put in your own system's address. For an Odoo, for example:

peaky_url = "https://connect.eu.peaky.ai"

[[target]]
name = "odoo"
url = "https://odoo.mycompany.internal:8069"
profile = "odoo-readonly"

Setting

What it does

name

The name Peaky uses for the target, such as odoo. Lowercase letters, digits and dashes

url

The system's address as the connector's machine reaches it, such as https://odoo.mycompany.internal:8069

profile

A ready-made set of rules for a kind of system, such as odoo-readonly. Your integration's page says which one to use

ca_file

Optional. A certificate file to trust for this target, when your system uses a certificate from your own certificate authority

timeout_seconds

Optional. How long the connector waits for the system to answer. Default 300

use_proxy

Optional. Set to true to reach this target through your proxy as well. Off by default

Nothing is allowed unless the configuration allows it. After changing the file, restart the connector to load it — see Run on Docker, Run on Linux, Run on Windows or Run on Kubernetes.

A profile is built into the connector and checked on your machine: Peaky cannot change or loosen it. It reads each request before passing it on and refuses any the profile does not allow, whatever rights the account Peaky signs in with has.


Connect an Integration Through It

Once the connector shows as Connected, connect the integration on the Integrations page and choose to reach it through your connector, with the Target you named. The steps for each integration are on its page — see Supported integrations.

The integration's own credentials, such as an API key, are stored in Peaky like any other integration's, not on the connector.


Connector Status

The Connectors tab lists your connectors with their status:

Status

What it means

Connected

The connector is running and connected to Peaky

Not connected

It was installed, but Peaky has not heard from it for a while: it is stopped, or its machine or network is down

Not installed

It has not been started with its install token yet

Under each connector are its Targets, as it reported them the last time it connected. A connector that is Not connected also says when it disconnected and why, for example Disconnected 2 hours ago: the connection broke — its Activity has the whole story.

Everyone who can see the Integrations page sees this tab and each connector's activity. Adding, renaming, reinstalling and removing a connector need the rights listed under Manage Connectors.

When a connector cannot do its work, the integrations that go through it show Sync failing with a Check connector button that opens this tab — see Fixing a Connection.


Activity

Choose Activity in a connector's more menu (...) to see what happened to it, newest first: when it connected and disconnected and why, when Peaky turned it away, every sync that went through it, and what people changed. It answers questions like why didn't last night's sync run? or does our connector keep dropping? without logging in to the machine it runs on. Hover over a time to see the exact date and time.

Event

What it means

Added by …

Someone added the connector in Peaky

New install token, by …

Someone asked for a new install token for a connector that is not installed yet

Installed

The connector was started with its install token, with the version and the machine it reported

Connected

The connector connected to Peaky, with its version, machine and targets. When one of these changed since the last time — after an upgrade, a move or a change to the configuration — the line says from what to what

Disconnected

The connection ended, and why (below)

Turned away

The connector tried to connect, and Peaky refused it (below)

Integration sync completed or failed

A sync went through the connector (below)

Reinstall started by …

Someone chose Reinstall: the installation that ran is cut off and turned away from then on

Renamed by …

Someone renamed the connector, from what to what

Removed by …

Someone removed the connector

Why a connection ended:

Reason

What happened

What to do

Closed by the connector

The connector was stopped or restarted, or its machine shut down

Nothing, if someone did it on purpose. Otherwise, check why the container or its machine stopped

The connection broke

The connection was cut without being closed: a network problem, or a firewall or proxy ending it

Check the machine's network and outbound HTTPS. The connector reconnects by itself

Replaced by a newer connection

The same connector connected again and the new connection took over: it reconnected before Peaky saw the old connection drop, or a second copy runs with the same volume

Nothing, if it happens now and then. If it keeps happening, make sure only one copy runs: two copies take over from each other in turn

Removed in Peaky

Someone removed the connector

Stop it on its machine

Reinstalled

Someone started a reinstall

Start the connector with the new token

Peaky restarted

Peaky restarted its side, as it does for an update

Nothing: the connector reconnects within seconds

Lost

Peaky stopped hearing from the connector and nothing closed the connection. The line shows when it was last seen

As for a broken connection. If it does not come back, check that the machine is up

When the connector reconnects again and again within minutes, the activity folds those into one line, such as Reconnected 14 times, with the time span. Choose Show all to see each one. It points at an unstable network, or a machine or container that keeps restarting.

Why Peaky turned a connector away:

Reason

What to do

It was removed in Peaky, but is still running

Stop and remove it where it runs

It is not installed: an installation retired by a reinstall is still running

Stop the old copy, where it ran before

Its signature does not match its key

Reinstall it

Its signature is too old or too new

Set the machine's clock, or turn on time synchronisation

A connector that keeps trying is listed about once an hour, with how many times it was turned away.

Syncs through the connector

Each sync that goes through the connector adds one line, when it ends, rather than one per request: whether it completed or failed, how many requests it sent through the connector, how many the connector refused (its configuration or the target's profile did not allow them), how many did not reach your system, and how many were not sent because the connector was not connected. Open the sync log opens that integration's own Logs.

A sync with refused calls lists the first few, with the method and path and, for Odoo, the model and method that were asked for — for example POST /xmlrpc/2/object · res.partner · write — and each call's request id. Copy the id with the button next to it, and find the same id in the connector's audit log, which has the reason it was refused.

What Peaky keeps

The activity holds names and counts only: never the content of a request or an answer, your data, credentials, or your systems' addresses. Peaky keeps the last 90 days.


Manage Connectors

From a connector's more menu (...):

  • Rename — change its name. Needs the integration Update right.

  • New install token — for a connector that is still Not installed, when the first token expired or was lost. Needs the integration Create right, like Reinstall.

  • Reinstall — to move a connector to another machine, or start over. Peaky asks you to confirm, then shows a new install command. The installation that runs now is cut off straight away, so the integrations that go through it stop syncing until you start the connector again with the new token. Then remove the old installation and its storage, and install it again with the new token — see Run on Docker, Run on Linux, Run on Windows or Run on Kubernetes.

  • Remove — Peaky refuses the connector from then on, and the integrations that go through it stop syncing. Needs the integration Delete right.

  • Activity — what happened to the connector — see Activity. Anyone who can see the Integrations page can open it.

Each of these, and who did it, shows in the connector's activity.


The Audit Log

The connector records every request Peaky made — allowed or refused — one line each, in audit.jsonl in its storage. Each line has the time, the target, the request, what a profile read from it (for Odoo, the model and method that were asked for), whether it was allowed or denied and why, the answer's size and how long it took. The same lines appear in the connector's own log, which Run on Docker, Run on Linux, Run on Windows and Run on Kubernetes show how to read.

The log stays on your machine; Peaky does not collect it. To keep it elsewhere, set audit_log at the top of the configuration file to another path.

Each line has a request_id, the same one Peaky shows for a refused call in the connector's Activity: search the log for it to see that request, and why it was refused.


Security

  • Nothing inbound. The connector only makes an outgoing HTTPS connection to Peaky. You open no ports and whitelist no addresses.

  • Its own key. The connector creates a key on your machine when it is installed and proves who it is with it every time it connects. The key never leaves the machine. Removing the connector in Peaky refuses it from then on.

  • Only what you list. Peaky reaches targets by name only, and only the requests their profile allows.

  • Only your company. A connector serves the company it was added to, and no other.

  • No credentials, no data. The connector stores no passwords or API keys and keeps no copy of what passes through it.


Proxies and Certificates

If outgoing traffic has to go through a proxy, give the connector the proxy's address. A proxy that needs a username and password takes them in the address (http://user:password@proxy…). Addresses you list as exceptions are reached directly.

If your proxy inspects HTTPS traffic with its own certificate, give the connector that certificate to trust as well.

Where to set both depends on how you run the connector — see Run on Docker, Run on Linux, Run on Windows or Run on Kubernetes.

Requests to your own systems do not go through the proxy, unless a target sets use_proxy = true.


Troubleshooting

Start with the connector's status and Activity in Peaky. For what to check where the connector runs — its log, peaky-connector check, restarting it — see Troubleshooting on Run on Docker, Run on Linux, Run on Windows or Run on Kubernetes.

Symptom

Likely cause

What to do

The connector stays Not installed

It was not started, or it cannot reach Peaky

Check the connector's log, and that it can open https://connect.eu.peaky.ai

The log says the token is unknown, already used or expired

The token worked once already, or is more than 24 hours old

Use New install token (or Reinstall) and start the connector with the new command

The log says Peaky refused this connector

It was removed or reinstalled in Peaky

Use Reinstall to get a new command, or remove the old installation

The log says the signature's time is too far off

The machine's clock is wrong

Set the clock, or turn on time synchronisation, and restart the connector

The connector is Not connected

It is stopped, or its machine or network is down

Open its Activity to see when and why it disconnected. Start it again and check its outbound HTTPS

The connector keeps disconnecting

An unstable network, two copies of the connector, or a container or service that keeps restarting

Its Activity shows Reconnected … times, or Replaced by a newer connection when two copies run

A sync through the connector failed, or skipped data

The connector refused some of its calls, or could not reach your system

Its Activity lists the sync, with the refused calls and their request ids to look up in the audit log

Connecting an integration says The connector is not connected to Peaky

Same as above

Start the connector, wait until it shows Connected, then try again

Connecting an integration says The connector refused the request

The configuration has no target of that name, or the target lacks the profile the integration needs

Check the target's name and profile, restart the connector, and use the same name as Target

The connector is Connected but cannot reach your system

The system is down, or the target's url is wrong

Run peaky-connector check in the connector, and check the target's url from where it runs

Problems specific to one integration are on its page — see Supported integrations.