Skip to content

Deploy from Source ​

GCopy is a single Go binary with the frontend embedded — no separate frontend deployment needed.

Get the Binary ​

Build from Source ​

Prerequisites: Go 1.20+, Node.js 18.17+, git

bash
git clone https://github.com/llaoj/gcopy.git
cd gcopy
make bin/gcopy

Build process: compile Next.js frontend to static files → embed via go:embed → produce bin/gcopy

Download from Release ​

Download the binary for your platform from GitHub Releases.

Quick Start ​

The browser Clipboard API requires HTTPS. The following example uses a self-signed certificate:

bash
# 1. Generate a self-signed certificate
curl -sSL https://raw.githubusercontent.com/llaoj/gcopy/main/scripts/gen-cert.sh | bash

# 2. Start
./gcopy -app-key=<your-key> -tls-cert-file=cert.pem -tls-key-file=key.pem

Visit https://<host>:3375. The browser will warn about the self-signed certificate — proceed to continue.

You can also use a valid certificate or a reverse proxy for HTTPS. See HTTPS Configuration below.

Authentication ​

All configuration can be done via command-line flags or environment variables (with GCOPY_ prefix). Users authenticate with an 8-character token.

Rate Limiting ​

GCopy has no built-in rate limiting — it focuses on the core sync logic. If it is reachable by untrusted clients, apply traffic control at the edge (nginx limit_req, Istio, a sidecar, etc.), especially for POST /api/v1/user/token/generate, POST /api/v1/user/token/verify and POST /api/v1/clipboard.

HTTPS Configuration ​

The browser Clipboard API requires HTTPS. You must configure HTTPS for GCopy to work.

Self-Signed Certificate (Quick Test) ​

bash
curl -sSL https://raw.githubusercontent.com/llaoj/gcopy/main/scripts/gen-cert.sh | bash

Use this script to generate a local self-signed certificate. The browser will warn about the certificate — proceed to continue.

Alternatively, for production, it is recommended to obtain a valid certificate for your domain, then:

Domain Certificate ​

bash
...
-tls-cert-file=/path/to/cert.pem \
-tls-key-file=/path/to/key.pem

With a certificate configured, GCopy serves HTTPS directly — no reverse proxy needed.

Reverse Proxy ​

Run GCopy with HTTP and let a reverse proxy (Nginx, Caddy, etc.) handle TLS:

bash
...
-listen=127.0.0.1:3375

Configure the reverse proxy to forward HTTPS traffic to port 3375.

Configuration Reference ​

FlagEnvironment VariableDefaultDescription
-app-keyGCOPY_APP_KEY-Encryption key (min 16 characters, required)
-listenGCOPY_LISTEN:3375Listen address
-tls-cert-fileGCOPY_TLS_CERT_FILE-TLS certificate file
-tls-key-fileGCOPY_TLS_KEY_FILE-TLS key file
-max-content-lengthGCOPY_MAX_CONTENT_LENGTH10Max clipboard size (MiB)
-debugGCOPY_DEBUGfalseDebug mode
-version-falsePrint version

Development ​

For development with hot-reload, use scripts/dev.sh which starts the frontend and backend as separate processes:

bash
./scripts/dev.sh
  • Frontend: https://localhost:3375 (Next.js dev server with HTTPS)
  • Backend: https://localhost:3376 (Go server with TLS)

Released under the MIT License.