Clippy

A web-based application that allows users to share text and files in real-time through secure, encrypted sessions.

台灣繁體中文 請按這

---

Table of Contents 📖

• Features ✨
• Screenshots 📸
• Usage 🚀
  • Installation ⚙️
  • Setting the Rate Limit 🕒
  • Changing the Default Port 🔌
• Build It Yourself 🛠
  • File Structure 🗄
  • Prerequisites ✅
  • Building 🚧
• Notes 📝
  • Known Bugs 🐛
• Issues / Bugs? 🙋‍♀️

---

Features ✨

Tired of sharing text / files across different computers? Try this clippy!

• Session-based sharing: Create or join sessions using short, custom-length IDs
• Encrypted payloads: Each session uses a 256-bit AES-GCM key derived client-side from the connection ID (SHA-256 KDF). All block content is encrypted before it leaves the browser, so the backend only ever sees ciphertext. The server issues the ID and could derive the key too — this is encrypted-at-rest and on-the-wire, not strict end-to-end against a malicious server
• Real-time collaboration: See blocks appear instantly when other users create them
• File uploads: Support for small file uploads
• User management:
  • Custom or random user names
  • Host can transfer host rights to other users
  • Host can control whether new users can join
• Session persistence: Sessions remain active until destroyed by host or after 1 hour of inactivity
• Block system: Add and delete text or file blocks, similar to Jupyter notebooks

---

Screenshots 📸

---

Usage 🚀

Installation ⚙️

1. Download the release ZIP file from the release page. To build it yourself, please refer to Build It Yourself.
2. Unzip the file.
3. Run the setup script:

   bash setup.sh
   
   # If Docker requires root permission
   sudo bash setup.sh

4. Follow the prompts to enter variables and parameters.
5. You're all set!

Setting the Rate Limit 🕒

The rate limit is set in nginx. Default setting allows 10 requests per minute. You can modify the limit in docker/nginx/nginx.conf.

Changing the Default Port 🔌

By default, the web service runs on port 8080. To change it, edit the .env file of the project root.

---

Build It Yourself 🛠

File Structure 🗄

Source Code 🧑‍💻

• Frontend: Built using Vite, located in the frontend folder.
• Backend: Built using Python FastAPI, located in the backend folder.

Docker 🐳

• docker/frontend: Contains built frontend files.
• docker/backend: Contains Python backend files.
• docker/nginx: Contains Nginx default.conf.

Prerequisites ✅

Recommended:

1. Node >= 22.20.0
2. Python >= 3.12

Building 🚧

Frontend 🌐

1. Navigate to the frontend folder.
2. Install dependencies:

   npm install

3. (Optional) Modify the code as you wish.
4. (Optional) Vite can be executed in development mode:

   npm run dev

5. Build the frontend:

   npm run build

6. Copy the files under dist folder to docker/frontend/.

Backend 👨‍🔧

The FastAPI documentation is in https://example.com/api/v1/docs.

The passphrase and salt is stored in the docker/backend/.env file.

If you want to modify the backend, follow these steps. Otherwise, copy the contents of backend to docker/.

1. Navigate to the backend folder.
2. (Optional) Create a virtual environment: By using venv

   python -m venv .venv

   OR by using uv

   uv venv

3. (Skip if not using a virtual environment) Activate the virtual environment:

    source .venv/bin/activate

4. Install dependencies:

   pip install -r requirements.txt

   OR by using uv

   uv sync

5. Modify the code as you wish.
6. Run the backend in development mode:

   python app.py

7. Copy the files under backend folder to docker/backend/.

Note that you might want to change ALLOWED_ORIGINS of python .env to * when developing.

---

Notes 📝

Known Bugs 🐛

• Destroying the session might not directly take you back to homepage.

---

Issues / Bugs? 🙋‍♀️

Encounter issues or bugs? Feel free to report them in Issues and submit Pull Requests, please open an issue before typing to do pr.