# 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](/doc/run-on-docker-o5CZCzqkk4), [Run on Linux](/doc/run-on-linux-h1rOBYadEK), [Run on Windows](/doc/run-on-windows-Q0AucWclz0) and [Run on Kubernetes](/doc/run-on-kubernetes-scvf7JLIud), 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](/doc/connect-odoo-aJavQRQQs6) | An Odoo on your own network, reached with the **odoo-readonly** profile, which lets Peaky read and nothing else |
| [Dynamics NAV](/doc/connect-dynamics-nav-UsFyxwVQnL) | 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](/doc/connect-sap-business-one-yIN8CxvNYT) | 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](#proxies-and-certificates)).
* The **Create** right on integrations in Peaky. See [Team & Roles](/doc/team-roles-ORspfM4rgP).


---

## 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](#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](#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](/doc/run-on-docker-o5CZCzqkk4) |
| **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](/doc/run-on-docker-o5CZCzqkk4) |
| **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](/doc/run-on-linux-h1rOBYadEK) |
| **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](/doc/run-on-windows-Q0AucWclz0) |
| **Helm** | You run Kubernetes. The recommended way there | [Run on Kubernetes](/doc/run-on-kubernetes-scvf7JLIud) |
| **Kubernetes** | You run Kubernetes and apply plain YAML yourself, with `kubectl`, kustomize or a GitOps tool | [Run on Kubernetes](/doc/run-on-kubernetes-scvf7JLIud) |

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](#supported-integrations)) and put in your own system's address. For an Odoo, for example:

```toml
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](/doc/run-on-docker-o5CZCzqkk4#change-the-configuration), [Run on Linux](/doc/run-on-linux-h1rOBYadEK#change-the-configuration), [Run on Windows](/doc/run-on-windows-Q0AucWclz0#change-the-configuration) or [Run on Kubernetes](/doc/run-on-kubernetes-scvf7JLIud#change-the-configuration).

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](#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](#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](#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](/doc/fixing-a-connection-jKz29zCMG7#peaky-connector).


---

## 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](#the-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](/doc/run-on-docker-o5CZCzqkk4#move-or-reinstall), [Run on Linux](/doc/run-on-linux-h1rOBYadEK#move-or-reinstall), [Run on Windows](/doc/run-on-windows-Q0AucWclz0#move-or-reinstall) or [Run on Kubernetes](/doc/run-on-kubernetes-scvf7JLIud#move-or-reinstall).
* **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](#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](/doc/run-on-docker-o5CZCzqkk4#logs), [Run on Linux](/doc/run-on-linux-h1rOBYadEK#logs), [Run on Windows](/doc/run-on-windows-Q0AucWclz0#logs) and [Run on Kubernetes](/doc/run-on-kubernetes-scvf7JLIud#check-it) 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](#syncs-through-the-connector): 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](/doc/run-on-docker-o5CZCzqkk4#proxies-and-certificates), [Run on Linux](/doc/run-on-linux-h1rOBYadEK#proxies-and-certificates), [Run on Windows](/doc/run-on-windows-Q0AucWclz0#proxies-and-certificates) or [Run on Kubernetes](/doc/run-on-kubernetes-scvf7JLIud#chart-settings).

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](#activity) in Peaky. For what to check where the connector runs — its log, `peaky-connector check`, restarting it — see Troubleshooting on [Run on Docker](/doc/run-on-docker-o5CZCzqkk4#troubleshooting), [Run on Linux](/doc/run-on-linux-h1rOBYadEK#troubleshooting), [Run on Windows](/doc/run-on-windows-Q0AucWclz0#troubleshooting) or [Run on Kubernetes](/doc/run-on-kubernetes-scvf7JLIud#troubleshooting).

| 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](#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](#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](#syncs-through-the-connector) lists the sync, with the refused calls and their request ids to look up in the [audit log](#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](#supported-integrations).

---

**Documents**

- [Run on Docker](https://docs.peaky.ai/s/052dba34-0c8e-4a5d-90a7-c0572642e54f/doc/run-on-docker-o5CZCzqkk4)
- [Run on Linux](https://docs.peaky.ai/s/052dba34-0c8e-4a5d-90a7-c0572642e54f/doc/run-on-linux-h1rOBYadEK)
- [Run on Windows](https://docs.peaky.ai/s/052dba34-0c8e-4a5d-90a7-c0572642e54f/doc/run-on-windows-Q0AucWclz0)
- [Run on Kubernetes](https://docs.peaky.ai/s/052dba34-0c8e-4a5d-90a7-c0572642e54f/doc/run-on-kubernetes-scvf7JLIud)
- [Connect Odoo](https://docs.peaky.ai/s/052dba34-0c8e-4a5d-90a7-c0572642e54f/doc/connect-odoo-aJavQRQQs6)
- [Connect Dynamics NAV](https://docs.peaky.ai/s/052dba34-0c8e-4a5d-90a7-c0572642e54f/doc/connect-dynamics-nav-UsFyxwVQnL)
- [Connect SAP Business One](https://docs.peaky.ai/s/052dba34-0c8e-4a5d-90a7-c0572642e54f/doc/connect-sap-business-one-yIN8CxvNYT)