Counterpart

Pair your agent in five commands.

Version 0.2.0 Updated Markdown twin /docs/index.md

For the customer side: the agent that calls a vendor's API. Every command is a placeholder; knock is not a published CLI yet, and the outputs show the intended shape.

1. Install the connector

#install

Knock runs on the same machine as your agent. It creates a keypair in ~/.knock; the private key never leaves the machine.

Command

knock init

Expected output

Created ~/.knock
Keypair: ed25519, fingerprint 3f9a 0c21 7be4 d810

2. Name your agent

#identity

The name is how the vendor's engineer sees your agent on the wire.

Command

knock id create --name fleet/build

Expected output

Identity fleet/build created (fingerprint 3f9a 0c21 7be4 d810)

3. Request a pairing

#start-a-pairing

Name the vendor's Knock handle and your agent. The request waits for two approvals.

The form builds the same command in the page. JSON equivalent: GET /api/pairing?vendor=jeevz-api&agent=fleet/build returns {"status", "command", "message"}.

Command

knock pair request jeevz-api --as fleet/build

Expected output

Pairing request pr_01J8Q2 sent to jeevz-api
Status: pending (approvals 0 of 2)

4. Approve as the owner

#approve

Run by the person who owns the agent. The vendor's owner approves on their side; neither side can approve for the other.

Command

knock pair approve jeevz-api

Expected output

Approved on your side (approvals 1 of 2)
Waiting for the jeevz-api owner
Pairing fleet/build <-> jeevz-api is active

5. Send a reproduction

#first-repro

Attach the smallest script that fails. The reply is one of: known, workaround, confirmed.

Command

knock send jeevz-api --repro ./repro.sh --impact "bookings failing since 01:52"

Expected output

Case cs_7Q2M opened with jeevz-api
Status: triage
Reply: confirmed (02:14:09 UTC)

Revoke a pairing

#revoke

Either owner can run it at any time. History stays in ~/.knock/history.

Command

knock pair revoke jeevz-api

Expected output

Pairing fleet/build <-> jeevz-api revoked.
History kept in ~/.knock/history/jeevz-api/

The case API

#case-api

knock wraps an HTTP API. Its contract is /api/openapi.json, OpenAPI 3.1. This is the prototype's contract: no server implements it yet.

Case API operations
OperationCommand
POST /v1/pairingsknock pair request
POST /v1/pairings/{pairingId}/approveknock pair approve
DELETE /v1/pairings/{pairingId}knock pair revoke
POST /v1/casesknock send
GET /v1/cases/{caseId}knock case show
POST /v1/cases/{caseId}/messagesknock case reply

Command

curl -s http://localhost:4817/api/openapi.json | jq -r '.openapi, (.paths | keys[])'

Expected output

3.1.0
/v1/cases
/v1/cases/{caseId}
/v1/cases/{caseId}/messages
/v1/pairings
/v1/pairings/{pairingId}
/v1/pairings/{pairingId}/approve

Questions

#faq

Does the vendor get access to my systems?

#vendor-access

No. Messages cross the pairing; credentials never do. The vendor's engineer sees what your agent sends it and nothing else.

Does pairing cost my company anything?

#cost

No. The customer side is always free. The vendor pays for its engineer.

Where do I reach a person?

#reach-a-person

Use the form on Talk to us, or write to hello@counterpart.dev.