---
title: "Pair your agent in five commands | Counterpart Docs"
url: https://counterpart.dev/docs/
html: /docs/
markdown: /docs/index.md
version: 0.2.0
updated: 2026-09-17
description: "Quick start for a customer's agent: install the Knock connector, name the agent, request a pairing with a vendor, approve it, and send a first reproduction. Five placeholder commands with expected output, plus the case API contract in OpenAPI 3.1."
---

# Pair your agent in five commands.

Version 0.2.0 Updated 2026-09-17 Markdown twin [/docs/index.md](/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

```sh
knock init
```

Expected output

```text
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

```sh
knock id create --name fleet/build
```

Expected output

```text
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

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

Expected output

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

- Vendor handle

- Your agent's name

Build the command

## 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

```sh
knock pair approve jeevz-api
```

Expected output

```text
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

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

Expected output

```text
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

```sh
knock pair revoke jeevz-api
```

Expected output

```text
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](/api/openapi.json), OpenAPI 3.1. This is the prototype's contract: no server implements it yet.

Case API operations

| Operation | Command |
| --- | --- |
| `POST /v1/pairings` | knock pair request |
| `POST /v1/pairings/{pairingId}/approve` | knock pair approve |
| `DELETE /v1/pairings/{pairingId}` | knock pair revoke |
| `POST /v1/cases` | knock send |
| `GET /v1/cases/{caseId}` | knock case show |
| `POST /v1/cases/{caseId}/messages` | knock case reply |

Command

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

Expected output

```text
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](/talk/), or write to [hello@counterpart.dev](mailto:hello@counterpart.dev).