Metadata-Version: 2.4
Name: botrelay
Version: 0.1.0
Summary: Zero-knowledge Python client for BotRelay agent vaults
Author: BotRelay
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://botrelay.ai
Project-URL: Documentation, https://github.com/chouseknecht/botrelay#readme
Project-URL: Repository, https://github.com/chouseknecht/botrelay
Keywords: botrelay,secrets,vault,zero-knowledge
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security :: Cryptography
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.28.0
Requires-Dist: pynacl>=1.5.0
Dynamic: license-file

# 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:

```bash
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`](../../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:

```bash
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

```python
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`.
