clipbox

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

Features

• Named buffers -- create multiple independent text buffers
• File sharing -- upload and download files alongside the 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
• One-line client setup -- the server hands out its own cb and fb shell helpers
• 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

Filenames are kept as sent -- spaces, accents, emoji and macOS screenshot names all round-trip. Uploads are stored under an opaque name on disk, so nothing in a filename can reach the filesystem.

Install

Requires Python 3.14+. Use uv.

Usage

uvx clipbox

OR

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.

Shell helpers

cb and fb wrap the API as shell commands, with tab completion and an interactive picker. The running server hands them out, so on any machine that can reach it:

curl -fsSL http://host:port/cli | sh

The server fills in its own address, so CB_HOST is already set correctly -- there is nothing to configure. The installer detects your shell, writes the helpers to ~/.local/share/clipbox/, adds a marked block to your .bashrc or .zshrc, and picks a clipboard command for your platform. It touches nothing outside your home directory and needs no sudo. Re-running it replaces the block rather than duplicating it, and leaves your settings alone.

curl -fsSL http://host:port/cli | sh -s -- --print-only   # don't edit any rc file
curl -fsSL http://host:port/cli | sh -s -- --uninstall    # remove it again
curl -fsSL http://host:port/cli | sh -s -- --help         # all options

If you would rather nothing the server sends gets executed, fetch the helpers directly and source them yourself -- the address is baked into this file too:

mkdir -p ~/.local/share/clipbox
curl -fsSL http://host:port/cli/shell.sh -o ~/.local/share/clipbox/clipbox.sh
echo '. ~/.local/share/clipbox/clipbox.sh' >> ~/.bashrc

On zsh, bash-style completion needs to be enabled first; the installer writes this for you, but add it yourself if you are sourcing manually:

autoload -Uz compinit bashcompinit
(( $+functions[compdef] )) || compinit
bashcompinit

Commands

cb copy [name]           Copy a buffer to the clipboard (omit name to pick one)
cb paste [content]       Write a new buffer, or read stdin
cb rename <name> <new>   Rename a buffer
cb delete [name]         Delete a buffer

fb send [--overwrite] <file>...
                         Upload files. A name that is already taken
                         prompts to overwrite or keep both;
                         --overwrite answers that up front
fb get [name...]         Download files (omit names to pick; TAB selects several)
fb delete [name...]      Delete files (omit names to pick; TAB selects several)

Settings

Your settings live in ~/.config/clipbox/config.sh, which the installer creates once and never overwrites:

export CB_HOST=http://host:port
export CB_COPY_CMD='pbcopy'   # wl-copy on Wayland, xclip -selection clipboard on X11

jq is required. fzf is optional -- without it the pickers fall back to a numbered list.

curl

Clipboard operations

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)

File Operations

curl -F 'file=@photo.jpg' http://host:port/files/   # upload a file
curl -F 'file=@photo.jpg' 'http://host:port/files/?overwrite=1'  # replace one
curl http://host:port/files/filename                # download a file
curl -X DELETE http://host:port/files/filename      # delete a file
curl http://host:port/api/files                     # list all files (JSON)

Environment variables

Data storage

The database is stored in the platform-appropriate data directory by default, with uploaded files in a files/ subdirectory next to it:

Override with the CLIPBOX_DB environment variable.

Development

uv sync                 # install, or `uv lock --upgrade && uv sync` to refresh
make test               # Python test suite
./tests/test_shell.sh   # cb/fb integration tests (starts its own server)
./tests/test_install.sh # installer tests (installs into a sandboxed HOME)
make check              # lint and type-check
make format             # apply formatting

The browser tests need playwright install chromium; they skip cleanly without it, so make test works either way.