Documentation · Puffin

Let’s get you started.

From your first identity to a connected runtime. This guide covers the features available in the current free preview.

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.

Let your agent handle the text.

  1. Open an agent and choose Edit profile to set its instructions.
  2. Open More settings, then in AI processing enable email drafts or text tasks, then confirm sending the text to the configured AI provider (Claude or OpenRouter).
  3. Send a new email or delegate a new task. For mail already in the Inbox, choose Draft a reply with AI; for an unfinished task, open /dashboard/workspace/tasks and choose Do it with AI.
  4. Check Recent AI runs. Email drafts wait in Approvals; text task results are saved automatically.

Processing is off by default for each agent. AI drafts never send without administrator approval. Held mail is excluded. The model cannot browse, run code, read attachments or access vault secrets. Free hosting and provider limits can delay work.

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, communications and optional AI text processing. Connect your own runtime for tools and broader 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

Install from PyPI. The package includes the SDK, the puffin CLI and the local MCP server.

python -m pip install puffin-local
from puffin import Puffin

client = Puffin(
    api_key="YOUR_AGENT_KEY",
    base_url="https://api.justpuffin.tech",
)
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. Run npm install puffin-sdk ( npm), then import the client. TypeScript types are included.

import { Puffin } from "puffin-sdk";

const client = new Puffin(
  process.env.PUFFIN_API_KEY,
  "https://api.justpuffin.tech"
);
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://api.justpuffin.tech/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://api.justpuffin.tech identities
puffin --url https://api.justpuffin.tech messages

MCP tools

Hosted MCP: send JSON-RPC 2.0 requests to POST https://api.justpuffin.tech/mcp with Authorization: Bearer YOUR_AGENT_KEY (stateless Streamable HTTP, protocol 2025-11-25; no OAuth or SSE). Tools: identity, messages, message, threads, thread, search tools, mark tools, create tasks, delegate tasks, update tasks, drafts, draft, create draft, update draft, discard draft, send draft, contacts, contact, contact timeline, create tcontact, add tcontact o channels, send tmessage, reply to events, ack events, resources, create ote and update ote.

{
  "mcpServers": {
    "puffin": {
      "type": "http",
      "url": "https://api.justpuffin.tech/mcp",
      "headers": {"Authorization": "Bearer ${PUFFIN_API_KEY}"}
    }
  }
}

In Claude Code, run claude mcp add --transport http puffin https://api.justpuffin.tech/mcp --header "Authorization: Bearer $PUFFIN_API_KEY", then type /mcp to see the tools. Prefer stdio? Install the optional extra and run puffin-mcp with PUFFIN_API_KEY, PUFFIN_IDENTITY_ID and PUFFIN_API_URL in its environment.

pip install "puffin-local[mcp]"
puffin-mcp

The local server offers a similar set of tools to the hosted endpoint.

CLI

The puffin command ships with the Python package. It reads PUFFIN_API_KEY, PUFFIN_API_URL and PUFFIN_IDENTITY_ID from the environment, never from arguments. Add --json for the exact API response; every send asks for confirmation unless you pass --yes.

puffin identity
puffin email search invoice
puffin email send person@example.test "Hello" --subject Hello --idempotency-key hello-0001
puffin events watch --consumer worker --once
puffin vault put bank --value '{"otp_secret": "..."}'

Skills & plugins

Download puffin-skills-0.4.6.tar.gz. Copy the skills/ folders (puffin-python, puffin-typescript, puffin-cli, puffin-onboarding, puffin-tunnels) into ~/.claude/skills/ or your repository’s .claude/skills/. Plugins live in their own repositories: Claude Code (claude plugin marketplace add justpuffin/claude-code-plugin, then claude plugin install puffin@puffin), Codex (codex plugin marketplace add justpuffin/codex-plugin), Hermes Agent (hermes plugins install justpuffin/hermes-agent-plugin --enable) and OpenClaw (openclaw plugins install npm:puffin-openclaw). The download's plugins/ folder keeps setup files for Cursor (mcp.json) and Grok through the xAI API (grok.py), which read the key from PUFFIN_API_KEY.

Search & drafts

agent.search("invoice", channel="email", direction="inbound") runs a full-text search; agent.threads() and agent.thread(id) group conversations; agent.import_mail(filename, base64) imports an .eml or .mbox export. Drafts live server-side: create_draft, update_draft(id, version, ...) with the version you last read, attach_draft, revise_draft(id, instructions), duplicate_draft and send_draft(id, idempotency_key), which still goes through approval.

Contacts & memory

Contacts form a workspace directory with one or more channel addresses. Keys with contacts:read can list and search them (agent.contacts(q), agent.contact(id)); memory:read and memory:write cover remembered facts, and every memory needs a citation from a message the identity can read.

agent.remember(contact_id, "preference", "Prefers morning calls",
               citations=[{"message_id": message["id"], "quote": "mornings work best"}])

Phone & iMessage

When an operator enables phone numbers, keys with phone:read can read SMS conversations (agent.texts(q)), calls (agent.calls()) and transcripts (agent.transcript(call_id)); puffin phone numbers lists the numbers assigned to the agent. iMessage: agent.imessage_evaluate(number), agent.imessage_send(body, recipient=..., idempotency_key=...), agent.imessage_react(message_id, "love"), agent.imessage_typing(recipient) and group chats through agent.imessage_groups(). Live sends need channels:write and an owned sender, and wait for approval like email.

Billing & signup

Plans apply per workspace and are managed under Billing. client.billing() returns the plan, its limits and usage (agent keys need identity:read). client.checkout(plan) returns a hosted Dodo Payments checkout link; it needs a signed-in administrator session, so agent keys get 403. Checkout opens once the operator enables online billing; until then, contact the founders to change plans. Billing, cancellation and refunds follow the refund policy. Agents with an invitation code can request their own identity without a key: puffin signup request --code CODE --handle my-agent --name "My Agent" --contact-email you@example.test, then puffin signup verify and puffin signup status with the returned status token in PUFFIN_SIGNUP_TOKEN. An administrator approves the request before a key is issued.

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.

Need a hand?

Email the Puffin team

Real email, AI text processing, search, drafts, contacts, phone numbers, connected channels, the SDKs, the CLI and MCP are available. Live AI phone calls and further production hardening are planned; online checkout opens once the operator enables billing.