# clipbox

A self-hosted shared clipboard for copying text between devices on your local network.

## Features

- **Named buffers** -- create multiple independent text buffers
- **Auto-save** -- changes save automatically as you type, with a status indicator
- **Copy button** -- one-tap copy on both desktop and mobile
- **curl-friendly** -- read, write, and delete buffers from the terminal
- **Mobile-friendly** -- responsive UI that works on phones and tablets, installable as a PWA
- **SQLite storage** -- persistent, zero-config database stored in the platform-appropriate data directory

## Install

Requires Python 3.14+. Use [uv](https://docs.astral.sh/uv/).

## Usage

```sh
uvx clipbox
```

_OR_

```sh
uvx clipbox --host 0.0.0.0 --port 8080
```

This starts the server on `http://0.0.0.0:8080`. Open it in a browser from any device on your network.

### curl

```sh
curl http://host:port/my-buffer                         # read a buffer
curl -X PUT -d 'text' http://host:port/my-buffer        # write to a buffer
curl -X PATCH -d 'new-name' http://host:port/my-buffer  # rename a buffer
curl -X DELETE http://host:port/my-buffer               # delete a buffer
curl http://host:port/api/buffers                       # list all buffers (JSON)
```

### Environment variables

| Variable     | Default       | Description                      |
| ------------ | ------------- | -------------------------------- |
| `CLIPBOX_DB` | _(see below)_ | Path to the SQLite database file |

### Data storage

The database is stored in the platform-appropriate data directory by default:

| Platform | Path                                               |
| -------- | -------------------------------------------------- |
| Linux    | `~/.local/share/clipbox/clipbox.db`                |
| macOS    | `~/Library/Application Support/clipbox/clipbox.db` |
| Windows  | `%LOCALAPPDATA%\clipbox\clipbox.db`                |

Override with the `CLIPBOX_DB` environment variable.
