Onboarding

Adopt Vouch in six guided steps.

The Vouch Protocol paper describes a six-step adoption path. The vouch onboard CLI wizard walks you through each step, generates the artifacts, and persists your progress so an interrupted session resumes where you left off. This page mirrors the wizard step-by-step; use it to look before you leap, then run the command on your own machine.

Every step below has a Try it locally first note so you can prove the loop end-to-end in your dev env, no domain or hosting required, before you publish anything. The production command for each step is unchanged.

bash

pip install vouch-protocol && vouch onboard

Step 1 of 6 . 2 minutes

Generate the issuer DID

The wizard generates an Ed25519 keypair, derives a did:web identifier from your domain, and writes a standards-aligned DID Document. You publish the document at /.well-known/did.json on the domain you chose; everything downstream resolves the issuer through that path.

Try it locally first

pass --domain localhost. The wizard still emits a valid keypair and a did.json, but you do not publish it. The signer and verifier in later steps will work end-to-end against the in-memory key, so you can prove the whole loop before owning a domain.

Run

bash

vouch onboard --domain agent.acme.example --tier standard --lang python

Artifact: did.json

json

{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://w3id.org/security/suites/jws-2020/v1"
  ],
  "id": "did:web:agent.acme.example",
  "verificationMethod": [
    {
      "id": "did:web:agent.acme.example#key-1",
      "type": "JsonWebKey2020",
      "controller": "did:web:agent.acme.example",
      "publicKeyJwk": {
        "kty": "OKP",
        "crv": "Ed25519",
        "x": "<base64url public key>"
      }
    }
  ],
  "authentication": ["did:web:agent.acme.example#key-1"],
  "assertionMethod": ["did:web:agent.acme.example#key-1"]
}

§ II

What the wizard writes

Every step emits a real artifact, not a placeholder. The full set is ready to drop into your deployment.

did.json

Standards-aligned did:web document with an Ed25519 verification method. Commit to your domain at /.well-known/did.json.

~/.vouch/onboarding.json

Persisted wizard state so you can resume across sessions and machines. Encrypted private key sits next to it in ~/.vouch/keys/.

vouch-allowlist.json

The action vocabulary the verifier enforces. Three starter presets cover read-only, scoped read-write, and regulated workloads.

vouch-toolwire.{py,ts,go}

Tool-call wrapper for your agent runtime. Intercepts every call, mints a credential against the Sidecar /sign endpoint, attaches it as Vouch-Token.

vouch-verifier.{py,ts,go}

Drop-in middleware for FastAPI, Express, or Gin. Verifies the Vouch-Token header and rejects calls whose action is not allow-listed.

vouch-heartbeat.yaml

Kubernetes deployment for the heartbeat validator. One replica for standard tier; three for regulated, set automatically.

§ III

Time budget

The Vouch Protocol paper estimates one to two engineering days for the credential layer and two to four days for state verifiability and quorum. The wizard collapses the credential layer into roughly thirty interactive minutes by generating every artifact for you; the remaining time goes to deploying and integration testing in your own infrastructure.

Credential layer: Wizard~30 minutes
By hand1 to 2 days
State verifiability: Wizard~10 minutes
By hand2 to 4 days
Time to first verified request: Wizardunder 1 hour
By handmultiple days