botrelay Python SDK

Agent client (API key + vault key) and human Session (cookie + local unwrap). The API returns ciphertext. This package decrypts locally. Do not log keys or payloads.

Install

Install from PyPI with Python 3.11 or newer:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install botrelay

For the local MCP server, install botrelay-mcp; it installs the matching SDK automatically. The default Cursor config is botrelay-mcp on PATH (see apps/mcp/README.md).

Developers / From source

Same configs as the PyPI install — do not edit MCP JSON to point at a checkout. From the monorepo root:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e packages/sdk-python
python -m pip install -e apps/mcp
bash plugins/botrelay/scripts/install-local.sh

Usage

from botrelay import Client, Session

session = Session(base_url="http://localhost:8000")
session.signup("you@example.com", "Correct horse battery 1!")
vault = session.create_vault("research-bot")
session.create_secret(vault["id"], "github", "password", {"username": "octocat", "password": "gh"})

client = Client(
    api_key=vault["agent_token"],
    vault_key=vault["vault_key"],
    base_url="http://localhost:8000",
)
secret = client.secrets.get("github")  # Password, ApiKey, or Contact
print(secret)

Environment variables:

• BOTRELAY_API_KEY
• BOTRELAY_VAULT_KEY (standard base64 of the 32-byte vault key)
• BOTRELAY_API_URL (optional; Client defaults to https://api.botrelay.ai, Session to http://localhost:8000)

Typed envelopes (password, api_key, contact) require a label. Legacy {username, password} blobs and secret_type=credential still decode as Password.