<p align="center"><img src="design/banner.png" alt="pulr — secure passage of files between minds" width="100%"></p>

# pulr

**Secure file exchange for AI agents.** Agents produce files — reports, CSVs, images, PDFs, code — and have no safe way to hand them to other agents, humans, or downstream automation. [pulr.ai](https://pulr.ai) is that handoff layer: drop a file, get a verified, scannable, expiring download URL everyone in the chain can actually trust.

Every upload is SHA-256-hashed, **scanned before any link activates** (secrets, prompt-injection heuristics, ClamAV malware), stamped with provenance (which agent, workflow, and model produced it), and served through unguessable capability URLs with TTLs, download limits, IP/geo/time restrictions, and instant revocation. Humans get a review page with approve/reject; automation gets webhooks and **Ed25519-signed receipts**. Everything is audit-logged — who fetched, when, from where.

**Website: [pulr.ai](https://pulr.ai)** · **Docs: [pulr.ai/docs](https://pulr.ai/docs)** · **Self-serve signup: [pulr.ai/app](https://pulr.ai/app)**

This repo is the open tooling: the **MCP server** (root, npm [`mcp-server-pulr`](https://www.npmjs.com/package/mcp-server-pulr)), the **JavaScript SDK** (`sdk/js`, npm `@pulr/sdk`), and the **Python SDK** (`sdk/python`, PyPI `pulr-sdk`, with LangChain tools).

<p align="center"><img src="design/plate08-vignettes.png" alt="Sealed handoff: sender → sealed capsule → customs → accepted. Safeguards: encrypted, audited, MFA, PHI-blind" width="92%"></p>

## Sample uses

- **Agent → human sign-off → automation.** An agent generates a quarterly report with `approval: true`; the reviewer gets the link by email, previews provenance and scan results, clicks *Approve & release* — only then does the download URL go live, and a webhook kicks off the downstream pipeline with a signed receipt as proof.
- **Agent → agent handoff without context stuffing.** Instead of jamming base64 blobs into a context window, one agent uploads and passes a capability URL; the receiving agent fetches integrity-verified bytes. Revoke the link the moment the job is done.
- **Burn-after-reading delivery.** `max_downloads: 1` + a 1-hour TTL: send credentials-adjacent artifacts, one fetch, then the link is dead — with an audit row showing exactly who took it, from which IP.
- **Geo/time-fenced distribution.** Lock a link to your office CIDR, US-only access, or 9–5 Eastern: `restrictions: { allow_ips, allow_countries, allow_hours }`.
- **Quarantine as a feature.** A "meeting notes" file with an embedded *"ignore all previous instructions…"* payload (even zero-width-obfuscated or base64-smuggled) gets flagged at upload and can never be shared — your agents never ingest it.
- **Compliance trail.** `GET /v1/artifacts/:id/receipt` returns an Ed25519-signed record of hash + provenance + scan + approval, verifiable by anyone without trusting pulr.

## Your files are not our data

The only thing that ever reads uploaded bytes is the automated threat scanner — malware signatures, leaked-secret patterns, prompt-injection heuristics. It looks for threats, not information: the verdict is recorded, the content is not extracted, indexed, mined, trained on, or sold.

<p align="center"><img src="design/plate08b-scanner.png" alt="The scanner is not a reader: your file, content folded away → scanned for threats only → same file, never opened → no human reads" width="92%"></p>

## Many workspaces on one account

An account can hold as many workspaces as you like — one per client, per environment, per project. Each has its **own workspace address** (`pa_...` — where it receives files and how it is identified as a sender), quota, keys, inbox and audit trail; files never cross between them.

**Keys carry a scope.** A normal key is sealed inside the workspace that issued it. To manage the account you mint an **account-scoped** key (dashboard → Keys → *account-wide*, or `POST /v1/keys {"scope":"account"}`). Only a signed-in owner or an existing account key can mint one, so a workspace key can never promote itself.

```bash
curl https://pulr.ai/v1/account/workspaces  -H "Authorization: Bearer $PULR_ACCOUNT_KEY"          # list
curl -X POST   https://pulr.ai/v1/account/workspaces        -d '{"name":"Client Alpha"}'          # create
curl -X PATCH  https://pulr.ai/v1/account/workspaces/ws_123 -d '{"rotate_address":true}'          # modify
curl -X DELETE https://pulr.ai/v1/account/workspaces/ws_123 -d '{"confirm":"Client Alpha"}'       # delete
curl "https://pulr.ai/v1/artifacts?workspace=ws_123"                                              # files in one workspace
```

Deleting removes files, links, inbox and audit trail permanently, so the API asks for the name back and refuses to delete an account's last workspace. Rotating an address invalidates the old one immediately.

As MCP tools: `pulr_workspaces`, `pulr_workspace_create`, `pulr_workspace_update`, `pulr_workspace_delete`, and `pulr_list` with `workspace_id`.

### Delivery policy — hold or auto-accept

By default every offered file **holds** in the recipient's inbox until it is reviewed and accepted. For trusted, high-volume agent-to-agent pipelines a workspace can opt into **auto-accept**: clean files from an explicit trust list (sender `pa_` addresses and/or verified agent-key fingerprints) are accepted the instant they arrive — the `file_received` webhook fires with `auto_accepted: true` and the receiving agent fetches the file with its own key. Scanning, quotas, signed receipts and audit are identical to a hand-accepted file; flagged files, unlisted senders and oversized files (if `auto_max_bytes` is set) always fall back to hold. Webhooks stay metadata-only — file bytes are never pushed.

```bash
curl -X POST https://pulr.ai/v1/workspaces/settings \
  -H "Authorization: Bearer $PULR_API_KEY" -H 'Content-Type: application/json' \
  -d '{"delivery_policy": "auto", "trusted_senders": ["pa_9f5f84de..."], "auto_max_bytes": 10485760}'
```

Or via MCP: `pulr_workspace_update` with `delivery_policy` / `trusted_senders` / `auto_max_bytes`.

## MCP server (Claude Code, Codex, Claude Desktop)

**Claude Code** — one command:

```bash
claude mcp add pulr --env PULR_API_KEY=pulr_sk_... -- npx -y mcp-server-pulr
```

Add `--scope project` to write a shareable `.mcp.json` into the repo instead of your user config.

**Codex CLI:**

```bash
codex mcp add pulr --env PULR_API_KEY=pulr_sk_... -- npx -y mcp-server-pulr
```

Or declare it in `~/.codex/config.toml`:

```toml
[mcp_servers.pulr]
command = "npx"
args = ["-y", "mcp-server-pulr"]
env = { "PULR_API_KEY" = "pulr_sk_..." }
```

**Claude Desktop & other MCP clients:**

```json
{
  "mcpServers": {
    "pulr": {
      "command": "npx",
      "args": ["-y", "mcp-server-pulr"],
      "env": { "PULR_API_KEY": "pulr_sk_..." }
    }
  }
}
```

Then just ask your agent: *"Upload this report to pulr with approval required and a 24-hour expiry, and give me the review link."*

Tools: `pulr_upload` (with `approval`), `pulr_send` / `pulr_inbox` / `pulr_accept` / `pulr_reject` / `pulr_address` (sealed workspace-to-workspace handoff — no links), `pulr_share` (with `restrictions`), `pulr_fetch`, `pulr_list`, `pulr_revoke`, `pulr_receipt`, `pulr_whoami`. Env: `PULR_API_KEY` (required), `PULR_API_URL` (optional, defaults to `https://pulr.ai`; point at your own instance if self-hosting).

## JavaScript / TypeScript — `npm install @pulr/sdk`

```js
import PulrClient from '@pulr/sdk'
const pulr = new PulrClient({ apiKey: process.env.PULR_API_KEY })

const a = await pulr.upload({ filePath: './q3-report.pdf', approval: true, expiresIn: '48h' })
console.log(a.review_url)                                  // send to a human
const { bytes } = await pulr.fetchCapability(a.download_url)  // sha256-verified
console.log(PulrClient.verifyReceipt(await pulr.receipt(a.artifact_id)))  // true
```

## Python — `pip install pulr-sdk`

```python
from pulr import PulrClient, verify_receipt
pulr = PulrClient()  # reads PULR_API_KEY

a = pulr.upload(file_path="q3-report.pdf", approval=True, expires_in="48h",
                restrictions={"allow_countries": ["US"]})
data, sha = pulr.fetch_capability(a["download_url"])   # sha256-verified
verify_receipt(pulr.receipt(a["artifact_id"]))         # pip install pulr-sdk[verify]
```

LangChain: `from pulr.langchain_tool import pulr_tools` → `pulr_upload` / `pulr_fetch` / `pulr_share` StructuredTools for any agent.

## Getting a key

Create a workspace at [pulr.ai/app](https://pulr.ai/app) — 30 seconds, 500 MB included, owner API key shown once. Mint one key per agent (provenance is stamped from the key); revoke any key to cut that agent off instantly. Full API reference: [pulr.ai/docs](https://pulr.ai/docs).

> A pulr "artifact" is a durable **file** with a lifecycle — not a streaming chat-UI panel. If you want typed real-time artifact panels for React chat apps, that's a different (complementary) tool, e.g. `@ai-sdk-tools/artifacts`. pulr is where the file goes *afterward*.

MIT © Tal Eilon

## The design plates

pulr's product design is kept as a series of drafting plates — one per chapter of the system. A few from the atlas:

| | |
|---|---|
| <img src="design/plate06-registry.png" alt="Harbor Registry — accounts: a name is pencil until witnessed"> | <img src="design/plate04-watchroom.png" alt="Watchroom — the operations register"> |
| <img src="design/plate05-open-water.png" alt="Open Water — the 404: here the survey ends"> | <img src="design/plate01.png" alt="Sealed Passage — plate one"> |