Welcome aboard, automaton.

Install

$ npm install -g perkoon

Or run without installing:

$ npx perkoon send file.zip

Requires Node.js >= 18

Send

$ perkoon send report.pdf

  ✓ report.pdf (2.5 MB)
  ✓ Code: K7MX4QPR9W2N

  Receiver command:   perkoon receive K7MX4QPR9W2N
  Or open in browser: https://perkoon.com/K7MX4QPR9W2N

  Waiting for receiver...
  ✓ Receiver connected
  ✓ Direct connection established

  ██████████████████████████████ 100%     8.3 MB/s  ETA 0s
  ✓ Complete: 2.5 MB in 0.3s (8.3 MB/s)

The receiver can use the CLI or just open the link in any browser. Their choice.

Receive

$ perkoon receive K7MX4QPR9W2N

  ✓ Joined session K7MX4QPR9W2N
  ✓ Sender found
  ✓ Direct connection established
  ✓ Receiving: report.pdf (2.5 MB)

  ██████████████████████████████ 100%     8.3 MB/s  ETA 0s
  ✓ Saved: ./received/report.pdf
  ✓ Complete: 0.3s (8.3 MB/s)

Options

JSON Mode

For automation and AI agents. --json outputs structured events to stdout, one JSON object per line.

$ perkoon send file.zip --json --quiet

{"event":"file_ready","name":"file.zip","size":1048576}
{"event":"session_created","session_code":"K7MX4QPR9W2N","share_url":"https://perkoon.com/K7MX4QPR9W2N"}
{"event":"waiting_for_receiver"}
{"event":"receiver_connected"}
{"event":"webrtc_connected"}
{"event":"progress","percent":50,"speed":8500000,"eta":3}
{"event":"transfer_complete","duration_ms":2100,"speed":8500000}

Event Reference (send flow)

The receive flow emits a different sequence: session_joined, sender_found, webrtc_connected, receiving_file, progress, transfer_complete. Parse for these (not the send events above) when driving perkoon receive.

Exit Codes

Rate limits: session creation via /api/v1/sessions is capped at 10/min per IP (joins 30/min, status 20/min). A 429 surfaces here as a fast exit 3 before session_created — back off ~30s and retry (see the rate-limit note in the A2A section for the full policy).

Packages & Skills

Published and ready to wire into your stack.

Protocol 01: Send Payload

Playwright/Puppeteer. Six steps. Chromium included.

// 1. Warm the browser context — load home so we have a session cookie and
//    can read the CSRF token. /create is in Phoenix's protect_from_forgery
//    pipeline; without _csrf_token it returns 403.
await page.goto('https://perkoon.com/');
const csrf = await page.locator('meta[name="csrf-token"]').getAttribute('content');

// 2. Create session via POST — auto-accepts TOS for agent_browser source
const res = await page.context().request.post(
  'https://perkoon.com/create',
  {
    form: {
      _csrf_token: csrf,
      'session[tos_accepted]': 'true',
      'session[source]': 'agent_browser'
    },
    maxRedirects: 0
  }
);
const code = res.headers()['location'].slice(1); // drop leading /

// 3. Open the session URL — agent flag identifies us in the participant list
await page.goto(`https://perkoon.com/${code}?agent=true`);
await page.waitForSelector('[data-testid="p2p-session"]');
// Wait for the WebSocket-backed LiveView to fully connect, otherwise the
// NativeFileInput hook's pushEventTo silently drops add_files.
await page.waitForFunction(() => window.liveSocket?.isConnected());

// 3. Add files via the file input
await page.setInputFiles('[data-testid="file-input"]', '/path/to/file.zip');

// 4. Share the code with recipient (your problem, not ours)

// 5. Click Send to start the transfer
await page.click('[data-testid="send-transfer"]');

// 6. Wait for completion via window.__perkoon
await page.waitForFunction(
  () => window.__perkoon?.transfer?.status === 'complete',
  null,
  { timeout: 600000 }
);

Protocol 02: Receive Payload

Even simpler. Dock, wait, collect.

// 1. Join the session — `?agent=true` picks the right sink by file size:
//    file ≤ OPFS quota (~60-80% disk) → OPFS
//    file > quota but ≤ free disk     → Service Worker download
//    file > free disk                 → fail loud (use Cloud Relay)
await page.goto(`https://perkoon.com/${sessionCode}?agent=true`);

// 2. Click the incoming-transfer Accept button. It appears once the
//    sender's offer arrives. This is the RECEIVE-side accept — distinct
//    from the sender's session-creation gate [data-testid="tos-accept"].
//    (Reject is [data-testid="transfer-reject"].)
await page.locator('[data-testid="transfer-accept"]')
  .waitFor({ state: 'visible', timeout: 300000 });
await page.click('[data-testid="transfer-accept"]');

// 4. Wait for per-file readiness
await page.waitForFunction(
  (n) => (window.__perkoon?.files?.length ?? 0) >= n,
  expectedFileCount,
  { timeout: 600000 }
);

// 5. Read bytes via the SINK-AGNOSTIC stream() accessor.
// Works at any size — no V8 ~2GB ArrayBuffer ceiling, no Playwright
// download-event coupling. Same code for 1KB or 100TB.
const agentSink = new Map();   // transferId → fs.WriteStream (your code)
await page.exposeFunction('__perkoonChunk', (transferId, name, b64) => {
  let w = agentSink.get(transferId);
  if (!w) { w = fs.createWriteStream(`./received/${name}`); agentSink.set(transferId, w); }
  w.write(Buffer.from(b64, 'base64'));
});

await page.evaluate(async (n) => {
  for (let i = 0; i < n; i++) {
    const f = window.__perkoon.files[i];
    if (!f.stream) continue;   // FSAPI direct-to-disk, no programmatic re-read
    const rs = await f.stream();
    if (!rs) continue;   // handle cleaned up before we read it
    const reader = rs.getReader();
    while (true) {
      const { done, value } = await reader.read();
      if (done) break;
      // chunked base64 to avoid building one giant string
      let bin = '';
      for (let j = 0; j < value.length; j += 0x8000)
        bin += String.fromCharCode.apply(null, value.subarray(j, j + 0x8000));
      await window.__perkoonChunk(f.transferId, f.name, btoa(bin));
    }
    f.release?.();   // free OPFS storage early
  }
}, expectedFileCount);

// 6. Listen for failures. INSUFFICIENT_STORAGE → ask sender for Cloud Relay (A2A).
page.on('console', msg => {/* perkoon:file:error events surface here */});

Grab & Go

Complete scripts. Copy, paste, run. No assembly required. Downloads include error handling and PERKOON_URL env var for local dev.

npm install playwright