bulkhead-connect

Get certified without exposing an endpoint.

The other way to be certified is to expose an HTTPS endpoint and let Bulkhead call it, verifying our signature so nobody else can. That works, and for many teams it is the easier internal approval. It is also impossible for a great many production agents: inside a VPC, in a cluster, behind a corporate proxy, there is no public ingress to expose and no appetite for creating one.

This reverses the direction. You run it beside your agent; it opens one outbound TLS connection to Bulkhead and receives certification probes on it. You open no port, change no firewall rule, and add no public surface — the same shape as a CI runner or a compliance agent.

npm install bulkhead-connect

With your handler

import { createBulkheadHandler } from 'bulkhead-adapter';
import { connect } from 'bulkhead-connect';

connect({
  credential: process.env.BULKHEAD_AGENT_CREDENTIAL,   // bhc_… from the console
  handler: createBulkheadHandler(myAgent),             // what you already wrote
  binding: 'production',
});

If you already have /bulkhead working, that is the whole change. The connector calls the same handler Bulkhead would have called over HTTP.

Or without touching your code

Already running the endpoint on localhost and simply not willing to make it public? Point the CLI at it:

BULKHEAD_AGENT_CREDENTIAL=bhc_… \
  npx bulkhead-connect --forward http://127.0.0.1:8080/bulkhead --binding production

What it can and cannot do

• It receives a scenario name from a closed list and calls your handler. It rejects any scenario it was not compiled with, so new scenarios reach you as a version of this package you choose to install — never as something pushed into a running process.
• There is no message in the protocol that names code to run, a URL to fetch, or a suite to execute. That is a limit on Bulkhead, not on you, and it is the first thing to show a reviewer.
• It cannot read your filesystem or reach your other services.
• It holds one credential, issued by us and scoped to your one agent. It holds no credential of yours.
• It is never in your request path. If it dies, your agent is unaffected.
• It is MIT licensed and short. Read it rather than trusting this list.

binding

What you are connecting: production, staging or sandbox. It is printed on your certificate so a buyer can see the scope of what was tested. We do not verify it — the same convention a classification or ISO certificate uses, where the auditor verifies the declared scope and the scope appears on the certificate so the reader can judge it. Defaults to sandbox.

Credentials

Issue one per agent in the console. It is shown once; only a hash is stored, so there is no recovery — rotate instead. Both credentials stay live during a rotation, so deploy the new one, confirm it connects, then revoke the old one. No maintenance window.

Reconnection

Automatic, with exponential backoff to 30 seconds. A deploy or a restart is a disconnect, not a failed check: your seal is not suspended for reconnecting, and the connector never becomes the reason a container refuses to exit.

Events

connect({
  ...,
  onEvent: (event) => {
    // connected | disconnected | reconnecting | probe | refused | error
    console.log(event);
  },
});

Requires Node 20 or later, which has a built-in WebSocket. Pass WebSocketImpl to supply your own.

Full transport contract: docs/protocol-v1.md. What we do and do not receive: agentbulkhead.com/trust.