LAN-clipboard

中文说明

LAN-clipboard is a self-hosted local-network clipboard and file sharing service. It provides a browser-based shared workspace for text, screenshots, and files, plus the lcb command-line tool for configuration and PM2-backed service management.

The npm package name is @benryoung/lan-clipboard, and the CLI command is lcb.

Features

• Real-time text synchronization across devices on the same network.
• Paste images/files or drag files into the browser UI and store them in the server upload directory.
• Automatically show files that the server places directly in the upload directory.
• Image preview and file download from the shared file grid.
• Configurable upload directory, log directory, port, storage quota, and upload limit.
• Storage usage API and orphan-file cleanup.
• User-level configuration instead of hardcoded project paths.
• PM2 service lifecycle commands through the bundled CLI.

Install

npm install -g @benryoung/lan-clipboard

For local development from this repository:

npm install
npm link

Configure And Start

Create the default configuration:

lcb config init

config init writes a user-level configuration file, creates runtime directories, and writes the PM2 service configuration. In an interactive terminal it asks whether to start the service immediately.

Common non-interactive setup:

lcb config init --yes --port 8765
lcb service start
lcb service status

Then open:

http://localhost:8765
http://<server-ip>:8765

Uninstall

npm uninstall -g @benryoung/lan-clipboard

A running lcb service watches its package installation directory. After global uninstall removes the package files, the service exits with code 0; the PM2 configuration treats that exit code as a normal stop so the removed service is not restarted.

CLI Reference

lcb help
lcb --help
lcb --version
lcb doctor
lcb config path
lcb config get
lcb config set --port 8765 --uploads-dir ~/.local/share/lan-clipboard/uploads
lcb service start
lcb service status
lcb service status --json
lcb service logs --lines 20
lcb service restart
lcb service stop

Configuration

Default config path:

~/.config/lan-clipboard/config.json

Default runtime directories:

Uploads: ~/.local/share/lan-clipboard/uploads
Logs:    ~/.local/state/lan-clipboard/logs

Override the config path:

LCB_CONFIG=/path/to/config.json lcb service start
lcb service start --config /path/to/config.json

Useful configurable defaults:

Host:                 0.0.0.0
Port:                 8765
Upload limit:         10 GB
Storage limit:        30 GB
Socket.IO buffer:     200 MB
Cleanup interval:     1 hour
PM2 service name:     lan-clipboard
PM2 memory threshold: 2G

0.0.0.0 is the bind address. lcb config init and lcb service status also print the LAN access URL, such as http://<server-ip>:8765.

HTTP And Socket.IO Surface

• GET / serves the browser UI.
• GET /storage-status returns current storage usage and quota information.
• POST /upload uploads a file through multipart form data.
• POST /cleanup removes orphaned files that are no longer referenced by the current UI state.
• The upload directory is scanned at startup and watched for additions, updates, and removals while the service is running.
• Socket.IO events synchronize text, pasted files, upload-directory files, delete requests, settings, and storage updates.

Development

npm install
npm test
npm run pack:check

The test suite starts short-lived local servers on test ports and verifies the browser entry, storage API, upload/download flow, upload-directory sync, config commands, and foreground service mode.

Release Checks

Before publishing:

npm test
npm pack --dry-run
npm publish --dry-run --access public

The package uses package.json.files to keep the npm tarball limited to runtime files, public documentation, and referenced assets.

Security Notes

LAN-clipboard is designed for trusted local networks. It does not implement authentication or end-to-end encryption. Do not expose it directly to the public internet without adding an access-control layer such as a VPN, reverse proxy authentication, or firewall rules.

License

MIT