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.
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/petThen 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 MessagesHave a key that can spend
A
ptrv_test_key with "Call models". Make one in the sandbox, or runnpm run sandbox:key -- --spendin the repository.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_... claudeCheck it works
run
claudeand ask anything. A receipt appears in the dashboard under Receipts, and each answer carries anx-petrova-receiptheader.> Hello Hello from the Petrova sandbox. (canned answer) x-petrova-receipt: 3b0e1d52-8c7a-4f19-9d2e-5a6b7c8d9e0fPetrova 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 lineHave a key that can spend
A
ptrv_test_key with "Call models". Make one in the sandbox, or runnpm run sandbox:key -- --spendin the repository.Connect
Adds
/petrova-guard:balance,/petrova-guard:cap 5,/petrova-guard:receipts, the agentwalletskill, 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@petrovaCheck it works
in Claude Code, run
/petrova-guard:balance. It prints your balance. Optional status line:plugins/petrova-guard/bin/petrova-setup.sh --statuslineprints a block for~/.claude/settings.json, then you seePetrova $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 runplugins/petrova-guard/bin/petrova claude(the plugin's helper script, notpet) to start one routed session.
MCP server
6 toolsHave a key that can spend
A
ptrv_test_key with "Call models". Make one in the sandbox, or runnpm run sandbox:key -- --spendin the repository.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 mcpCheck it works
run
claude mcp listand seepetrovaconnected. Then ask Claude "what is my Petrova balance?" and it calls thebalancetool.$ claude mcp list petrova: npm --prefix … run --silent mcp - ✓ ConnectedThe server reads
PETROVA_API_KEYandPETROVA_API_URL(defaulthttp://127.0.0.1:4100). Memory tools need a key withmemory:read/memory:write. MCP docs
Anthropic SDK
No /v1Have a key that can spend
A
ptrv_test_key with "Call models". Make one in the sandbox, or runnpm run sandbox:key -- --spendin the repository.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);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/messagesPetrova readsx-claude-code-agent-idandx-claude-code-session-id;x-petrova-agent-idis read only on the OpenAI routes today. Limits
OpenAI SDK
With /v1Have a key that can spend
A
ptrv_test_key with "Call models". Make one in the sandbox, or runnpm run sandbox:key -- --spendin the repository.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);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 APIHave a key that can spend
A
ptrv_test_key with "Call models". Make one in the sandbox, or runnpm run sandbox:key -- --spendin the repository.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" }Check it works
run
export PETROVA_API_KEY=ptrv_test_...thencodex. It streams a reply and the call shows in Receipts.> Say hello Hello from the Petrova sandbox. (response.completed · x-petrova-receipt …)
Other coding tools
opencode, OpenClaw, Cline, Roo Code, Kilo Code, Zed and Aider each have a short guide with the exact settings.
Something not working?
401: the key was not accepted. Copy all of it.403: the key cannot spend. Make one with "Call models".400unknown model: use an exact id such asclaude-opus-5-5. Models402: the balance is empty. All errors