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, 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:
macOS, Intel: the same, with dojo-connect-darwin-amd64.
Linux, x86-64:
Linux, arm64: the same, with dojo-connect-linux-arm64.
Windows, x86-64, in PowerShell:
Check it worked:
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.
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
On Windows, that is .\dojo-connect.exe from the folder you downloaded it into.
It prints one line when it is up:
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:
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.
- 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.
- 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.
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
- Connect a partner endpoint to create and register the
connection.
- Run a conformance suite against it.