> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chargerdojo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Use the connector

> Run dojo-connect beside your OCPI service so we can test it without it ever being reachable from the internet: install, pair, run, and what the connector will not do.

`dojo-connect` is a small binary you run next to your service. It opens an **outbound**
WebSocket to us and forwards the requests we send it to a local address you name. No inbound
firewall rule, no public hostname, no TLS certificate, and your service is never reachable from
the internet at any point.

It is the alternative to [a tunnel](/guide/connect-a-local-endpoint), which works today and
costs you a window of public exposure. Connectors are part of a paid plan.

It is a pipe and nothing more. It holds no test suites, no checks and no verdicts: everything
that decides whether your implementation is correct stays on our servers.

## Install it

Pick your platform, then run the three lines under it. They download the binary, check it against
the published checksum, and put it on your `PATH` so every later command is just `dojo-connect`.

**macOS, Apple silicon:**

```bash theme={null}
curl -fsSLO https://github.com/chargerdojo/dojo-connect/releases/latest/download/dojo-connect-darwin-arm64
curl -fsSLO https://github.com/chargerdojo/dojo-connect/releases/latest/download/checksums.txt
shasum -a 256 --ignore-missing -c checksums.txt
sudo install -m 755 dojo-connect-darwin-arm64 /usr/local/bin/dojo-connect
```

**macOS, Intel:** the same, with `dojo-connect-darwin-amd64`.

**Linux, x86-64:**

```bash theme={null}
curl -fsSLO https://github.com/chargerdojo/dojo-connect/releases/latest/download/dojo-connect-linux-amd64
curl -fsSLO https://github.com/chargerdojo/dojo-connect/releases/latest/download/checksums.txt
sha256sum --ignore-missing -c checksums.txt
sudo install -m 755 dojo-connect-linux-amd64 /usr/local/bin/dojo-connect
```

**Linux, arm64:** the same, with `dojo-connect-linux-arm64`.

**Windows, x86-64**, in PowerShell:

```powershell theme={null}
Invoke-WebRequest https://github.com/chargerdojo/dojo-connect/releases/latest/download/dojo-connect-windows-amd64.exe -OutFile dojo-connect.exe
```

Check it worked:

```bash theme={null}
dojo-connect --version
```

<Warning>
  On macOS, download with `curl` as above rather than through a browser. The binaries are not
  code signed yet, so a browser marks the file as quarantined and macOS kills the first run
  without printing anything: no dialog, no error, just an exit code. If that has already happened,
  run `xattr -d com.apple.quarantine <file>` and try again. On Windows, SmartScreen shows a
  warning instead: choose **More info**, then **Run anyway**.
</Warning>

## Pair it

Go to **Endpoints** and start **Add endpoint**. When it asks where the service is, answer
**Behind a local connector**, then choose **Pair a connector**. Name it after the machine it will
run on: that name is what every endpoint and every report calls it. The endpoint form stays open
behind the pairing, so nothing you have already typed is lost.

Once you have one connector, the **Local connectors** list at the foot of the Endpoints page
pairs any others.

Pairing gives you a token that starts with `cdpair_`. We do not keep it, so we cannot show it to
you twice. Copy it when it appears; if you lose it, revoke the connector and pair a new one.

## Run it

```bash theme={null}
dojo-connect --target http://localhost:8000 --token <pairing token>
```

On Windows, that is `.\dojo-connect.exe` from the folder you downloaded it into.

It prints one line when it is up:

```
connected as target "emsp-local"
```

The name in that line is the connector's own: `--name` if you passed one, otherwise your
machine's hostname. It is not the name you typed when pairing, which is the one endpoints and
reports use.

On any machine other people can log into, and in CI, pass the token in the environment instead.
On the command line it is visible in your shell history and to anyone who can list processes:

```bash theme={null}
export DOJO_CONNECTOR_TOKEN=<your pairing token>
dojo-connect --target http://localhost:8000
```

Change `--target` if your service is not on port 8000, and repeat `--target` if it answers on
more than one port.

The connector shows as connected on the Endpoints page within a few seconds. Go back to the
endpoint form, pick your connector, and give the base URL your connector forwards to. Register it
and run a suite exactly as you would against a partner.

## Where it will and will not send requests

Two rules, in this order, and both live in the connector rather than on our servers.

1. **It forwards only to the origins you named with `--target`.** A request for any other host or
   port comes back refused, and the refusal names what was asked for. Every loopback spelling of
   your own machine counts as the same place, in either IP version, which matters because your
   service will usually advertise the numeric form during the handshake even when you typed the
   name.
2. **The address has to be one your own network owns.** Loopback, the RFC 1918 private ranges and
   the RFC 4193 IPv6 unique-local range `fc00::/7`, plus three more that catch people out: carrier-grade NAT (`100.64.0.0/10`),
   which is what Tailscale and other mesh VPNs hand out, so reaching your service over one works;
   link-local (`169.254.0.0/16`, `fe80::/10`); and the all-zeroes "this network" block, which on
   Linux dials loopback. Everything else is public. This is
   checked against the address the name actually resolves to, every time the connector dials, not
   once at startup, so a name that starts answering with a public address later does not get
   through. Requests that reuse an already open connection do not dial again, so the check is per
   connection rather than literally per request. Pass `--allow-public-target` if you deliberately
   want to forward somewhere public.

`--allow-public-target` is not a blanket waiver. Cloud instance metadata addresses
(`169.254.169.254` and four siblings on AWS, Alibaba Cloud and the AWS container agents) stay
refused with it on, because those addresses hand out the access keys of the machine your
connector runs on.

Because your connector dials your service, we never do. On this path we do not resolve or
connect to your address at all, which is why a private address is fine here and refused on the
[tunnel path](/guide/connect-a-local-endpoint).

## What you are trusting

Worth saying plainly, because it is the one thing no code on our side can check.

We send requests to your connector. Your connector decides where they go. The verdict in the
report is therefore only as good as the pairing token: anyone holding it can connect and answer
for your endpoint, and the answers they give would be graded as yours. Keep the token where you
keep your other secrets, and revoke it the moment you think it has leaked.

Revoking is immediate and reaches a running process: the connector disconnects within a second,
prints why, and its token stops working for good. One token also means one machine. Start the
same token somewhere else and the first connector is closed out, so pair a second connector for
a second machine rather than sharing one.

## What it does not do yet

* **Charging Journeys and load runs do not work over a connector.** They run in a separate
  worker process that cannot reach the socket your connector holds, so the app does not offer a
  connector-backed endpoint for a journey and the API refuses one if you ask it directly.
  Conformance runs are what a connector carries today.
* **A response body larger than about 6 MiB fails the request**, rather than being split across
  frames. The socket carries 8 MiB frames, and bodies travel Base64 encoded, which costs a third:
  on the default limit the usable body budget works out at 6,285,312 bytes. The refusal names that
  body budget and never the 8 MiB frame ceiling, deliberately, because quoting 8 MiB would send you
  looking for headroom that was never there.
* **A run does not wait for a connector to start.** If the connector is not running when you
  start one, the run fails immediately with `The connector "<name>" for this endpoint is not
  connected. Start it and try again.` Start the connector and run again.
* **A run that is already going does wait, briefly, for a connector that drops.** Your machine
  changing wifi or waking from sleep takes the socket down and the connector comes straight back
  on a new one. A check issued in that gap waits up to two seconds for the new connection and then
  travels over it, so a blip does not turn the rest of the run into failures your endpoint never
  caused. If nothing comes back in those two seconds, the run stops waiting and every remaining
  check fails by name, so a connector that is really gone never looks like a partner problem. The
  report records that the run crossed a reconnect either way.

## Next

1. [Connect a partner endpoint](/guide/connect-a-partner) to create and register the
   connection.
2. [Run a conformance suite](/guide/run-a-suite) against it.