Install

Connect your agent with one line

Paste one line into your agent. It reads skill.md, gets the command, signs itself up, and asks you only when it needs money.

Let your agent do it · test mode

The line to paste

It reads skill.md, signs itself up, finds a tool and learns its price, all free. The first time it needs money it sends you one link: one phone screen sets the amount and the monthly limit, and pays. You never paste a key.

Test mode: the address in the line is a placeholder, and no real money moves. A local API runs it today.

Set up Petrova from https://www.usepetrova.xyz/skill.md and follow it. Ask me only when you need money.

Get the pet command

Needs Node 20 or newer (check with node -v). It is one file. This is the same line as in skill.md:

mkdir -p ~/.petrova/bin && curl -fsSL https://www.usepetrova.xyz/cli/petrova.mjs -o ~/.petrova/bin/petrova.mjs && printf '#!/bin/sh\nexec node "$HOME/.petrova/bin/petrova.mjs" "$@"\n' > ~/.petrova/bin/pet && chmod +x ~/.petrova/bin/pet

Then run ~/.petrova/bin/pet, or put ~/.petrova/bin on your PATH and run pet. Test mode: petrova.example is a placeholder and no address is live yet, so today the command is run from a copy of the repository.

Get an open model

Downloads a model from holders into the Hugging Face cache, so your usual tools find it. Every piece is checked against the publisher's signature.

pet download <owner/name>

Built and tested on one machine. No index runs on the internet yet, so today you give --index and --root yourself. How pet works with models

Model gateway (test build)

The steps below are for the model gateway built in October. It runs only on a local test server and is not part of the tools launch. Skip them unless you are testing models.

Claude Code

Anthropic Messages
  1. Have a key that can spend

    A ptrv_test_ key with "Call models". Make one in the sandbox, or run npm run sandbox:key -- --spend in the repository.

  2. Connect

    Points Claude Code at Petrova. Base URL without /v1. Your Petrova key goes where the Anthropic key would.

    export ANTHROPIC_BASE_URL=http://127.0.0.1:4100
    export ANTHROPIC_API_KEY=ptrv_test_...
    claude
  3. Check it works

    run claude and ask anything. A receipt appears in the dashboard under Receipts, and each answer carries an x-petrova-receipt header.

    > Hello
      Hello from the Petrova sandbox. (canned answer)
    
    x-petrova-receipt: 3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0f

    Petrova reads Claude Code's agent and session headers, so per-agent caps work with no extra setup. Full Claude Code guide

Claude Code plugin: petrova-guard

Skill + status line
  1. Have a key that can spend

    A ptrv_test_ key with "Call models". Make one in the sandbox, or run npm run sandbox:key -- --spend in the repository.

  2. Connect

    Adds /petrova-guard:balance, /petrova-guard:cap 5, /petrova-guard:receipts, the agent wallet skill, and a spend-vs-cap status line. Run from a copy of the Petrova repository.

    claude plugin marketplace add ./plugins/petrova-guard
    claude plugin install petrova-guard@petrova
  3. Check it works

    in Claude Code, run /petrova-guard:balance. It prints your balance. Optional status line: plugins/petrova-guard/bin/petrova-setup.sh --statusline prints a block for ~/.claude/settings.json, then you see Petrova $1.25 / $5.00 cap · bal $18.76.

    /petrova-guard:balance
      Petrova balance: $19.98 available ($0.10 held)

    A plugin cannot set the base URL for you. Run eval "$(plugins/petrova-guard/bin/petrova-setup.sh)" once per shell (it never prints your key), or run plugins/petrova-guard/bin/petrova claude (the plugin's helper script, not pet) to start one routed session.

MCP server

6 tools
  1. Have a key that can spend

    A ptrv_test_ key with "Call models". Make one in the sandbox, or run npm run sandbox:key -- --spend in the repository.

  2. Connect

    Gives any MCP client (Claude Code, Claude Desktop, others) tools for cost estimates, balance, memory, the paid tool store and chain.watch. Cost tools need no key. Run this from the Petrova repository folder.

    claude mcp add petrova \
      --env PETROVA_API_KEY=ptrv_test_... \
      --env PETROVA_API_URL=http://127.0.0.1:4100 \
      -- npm --prefix "$PWD" run --silent mcp
  3. Check it works

    run claude mcp list and see petrova connected. Then ask Claude "what is my Petrova balance?" and it calls the balance tool.

    $ claude mcp list
    petrova: npm --prefix … run --silent mcp - ✓ Connected

    The server reads PETROVA_API_KEY and PETROVA_API_URL (default http://127.0.0.1:4100). Memory tools need a key with memory:read / memory:write. MCP docs

Anthropic SDK

No /v1
  1. Have a key that can spend

    A ptrv_test_ key with "Call models". Make one in the sandbox, or run npm run sandbox:key -- --spend in the repository.

  2. Connect

    Your own agent code on the Anthropic SDK. Set the base URL without /v1; the SDK adds it.

    pip install anthropic
    
    # agent.py
    import anthropic
    client = anthropic.Anthropic(base_url="http://127.0.0.1:4100", api_key="ptrv_test_...")
    msg = client.messages.create(
        model="claude-opus-5-5", max_tokens=1024,
        messages=[{"role": "user", "content": "Hello"}],
        extra_headers={"x-claude-code-agent-id": "my-agent"},
    )
    print(msg.content[0].text)
    npm install @anthropic-ai/sdk
    
    // agent.mjs
    import Anthropic from '@anthropic-ai/sdk';
    const client = new Anthropic({ baseURL: 'http://127.0.0.1:4100', apiKey: 'ptrv_test_...' });
    const msg = await client.messages.create({
      model: 'claude-opus-5-5', max_tokens: 1024,
      messages: [{ role: 'user', content: 'Hello' }],
    }, { headers: { 'x-claude-code-agent-id': 'my-agent' } });
    console.log(msg.content[0].text);
  3. Check it works

    the script prints an answer (canned in the fixture build). The call shows in Receipts with its cost.

    Hello from the Petrova sandbox. This answer is canned: no real model was called.

    The header names the agent so its cap applies. On /v1/messages Petrova reads x-claude-code-agent-id and x-claude-code-session-id; x-petrova-agent-id is read only on the OpenAI routes today. Limits

OpenAI SDK

With /v1
  1. Have a key that can spend

    A ptrv_test_ key with "Call models". Make one in the sandbox, or run npm run sandbox:key -- --spend in the repository.

  2. Connect

    Agents on the OpenAI SDK. Set the base URL with /v1. Chat Completions and Responses both work; Petrova translates them to Claude.

    pip install openai
    
    # agent.py
    from openai import OpenAI
    client = OpenAI(base_url="http://127.0.0.1:4100/v1", api_key="ptrv_test_...")
    r = client.chat.completions.create(
        model="claude-opus-5-5",
        messages=[{"role": "user", "content": "Hello"}],
        extra_headers={"x-petrova-agent-id": "my-agent"},
    )
    print(r.choices[0].message.content)
    npm install openai
    
    // agent.mjs
    import OpenAI from 'openai';
    const client = new OpenAI({ baseURL: 'http://127.0.0.1:4100/v1', apiKey: 'ptrv_test_...' });
    const r = await client.chat.completions.create({
      model: 'claude-opus-5-5',
      messages: [{ role: 'user', content: 'Hello' }],
    }, { headers: { 'x-petrova-agent-id': 'my-agent' } });
    console.log(r.choices[0].message.content);
  3. Check it works

    the script prints an answer. A spent cap answers 429 insufficient_quota, which the SDK does not retry.

    Hello from the Petrova sandbox. This answer is canned: no real model was called.

    Not supported yet: previous_response_id, hosted tools such as web search, and reasoning settings.

Codex CLI

Responses API
  1. Have a key that can spend

    A ptrv_test_ key with "Call models". Make one in the sandbox, or run npm run sandbox:key -- --spend in the repository.

  2. Connect

    Codex talks to /v1/responses. Add a provider to ~/.codex/config.toml.

    model = "claude-opus-5-5"
    model_provider = "petrova"
    
    [model_providers.petrova]
    name = "Petrova"
    base_url = "http://127.0.0.1:4100/v1"
    env_key = "PETROVA_API_KEY"
    wire_api = "responses"
    http_headers = { "x-petrova-agent-id" = "codex-main" }
  3. Check it works

    run export PETROVA_API_KEY=ptrv_test_... then codex. It streams a reply and the call shows in Receipts.

    > Say hello
    Hello from the Petrova sandbox.
    (response.completed · x-petrova-receipt …)

    Full Codex guide

Other coding tools

opencode, OpenClaw, Cline, Roo Code, Kilo Code, Zed and Aider each have a short guide with the exact settings.

All 13 tool guides

Something not working?

  • 401: the key was not accepted. Copy all of it.
  • 403: the key cannot spend. Make one with "Call models".
  • 400 unknown model: use an exact id such as claude-opus-5-5. Models
  • 402: the balance is empty. All errors