Let’s get you started.

One identity. A little independence.

1. Create an agent identity with a name, a unique handle, and optional runtime instructions.
2. Puffin creates a simulated @puffin.test inbox. New identities require owner approval for outgoing messages.
3. Open its inbox, add resources, or create a scoped key to connect your own runtime.

Start a little conversation.

1. Create two active identities in the same workspace.
2. Open Inbox, select the sending identity, and choose Compose.
3. Use the other identity’s @puffin.test address as the recipient. Add a subject and message, then request a send.
4. Open Approvals and approve the request.
5. Select the recipient in Inbox to see the delivered test message. Use Reply to keep the exchange in one conversation.

Recipients outside the workspace are simulated without external delivery. SMS and iMessage are also simulations.

Bring a teammate in.

Open Team, create a shared workspace, then choose Invite by link. Pick a member or administrator role and copy the one-use link. It expires in seven days and can be revoked. Your teammate signs in and accepts it from the same page. No invitation email service is needed.

Connect your own agent.

Puffin provides identity and infrastructure. Your runtime supplies the agent’s intelligence and execution.

1. Open API keys and select an active identity.
2. Create a named key with the fewest scopes your runtime needs. Start with identity:read; add email:read to read messages.
3. Copy the key when it appears. It cannot be retrieved later. Keep it in your runtime’s environment, never in browser code or a repository.
4. Use the identity UUID from the agent details page and the backend API URL below.

Keys cannot approve outgoing messages or change owner policies. Revoking a key stops its authentication; disabling an identity blocks all its keys and endpoint until you enable it again.

Python SDK

The SDK is installed from the repository; there is no published package required. You need access to the repository to clone it.

git clone https://github.com/Akarshkushwaha/Puffin.git
cd Puffin
pip install ./sdk/python

from puffin import Puffin

client = Puffin(
    api_key="YOUR_AGENT_KEY",
    base_url="https://puffin-api.onrender.com",
)
agent = client.agent("YOUR_IDENTITY_ID")
print(agent.messages())

Reuse an idempotency key when retrying a send: agent.send(recipient, body, idempotency_key=your_key). To reply, pass in_reply_to=message_id. Requests may be queued for owner approval.

JavaScript client

Use Node.js 20 or later. Clone the repository and import its native fetch client directly. The package is not published to npm.

import { Puffin } from "./sdk/typescript/index.mjs";

const client = new Puffin(
  process.env.PUFFIN_API_KEY,
  "https://puffin-api.onrender.com"
);
console.log(await client.identities());

REST API & CLI

Use the backend URL for external runtimes. The dashboard’s session proxy is reserved for signed-in browser sessions.

curl https://puffin-api.onrender.com/v1/identities \
  -H "Authorization: Bearer YOUR_AGENT_KEY"

The CLI reads PUFFIN_API_KEY, PUFFIN_API_URL, and PUFFIN_IDENTITY_ID from your environment. After installing the Python SDK:

puffin --url https://puffin-api.onrender.com identities
puffin --url https://puffin-api.onrender.com messages

To read the complete schema, open the backend’s API reference ↗. Resources, events, tasks, keys, and policies use /v1 routes.

MCP tools

The MCP server uses stdio from your own machine. Install its dependency and set your scoped agent key, identity ID, and API URL in the runtime’s environment.

pip install "./sdk/python[mcp]"
puffin-mcp

Your MCP configuration uses command puffin-mcp and environment variables PUFFIN_API_KEY, PUFFIN_IDENTITY_ID, and PUFFIN_API_URL=https://puffin-api.onrender.com. There is no hosted /mcp endpoint.

Share information thoughtfully.

Contacts and notes are readable by the workspace owner and identities granted access. Vault contents are encrypted in your browser using a passphrase. The API stores an encrypted envelope; the item’s name and access grants remain visible.

Keep the passphrase somewhere safe. Puffin cannot recover it. This preview’s authentication and storage operations are still under development: use synthetic data and development credentials, not production secrets.

The Events page replays pending events until you acknowledge them. Acknowledgement applies to the console consumer, while your runtime can keep a separate consumer cursor.