---
name: clipboard-bin
description: Spin up a tiny local server that exposes your macOS clipboard as a plain-text URL. Useful for sharing code/text quickly with another device on the same network or via tunnel (cloudflared, ngrok). Optional history mode (last N clipboards), optional write-back mode (PUT to set clipboard). Pure stdlib http.server. Use when the user asks to "share my clipboard", "expose pasteboard", "quick paste server", or needs a fast way to get text from their Mac to another device without sending a message.
---


# clipboard-bin

Tiny local pastebin that mirrors your macOS clipboard (`pbpaste`) and serves it as plain text on `GET /`. Pure Python stdlib — no Flask, no pip, no daemon.

## Usage

```bash
python3 scripts/bin.py
# → Serving clipboard at http://127.0.0.1:8765
```

Then on any other device:

```bash
curl http://127.0.0.1:8765/        # current clipboard as plain text
```

To make it reachable from your phone or another machine, pair it with a tunnel:

```bash
# in another terminal
cloudflared tunnel --url http://127.0.0.1:8765
# → https://random-name.trycloudflare.com
```

## Flags

| Flag | Default | Meaning |
|---|---|---|
| `--port` | `8765` | TCP port to bind |
| `--host` | `127.0.0.1` | Bind address. Use `0.0.0.0` to expose on LAN (opt-in) |
| `--history N` | `10` | Keep the last N distinct clipboard snapshots (poll every 2s) |
| `--write` | off | Allow `PUT /` to set clipboard from request body via `pbcopy` |
| `--token TOKEN` | none | Require `Authorization: Bearer TOKEN` header on every request |

## Endpoints

- `GET /` — current clipboard as `text/plain; charset=utf-8`
- `GET /history` — JSON list of the last N distinct clipboards, newest first
- `PUT /` — (only with `--write`) sets clipboard from raw request body
- `GET /health` — `ok`

## Examples

LAN mode with auth and write-back:

```bash
python3 scripts/bin.py --host 0.0.0.0 --port 8765 --write --token sup3rsecret
```

Read from another device:

```bash
curl -H "Authorization: Bearer sup3rsecret" http://192.168.1.10:8765/
```

Push text back to your Mac's clipboard:

```bash
echo "hello from phone" | curl -X PUT --data-binary @- \
  -H "Authorization: Bearer sup3rsecret" \
  http://192.168.1.10:8765/
```

History (last 10 distinct clipboards):

```bash
curl http://127.0.0.1:8765/history | jq
```

## Security note

By default the server binds to `127.0.0.1` only — nothing leaves your Mac. To expose on LAN you must pass `--host 0.0.0.0`, and you should always pair that with `--token`. Anything in your clipboard (passwords, tokens, secrets) becomes available to anyone who can reach the port. Don't run `--host 0.0.0.0` on untrusted networks (cafe wifi, conferences). For remote use over a tunnel, prefer `127.0.0.1` + `cloudflared` so the tunnel handles TLS.

Stop with `Ctrl-C`.