exbarboss/terminal-stash

•Updated about 1 month ago

Self-hosted shared clipboard & file drop. Terminal-themed, one static Go binary.

Image

938

exbarboss/terminal-stash repository overview

⁠Terminal Stash

A self-hosted shared clipboard and file drop for your own machines. Run the server on one always-on box; every other machine gets a one-line install. Drop text or a file on one machine, pick it up on any other, in a terminal or a browser, updating live.

A TUI and a web UI that match: a list of items with a preview pane
One-liner client install for macOS, Linux, and Windows, served by the server
Push the OS clipboard from any platform, screenshots included
Live sync over Server-Sent Events, so nothing needs a refresh
One shared token: browsers log in with it, clients send it as a Bearer token
Ships a Claude Code skill, so agents on any machine can use the stash
Terminal aesthetic with 8 phosphor themes
Persists across restarts (SQLite + a volume), with auto-pruning
One static Go binary, linux/amd64 + linux/arm64

Put it behind something. stash speaks plain HTTP and has a single shared secret: no TLS, no per-user accounts. Use it on a trusted LAN, or behind a reverse proxy / VPN / Cloudflare Tunnel that terminates HTTPS. A proxy must forward X-Forwarded-Proto (so the session cookie gets Secure) and X-Forwarded-For (so rate limiting and logs see real client IPs), and you must set TRUSTED_PROXIES to the number of hops in front.

⁠Quick start

docker run -d --name stash \
  -p 127.0.0.1:7827:7827 \
  -e STASH_TOKEN=something-only-you-know \
  -v stash-data:/data \
  exbarboss/terminal-stash:latest

# open http://localhost:7827 and log in with the token

-p 127.0.0.1:7827:7827 keeps it reachable only from the host (typically behind a reverse proxy or tunnel). For direct LAN access use -p 7827:7827.

⁠Connect a machine

The web UI's add machine button shows this with your URL and token already filled in:

curl -fsSL "http://<server>:7827/install.sh?token=<token>" | sh   # macOS / Linux
irm "http://<server>:7827/install.ps1?token=<token>" | iex        # Windows

That installs the stash binary and writes ~/.config/stash/config. After it, stash opens the TUI, stash push and stash pull move the OS clipboard, and stash put and stash get move files.

⁠Tags

Tag	Meaning
`latest`	Most recent release
`X.Y.Z` (e.g. `0.1.0`)	Exact release
`X.Y`, `X`	Latest patch / minor within that line

⁠Configuration

Variable	Default	Description
`STASH_TOKEN`	(required)	Shared secret. Browsers log in with it; the CLI and TUI send it as a `Bearer` token. The server refuses to start if unset.
`APP_USER`	`user`	Name shown in the UI's terminal prompt (`<name>@stash`).
`PORT`	`7827`	Listen port.
`DATA_DIR`	`/data`	Where the SQLite DB and uploaded files are stored.
`MAX_ITEMS`	`200`	Keep at most this many items; oldest are pruned. `0` = unlimited.
`MAX_AGE_DAYS`	`30`	Delete items older than this. `0` = never expire.
`MAX_UPLOAD_MB`	`200`	Reject uploads larger than this.
`MAX_REQUEST_MB`	`MAX_UPLOAD_MB × 4`	Ceiling for a whole upload request. The browser sends every selected file in one POST, so this must allow several at once; it is not the per-file limit.
`TRUSTED_PROXIES`	`0`	How many reverse proxies sit in front of the server. `0` ignores `X-Forwarded-For` and rate-limits on the socket peer, which a client cannot forge. Leave it at `0` if nothing is in front of you, or anyone can reset their own rate limit with a header.
`PROXY_MAX_MB`	`100`	Request-body ceiling of the proxy in front of the server, used only for a startup warning when `MAX_UPLOAD_MB` exceeds it. `0` disables the check.

⁠Notes

Sessions last 30 days and survive restarts: the cookie signing key is persisted under /data. Clients use Bearer auth, unaffected either way.
Failed logins and bad bearer tokens are rate-limited per client IP and logged.
Data lives in /data, so mount a volume or it goes with the container.

Source, issues, and docker-compose setup: github.com/eng1n88r/terminal-stash⁠ · MIT licensed

Tag summary

Recent tags

Content type

Image

Digest

sha256:5c2c0c5b0…

Size

35.1 MB

Last updated

about 1 month ago

docker pull exbarboss/terminal-stash