vault-proxy Python SDK

Python client for vault-proxy -- secrets vault with HTTP proxy for AI agents.

Install

pip install vault-proxy

Quick Start

from vault_proxy import VaultClient

client = VaultClient()  # reads VAULT_ADDR + VAULT_TOKEN from env

# Unlock the vault
token = client.unlock("master-password")

# Proxy an API call -- vault injects credentials automatically
resp = client.proxy("openrouter", "POST", "/v1/chat/completions", json={
    "model": "anthropic/claude-haiku-4-5",
    "messages": [{"role": "user", "content": "hello"}],
})
print(resp.json())

Usage

Connect

from vault_proxy import VaultClient

# From environment variables (VAULT_ADDR, VAULT_TOKEN)
client = VaultClient()

# Explicit
client = VaultClient(addr="http://localhost:8390", token="tok_abc123")

# Context manager
with VaultClient() as client:
    print(client.health())

Proxy API Calls

The vault injects credentials automatically. Your code never sees the secrets.

# Simple request
resp = client.proxy("openrouter", "POST", "/v1/chat/completions", json=body)
data = resp.json()

# Streaming
for chunk in client.proxy_stream("openrouter", "POST", "/v1/chat/completions", json=body):
    print(chunk.decode(), end="")

Manage Services

# List services
services = client.list_services()
for svc in services:
    print(f"{svc.name} -> {svc.base_url} ({svc.auth_type})")

# Add a service
client.add_service({
    "name": "anthropic",
    "base_url": "https://api.anthropic.com",
    "auth": {"type": "header", "header_name": "x-api-key", "header_value": "sk-ant-xxx"},
})

# Remove a service
client.remove_service("anthropic")

Tokens

# Create a proxy-only token (safe to give to AI agents)
proxy_token = client.create_token("proxy")

# List active tokens
for tok in client.list_tokens():
    print(f"{tok.id_prefix}... ({tok.scope})")

# Revoke a token
client.revoke_token("tok_abc123")

File Storage

Store credential files (service account JSONs, client secrets) encrypted in the vault.

# Upload
client.upload_file("google-sa", "service-account.json")

# List
for f in client.list_files():
    print(f"{f.name} ({f.size} bytes)")

# Download
data = client.get_file("google-sa")

# Delete
client.delete_file("google-sa")

Error Handling

from vault_proxy import VaultClient, VaultError

try:
    client.unlock("wrong-password")
except VaultError as e:
    print(f"Failed: {e.status_code} - {e.message}")

Environment Variables

Variable	Default	Description
VAULT_ADDR	http://127.0.0.1:8390	Server address
VAULT_TOKEN	--	Session token

Requirements

• Python >= 3.10
• A running vault-proxy server

License

MIT