Quickstart

Drop Sphyr into your Python or Node agent with a single import. Every outbound request made through supported HTTP libraries gets signed, policy-checked, and logged automatically.

5 min Python · Node Updated Jun 2026

1. Install the SDK

Drop the SDK into your Python or Node.js backend. Both packages auto-handle HMAC signing, session refresh, and safety verification.

$ pip install sphyr-sdk

$ npm install @sphyr/sdk

Local IDE agents? If your agent runs inside Claude Desktop, Claude Code CLI, Cursor, VS Code, Antigravity, Zed, Windsurf, or OpenAI Codex, the CLI configures Sphyr as an MCP server in every detected client at once.

MCP / IDE

$ npx @sphyr/cli login

That's it — credentials are already configured

npx @sphyr/cli login uses device authorization (RFC 8628) — a short code is displayed in the terminal and approved at console.sphyr.io/device. Credentials are delivered securely in the server response body, never in URL query parameters. Previous versions used a loopback redirect; device authorization is the only supported flow. Manage keys later from the console.

2. Watch it work

Open the request log in the Sphyr console. Every request your agent makes is logged — view URL, method, outcome, and cryptographic signature in the request log.

MCP integration — connect any MCP client with a single config block

Data transmitted

Every proxied request sends hashed URL, HTTP method, timestamp, entropy score, and outcome to Sphyr. Data is stored per the Privacy Policy and purged within 36 days.

SDK Samples

Complete, runnable scripts. Run npx @sphyr/cli login once first — it writes your credential to ~/.sphyr/config.json so the SDK picks it up automatically. For CI/server environments, set SPHYR_CREDENTIAL env var instead.

// guard-demo.mjs — Run: node guard-demo.mjs
import  autoInstrument  from "@sphyr/sdk";

// One call — every fetch() in your agent is now signed and audited
// Credentials auto-loaded from ~/.sphyr/config.json (run: npx @sphyr/cli login)
autoInstrument();

// Your agent code — no changes needed:
const response = await fetch("https://api.example.com/data");
const data = await response.json();
console.log(data);

# guard_demo.py — Run: python guard_demo.py
from sphyr_sdk import auto_instrument

# One call — every requests.get() / httpx call is now signed and audited
# Credentials auto-loaded from ~/.sphyr/config.json (run: npx @sphyr/cli login)
auto_instrument()

# Your agent code — no changes needed:
import requests
response = requests.get("https://api.example.com/data")
print(response.json())

Fail-closed by default (v2.0.0-beta.1+)

If the Sphyr gateway is unreachable, instrumented requests throw SphyrNetworkError rather than passing through unscreened. Pass autoInstrument({ failClosed: false }) (JS) or auto_instrument(fail_closed=False) (Python) to prioritize uptime over strict enforcement.

Library Compatibility

auto_instrument() / autoInstrument() patch the standard HTTP layers listed below. Anything that bypasses a patched layer — custom socket transports, raw TCP, or an unlisted HTTP library — is not intercepted and requires manual wrapping.

Runtime	Library	Coverage
Python	`requests`	Automatic — all `Session` instances
Python	`httpx`	Automatic — `Client` and `AsyncClient`
Node.js / TS	global `fetch`	Automatic — Node 18+ and any runtime with global fetch
Node.js / TS	`axios`	Automatic — v1.x default adapter
Python	`aiohttp`, `urllib`	Manual wrapping required
Node.js / TS	`http` / `https` core modules	Manual wrapping required

Auto-excluded from instrumentation: the Sphyr gateway host itself, loopback (localhost, 127.0.0.1, [::1]), and RFC 1918 private ranges. Link-local addresses (169.254.0.0/16, including cloud metadata endpoints) are deliberately not excluded — they route through the gateway so SSRF screening can block them.

Verifying Webhook Deliveries

Every webhook delivery includes an X-Sphyr-Signature header containing an HMAC-SHA256 signature of the raw request body, hex-encoded. Use your webhook signing secret (shown once at creation or after rotation) to verify that deliveries originate from Sphyr.

The signing secret is a 64-character hex string. Header format: X-Sphyr-Signature: <hex>. Algorithm: HMAC-SHA256 over the raw UTF-8 request body.

# Python — verify X-Sphyr-Signature header
import hmac, hashlib

def verify_sphyr_webhook(payload_bytes: bytes, received_signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), payload_bytes, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, received_signature)

// TypeScript (Browser / Workers / Node 18+) — verify X-Sphyr-Signature header
async function verifySphyrWebhook(payload: string, signature: string, secret: string): Promise<boolean> {
  const enc = new TextEncoder();
  const key = await crypto.subtle.importKey('raw', enc.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['verify']);
  const sigBytes = new Uint8Array(signature.match(/.{2}/g)!.map((b) => parseInt(b, 16)));
  return crypto.subtle.verify('HMAC', key, sigBytes, enc.encode(payload));
}

To rotate your signing secret, call POST /v1/console/webhooks/:webhookId/rotate (authenticated console session required). The new secret is returned once in the response body and the old secret is immediately invalidated.

IDE Setup (manual)

If you ran npx @sphyr/cli guard init, these configs are already written for you — just restart your IDE. Use the blocks below only if you need to configure manually. (login only writes your credential; init is what writes the per-IDE MCP config.)

Sphyr connects through sphyr-mcp, a stdio MCP proxy that signs every outbound call with your single credential. Set SPHYR_CREDENTIAL in the env block below.

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "sphyr": {
      "command": "npx",
      "args": ["-y", "-p", "@sphyr/sdk", "sphyr-mcp"],
      "env": { "SPHYR_CREDENTIAL": "your-credential" }
    }
  }
}

Edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "sphyr": {
      "command": "npx",
      "args": ["-y", "-p", "@sphyr/sdk", "sphyr-mcp"],
      "env": { "SPHYR_CREDENTIAL": "your-credential" }
    }
  }
}

Edit ~/.vscode/mcp.json or run MCP: Open User Configuration:

{
  "servers": {
    "sphyr": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "-p", "@sphyr/sdk", "sphyr-mcp"],
      "env": { "SPHYR_CREDENTIAL": "your-credential" }
    }
  }
}

Edit ~/.gemini/antigravity/mcp_config.json:

{
  "mcpServers": {
    "sphyr": {
      "command": "npx",
      "args": ["-y", "-p", "@sphyr/sdk", "sphyr-mcp"],
      "env": { "SPHYR_CREDENTIAL": "your-credential" }
    }
  }
}

Edit ~/.config/zed/settings.json:

{
  "context_servers": {
    "sphyr": {
      "command": "npx",
      "args": ["-y", "-p", "@sphyr/sdk", "sphyr-mcp"],
      "env": { "SPHYR_CREDENTIAL": "your-credential" }
    }
  }
}

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "sphyr": {
      "command": "npx",
      "args": ["-y", "-p", "@sphyr/sdk", "sphyr-mcp"],
      "env": { "SPHYR_CREDENTIAL": "your-credential" }
    }
  }
}

Edit ~/.claude/mcp_servers.json:

{
  "mcpServers": {
    "sphyr": {
      "command": "npx",
      "args": ["-y", "-p", "@sphyr/sdk", "sphyr-mcp"],
      "env": { "SPHYR_CREDENTIAL": "your-credential" }
    }
  }
}

Add the mcpServers key to your codex.json:

{
  "mcpServers": {
    "sphyr": {
      "command": "npx",
      "args": ["-y", "-p", "@sphyr/sdk", "sphyr-mcp"],
      "env": { "SPHYR_CREDENTIAL": "your-credential" }
    }
  }
}

Rate limits

Default limits enforced by the gateway:

10 req/s per agent
100 req/s per key
300 req/s per IP
500 req/s pre-auth backstop

Rate-limited requests receive HTTP 429 with a Retry-After header.