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 |
|---|---|
An Odoo on your own network, reached with the odoo-readonly profile, which lets Peaky read and nothing else | |
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 | |
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.aion 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
On the Integrations page, open the Connectors tab and click Add connector.
Give it a Name you will recognise, such as the machine it runs on, and click Add.
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 | |
Docker Compose | You keep your machine's services in Compose files, or want the settings in a file rather than a command | |
Linux service | You have a Linux machine without Docker, or prefer not to run containers. The connector runs as a system service | |
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 | |
Helm | You run Kubernetes. The recommended way there | |
Kubernetes | You run Kubernetes and apply plain YAML yourself, with |
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 |
|---|---|
| The name Peaky uses for the target, such as |
| The system's address as the connector's machine reaches it, such as |
| A ready-made set of rules for a kind of system, such as |
| Optional. A certificate file to trust for this target, when your system uses a certificate from your own certificate authority |
| Optional. How long the connector waits for the system to answer. Default 300 |
| Optional. Set to |
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 |
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 |
The connector is Connected but cannot reach your system | The system is down, or the target's | Run |
Problems specific to one integration are on its page — see Supported integrations.