From nothing to monitored

Connect the repo

Run this where your agents live. It finds the MCP servers you already call, opens your browser to approve, and takes the first snapshot of every contract. No MCP servers? It sets up execution traces instead, step 4 becomes the whole product.

npx zevruna

The approval page asks you to sign in, then to confirm the code the terminal is showing. Signing in is what makes the project yours: the account, not the token, is what you recover with. Until you approve, the CLI keeps polling, so leave it running and approve in the browser tab it opened.

Servers on localhost. Zevruna polls from the cloud, so it can never reach a server running on your machine, those register as push-only and their contract is captured locally instead. The wizard prints the exact command per server:

zevruna snapshot <name> --push

Run it once now, and from CI so the contract stays current. Same path stdio servers take, for the same reason: the cloud never spawns your processes.

Done when the wizard says either “You’re live” (alerts are on) or “Project ready” with the one step left. It never claims to be watching something it isn’t.

Confirm it is really working

Checks the install against reality rather than against your config. Exits 1 while anything is wrong, so it doubles as a CI assertion.

npx zevruna doctor

Done when the last line reads “Zevruna is ready.”

Fail the build when a contract breaks

An alert is easy to ignore; a red check is not. Paste this workflow, it gates on the manifests step 1 wrote, and fails the build rather than passing quietly if none are committed.

# .github/workflows/contracts.yml
name: contracts
on:
  push: { branches: [main] }
  pull_request:
  schedule: [{ cron: "0 6 * * *" }]   # nightly: the server drifts, your code doesn't

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npx --yes zevruna@latest check --manifest "agents/*.yaml" --against pinned
        env:
          ZEVRUNA_TOKEN: ${{ secrets.ZEVRUNA_TOKEN }}

Keep the nightly schedule. It is the run that catches a server drifting while nothing in your repo changed, which no test you own can see, because nothing you own changed.

Done when a pull request shows a “contracts” check.

Optional, see inside the runs

Steps 1–3 tell you a contract moved. This tells you what your agent actually did. One boundary, wrapped by your coding agent, the wizard already installed the skill it needs.

npx zevruna instrument --json   # ranked candidates, each with a diff
npx zevruna doctor --json       # telemetry_received: ok

By hand it is an install and two lines. See exactly what it sends first if a security review is involved.

Or let your coding agent do it. Step 1 registered our MCP server, so ask it to “set up Zevruna”: propose_instrumentation hands it the ranked boundaries with the exact edit for each, and run_doctor tells it whether a run actually arrived. It proposes, you review the diff, nothing is written unattended.

In Node, wrap on the server, not in the browser. That SDK needs node:async_hooks, which a bundler stubs to an empty object, so a client-side wrap builds green and then throws the moment the chunk evaluates. If your turn loop runs in the browser, wrap the route it calls. Candidates are ranked with this in mind and a browser file is never proposed. Python and Go have no equivalent trap.

Node

npm install @zevruna/observe

import { observeAgent, instrumentMcpClient } from "@zevruna/observe";

const client = instrumentMcpClient(mcpClient, "acme-crm");
await observeAgent({ name: "support-agent" }, () => runSupportAgent(input));

Python

pip install zevruna

from zevruna import observe_agent, instrument_mcp_client

client = instrument_mcp_client(mcp_client, "acme-crm")
async with observe_agent("support-agent"):
    await run_support_agent(user_input)

Go

go get github.com/Kevin-Benelli/zevruna-go

ctx, trace := zevruna.StartTrace(ctx, "support-agent")
defer trace.EndWith(&err)

crm := zevruna.InstrumentMCP(client, "acme-crm")

All three emit the same versioned events and behave identically down to retry backoff and what they refuse to send. The protocol is the contract, and shared fixtures hold them to it in CI.

Already exporting OpenTelemetry? Then skip this step. Point your exporter at https://zevruna.com/api/otlp and your existing spans arrive as runs — two environment variables, no code change.

Every SDK reads ZEVRUNA_TOKEN from the environment, none of them reads .env.zevruna for you, so load that file or set the variable however your runtime already does. Without a token they stay silent rather than throwing: telemetry must never be able to take down the agent it is watching.

Done when doctor reports telemetry_received. Not when the diff looks right, when a run has arrived.