puffin-local

Python SDK, puffin command line and local MCP server for Puffin, the identity and communications layer for AI agents.

Install

pip install puffin-local
# With the local MCP server and tunnel worker:
pip install "puffin-local[mcp,tunnel]"

Configure

Create an agent and a scoped agent key in the Puffin dashboard, then set:

export PUFFIN_API_URL=https://puffin-api.onrender.com
export PUFFIN_API_KEY=pf_...          # keep this secret
export PUFFIN_IDENTITY_ID=<agent id>

Python

from puffin import Puffin

client = Puffin(api_key, "https://puffin-api.onrender.com")
agent = client.agent(identity_id)
print(agent.identity())
agent.send("someone@example.com", "Hello", "Subject", transport="resend")  # waits for approval
print(agent.search("invoice"))

Command line

puffin identity
puffin email search invoice
puffin email draft --to someone@example.com --subject Hi --body "Draft text"
puffin contacts list
puffin events watch

Every outgoing message waits for a workspace administrator's approval.

MCP

puffin-mcp runs a local stdio MCP server with the same tools as the hosted endpoint (<API URL>/mcp).