Perkoon — The Agent Data Layer

File transfer for humans and the things replacing them.

Your agent has compute, memory, and context. What it lacks is a jump gate to the physical world. Perkoon is that gate — P2P file transfer over WebRTC, engineered for autonomous machines from day one.

Not "AI-ready" the way a gas station is gourmet-ready. Actually built for machines — JSON event streams, structured exit codes, MCP native tools, an A2A protocol endpoint, and a state machine that doesn't need a browser, a mouse, or a soul.

Four integration methods — pick the one that fits your runtime:

Method	Best for	Install size
MCP Server	Coding agents (Claude Code, Cursor, Windsurf, VS Code Copilot)	~8 MB
CLI

Agents with shell access | ~8 MB |
| A2A Protocol | Agents with HTTP but no shell (ChatGPT, web agents) | Zero — just POST |
| Browser Automation | Full UI control via Playwright/Puppeteer | ~200 MB (Chromium) |

Three supported flight paths:

• - Agent → Human: Your agent sends a file. The human opens a link in any browser. No install on their end.
• Agent → Agent: CLI to CLI, MCP to MCP, or A2A to A2A. Two machines, no humans in the loop.
• Agent → Pipeline: Stream received files to stdout, pipe into processing. No disk writes required.

P2P transfers are free, unlimited, and encrypted. Both ends need to be online — that's the only constraint. For sensitive files, always use --password — without it, anyone with the share link can download.

---

METHOD 1: MCP Server (recommended for coding agents)

If your host supports MCP, this is the fastest path. Three native tools, zero shell commands.

Install: npx -y @perkoon/mcp@0.1.3 (stdio transport, pinned version)

Tools provided:

• - send_file — Send a file. Returns session code + share URL. Waits for receiver.
• INLINECODE3 — Receive files from a session code. Saves to disk.
• INLINECODE4 — Check if a session is active, expired, or not found.

Configuration for common hosts:

CODEBLOCK0

• - Claude Code: Add to .mcp.json in your project
• Claude Desktop: Add to INLINECODE6
• Cursor / VS Code / Windsurf: Settings → MCP → Add Server → INLINECODE7

Once configured, just call the tools directly — no bash, no log polling, no background processes.

---

METHOD 2: CLI (for agents with shell access)

IMPORTANT: Use npx -y perkoon@0.3.6 (pinned version) to avoid dynamic fetching of unaudited code.

SENDING a file

Step 1: Confirm the file path with the user, then start send

Before sending, confirm the file path and name with the user. Do not send files from sensitive directories without explicit user approval.

Replace /path/to/file with the actual file path:

CODEBLOCK1

Output: INLINECODE10

Once session_created appears, share the URL with the user. Example: "Here's your file — open this link on any device to download it: https://perkoon.com/K7MX4QPR9W2N"

The receiver doesn't need to install anything. The link works in any browser.

For password-protected sends, add --password SECRET and share both the URL and password.

Step 2: Monitor until complete — then REPORT BACK

You MUST run this after sharing the link. Do NOT skip this step.

CODEBLOCK2

• - ===TRANSFER COMPLETE=== → Tell the user: "File sent successfully!" Include speed and duration from the JSON.
• ===TRANSFER FAILED=== → Tell the user what went wrong.
• You MUST tell the user the outcome. Never finish silently.

SENDING into a pre-created session (Agent → Agent)

When another agent creates a session via A2A and gives you a session code + sender key:

CODEBLOCK3

Then monitor with the same Step 2 above. This joins an existing session as sender instead of creating a new one. The receiving agent runs npx -y perkoon@0.3.6 receive CODE --json on their end.

RECEIVING a file

Replace CODE with the 12-character session code:

CODEBLOCK4

For password-protected sessions, add --password SECRET.

• - ===TRANSFER COMPLETE=== → Tell the user: "File received!" and the save path.
• ===TRANSFER FAILED=== → Tell the user what went wrong.
• You MUST tell the user the outcome. Never finish silently.

Files are saved to /home/openclaw/.openclaw/workspace/received/.

Pipe to stdout

Stream a received file directly into another process — no disk write:

CODEBLOCK5

---

METHOD 3: A2A Protocol (for agents with HTTP, no shell)

If you can make HTTP requests but can't run shell commands, use the A2A endpoint directly.

Endpoint: POST https://perkoon.com/a2a
Protocol: JSON-RPC 2.0
Agent Card: INLINECODE22

Discover capabilities

CODEBLOCK6

Create a send session

CODEBLOCK7

Returns sender_url (for browser upload) + CLI commands + sender_key for A2A sender joining.

If you have shell access, run the CLI command from the response. If not, share the sender_url with your user — they open it in any browser to upload.

Join a session as receiver

CODEBLOCK8

Check session status

CODEBLOCK9

Runtime hints

Include clientCapabilities in your DataPart to get optimized instructions:

CODEBLOCK10

Agents declaring shell access get CLI commands. Web-only agents get browser URLs.

---

METHOD 4: Browser Automation (Playwright/Puppeteer)

For agents that need full browser UI control. Heavier than CLI but gives visual verification.

Ready-to-run scripts (requires npm install playwright):

CODEBLOCK11

Manual sender flow

1. 1. Navigate to https://perkoon.com/create, accept TOS, click Start
2. Skip confirmation modals: localStorage.setItem('perkoon_skip_confirm_direct-confirm', 'true') and INLINECODE30
3. Add files: INLINECODE31
4. Share session code with recipient
5. Wait for receiver: INLINECODE32
6. Click INLINECODE33
7. Wait: INLINECODE34

Manual receiver flow

1. 1. Register download handler: INLINECODE35
2. Navigate to INLINECODE36
3. Accept transfer: wait for [data-testid="transfer-accept"], click [data-testid="transfer-tos-checkbox"] if visible, then click INLINECODE39
4. Wait: INLINECODE40
5. Save: INLINECODE41

---

CLI reference

Flag	Description
INLINECODE42	Machine-readable JSON events (always use for automation)
INLINECODE43

Join an existing session as sender (A2A agent-to-agent) | | --sender-key <key> | Auth key for --session (provided by session creator) | | --password <pw> | End-to-end password protection | | --timeout <sec> | Peer wait time (default: 300, use 1800 for sends) | | --output <dir> | Save directory (default: ./received) | | --output - | Stream to stdout (no disk write) | | --overwrite | Replace existing files | | --quiet | Suppress human-readable output |

JSON event stream

Events appear in order on stdout when using --json:

Event	Meaning	Key fields
INLINECODE53	Ready — share the link now	INLINECODE54, INLINECODE55
INLINECODE56

Peer joined | |
| webrtc_connected | Direct P2P link established | |
| progress | Transfer in progress | percent, speed, eta |
| transfer_complete | Done | duration_ms, speed |
| error | Failed | message, exit_code |

Exit codes

Code	Meaning
0	Success
1

Bad arguments | | 2 | File not found | | 3 | Network/session error | | 4 | Wrong password | | 5 | Timeout — no peer joined |

Rules

1. 1. ALWAYS use --json for parseable output
2. ALWAYS confirm the file path with the user before sending
3. Once session_created appears, share the URL with the user
4. ALWAYS use --timeout 1800 for sends (30 min for the human to open the link)
5. ALWAYS use --overwrite for receives
6. ALWAYS monitor until transfer_complete or error — then tell the user the result
7. NEVER kill the process mid-transfer
8. The receiver does NOT need perkoon installed — the browser link works for everyone
9. Use pinned versions: npx -y perkoon@0.3.6 — never use INLINECODE75
10. NEVER send files from sensitive directories (~/.ssh, ~/.gnupg, /etc) without explicit user approval

Discovery endpoints

URL	What it is
INLINECODE76	A2A agent card (machine-readable capabilities)
INLINECODE77

Full agent integration guide | | https://perkoon.com/automate | Human-readable automation docs | | https://www.npmjs.com/package/@perkoon/mcp | MCP server package | | https://www.npmjs.com/package/perkoon | CLI package |