croc-desktop

Send files and text between devices — simply, privately, and without the cloud.

A friendly app for croc: end-to-end encrypted, peer-to-peer transfer.
Desktop: Linux · macOS · Windows · Mobile: iOS · Android
_{Built with Wails v3 (not v2)}

Install desktop · Mobile · How to use · Features · FAQ · Contributing · Development

Why croc-desktop?

Moving a file to another computer should not mean uploading it to someone else’s servers — or learning a command line.

croc-desktop is a full GUI for croc:


Private by default	End-to-end encrypted, peer-to-peer. Nothing is stored in the cloud.
One code (or QR)	Share a short phrase or scan a QR — done.
You stay in control	Accept or decline each transfer. Overwrite and resume when you choose.
Works with the CLI	Codes are the same as `croc` on the command line. Mix and match devices.
No terminal required	Point, click, drop, paste.

Unlike thin wrappers that only launch the croc CLI in a window, this app runs croc inside the process, so you get real dialogs, live progress, history, and relay hosting.

Stack note: this project uses Wails v3 (github.com/wailsapp/wails/v3). Older docs or the main branch may still mention Wails v2 — that is obsolete here.

Install (desktop)

One-line install

Linux / macOS:

curl -fsSL https://raw.githubusercontent.com/SihanTeng/croc-desktop/main/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/SihanTeng/croc-desktop/main/install.ps1 | iex

Platform	What the script installs	Notes
Linux (amd64)	AppImage → `~/.local/bin/croc-desktop`	Adds a desktop menu entry; ensure `~/.local/bin` is on `PATH`
macOS (Apple Silicon)	DMG → `/Applications`	Ad-hoc signed — first open may need Privacy & Security → Open Anyway
Windows (x64)	MSI via `msiexec`	May prompt for administrator approval

Optional: pin a version with VERSION=v0.2.0 (Unix) or $env:VERSION = "v0.2.0" (PowerShell) before the one-liner.

Manual download

Releases →

Platform	File	Tips
Linux	`croc-desktop_*_linux-amd64.AppImage`	`chmod +x` the file, then double-click or run it
macOS (Apple Silicon)	`croc-desktop_*_darwin-arm64.dmg`	Open the DMG and drag the app to Applications
Windows	`croc-desktop_*_windows-amd64.msi`	Run the installer

Both sides of a transfer need either this app or the croc CLI.

Mobile (iOS · Android)

Same app, same UI (bottom tabs on a phone-sized screen). Powered by Wails v3 native mobile targets.

Client	Status	Where it lives	How to run
iOS	Experimental — build from source	Scaffold in `build/ios/`	Simulator / device (needs full Xcode on macOS)
Android	Experimental — build from source	Scaffold in `build/android/`	Emulator / device (needs Android SDK + NDK)

There are no App Store / Play Store packages yet — mobile is for people who build from this repo (or a CI you set up). Desktop remains the supported download path on Releases.

Build & run mobile clients

Prerequisites: same as Development (Go, Node, Wails v3 CLI), plus the platform SDK.

# Install Wails v3 CLI (pin matches go.mod)
go install -tags gtk3 github.com/wailsapp/wails/v3/cmd/wails3@v3.0.0-alpha2.119

# Frontend assets (embedded into the app)
npm --prefix frontend ci && npm --prefix frontend run build

# ── iOS (macOS + Xcode only) ─────────────────────────────────
wails3 task ios:run                          # Simulator
# Device:
# wails3 task ios:package IOS_PLATFORM=device \
#   CODESIGN_IDENTITY="Apple Development: You (TEAMID)"

# ── Android ──────────────────────────────────────────────────
wails3 task android:run                      # emulator or adb device

	Value
iOS bundle ID	`io.github.sihanteng.croc-desktop`
Android applicationId	`io.github.sihanteng.crocdesktop` (no hyphens)
Config	`build/config.yml` (`ios:` block)
Platform hooks	`app_options_ios.go`, `app_options_android.go`

UI tip: resize the desktop window to ~360px wide to preview the mobile bottom-tab layout without a phone.

How to use

Send something

Open Send.
Drop files or a folder, browse to pick them, or switch to Text for a snippet.
Press Send. You’ll get a short code and a QR.
Share the code (or the QR image) with the person receiving.
Wait for them to accept — progress shows live. Cancel anytime with the button or Esc.

Receive something

Open Receive.
Paste the code (or a whole croc … command / share link) — or load a QR screenshot.
Choose a download folder if you like, then Receive.
Accept (or decline) when the prompt appears.
When it’s done, open previews for images, video, audio, or text right in the app.

Everyday extras

History — past sends and receives, searchable.
Favorites — save codes you reuse often.
Send again — re-send the same files or text without re-picking.
Settings — theme (light / dark / system), language, custom relays, proxies, and more.
Relay — optionally host a relay from the app for locked-down networks.

Features

Transfer

Files & folders (drag and drop or picker)
Text snippets
QR code + copy code / copy CLI command
Paste codes in any common format (code, croc code, CROC_SECRET=…, share links)
Decode codes from QR screenshots
Accept / decline and overwrite / resume prompts
Live progress, stall hints, cancel anytime
Resume interrupted receives
Inline previews after receive
Desktop notifications on finish or failure

App

Transfer history that survives restarts
Live logs with level filters
Optional in-app relay
Custom relay address & password, crypto curve, hash algorithm
Local-only / disable-local modes, compression, proxies (SOCKS5 / HTTP)
Zip folders, exclude patterns, upload rate limit
Light / dark / system theme
Languages: English, 简体中文, 繁體中文, Español, Français, Deutsch, 日本語
Responsive layout: side rail on desktop; bottom tabs on phones / small windows

FAQ

Is my data uploaded to a server?

No. Transfers are end-to-end encrypted and peer-to-peer. A public relay may help peers find each other (same idea as the croc CLI), but file contents are not stored there. You can run your own relay from the app or point at a private one in Settings.

Do both people need this app?

No. One side can use croc-desktop and the other the official croc CLI (or vice versa). Codes are compatible.

Does it work offline / on a LAN only?

Yes. Enable local-only (or use local discovery) in Settings when both devices are on the same network. You can also run a relay yourself under the Relay tab.

Where are settings and history stored?

In the same config area as the croc CLI (override with the CROC_CONFIG_DIR environment variable):

croc-desktop.json — preferences
croc-desktop-history.json — transfer history
croc-desktop.log — persistent app log (JSON lines, rotated at ~2 MiB × 3 files)

Older installs that used croc-gui.json are upgraded automatically on first run.

macOS says the app is from an unidentified developer

Release builds are currently ad-hoc signed, not notarized. Open System Settings → Privacy & Security and allow the app after the first blocked launch, or right-click → Open.

Is this still Wails v2?

No. This branch uses Wails v3 (github.com/wailsapp/wails/v3, see go.mod). Docs: v3.wails.io. If you still see “Wails v2” on GitHub, you are looking at an older branch (e.g. main before merge).

Where do I get the mobile apps?

See Mobile (iOS · Android) above. They are built from this repo with wails3 task ios:run / android:run — not published as store installers yet.

使用 Clash 等代理时连不上中继？请将中继设为直连（DIRECT）

若本机开启了 Clash / Clash Meta（mihomo）/ Clash Verge 等代理（尤其是 fake-IP 模式），公共中继域名可能被解析成 198.18.x.x 等虚假地址，导致发送/接收失败（超时、EOF、「无法连接中继」等）。

请在代理工具中把 croc 公共中继设为直连（DIRECT），并建议加入 fake-IP 过滤。配置后重载配置，并重启 croc-desktop。应用内 Settings 请填写域名（如 croc.schollz.com:9009），不要填写 198.18.… 地址。

规则示例（写在 rules: 靠前位置，保证优先生效）：

rules:
  - DOMAIN,croc.schollz.com,DIRECT
  - DOMAIN,croc6.schollz.com,DIRECT
  # 可选：同域名后缀一并直连
  - DOMAIN-SUFFIX,schollz.com,DIRECT
  # …其余规则…

DNS fake-IP 过滤（推荐，Clash Meta / mihomo）：

dns:
  enable: true
  enhanced-mode: fake-ip
  fake-ip-filter:
    - croc.schollz.com
    - croc6.schollz.com
    - +.schollz.com   # 可选

图形界面用户可在「规则 / Rules」中手动添加上述 DOMAIN → DIRECT 项，保存后重载配置。

说明：直连仅在你的真实网络能访问公共中继时有效。若运营商屏蔽了该中继，需要改用可访问的中继，或在 Settings 中填写自建/其他可用中继地址。

Contributing

Contributions are welcome — bug reports, translations, docs, and pull requests.

Be kind; we follow the Code of Conduct.
Prefer small, focused pull requests.
For UI strings, edit JSON under frontend/src/i18n/locales/ (en.json is the source of truth). Copy it to a new locale file (e.g. pt-BR.json) and translate values; keep keys and {placeholders} intact.

Development

Build from source (developers)

Stack: Go (see go.mod), Node.js, Wails v3 — module github.com/wailsapp/wails/v3 @ v3.0.0-alpha2.119 (not the v2 CLI).

# Wails v3 CLI (use -tags gtk3 on Linux without gtk4)
go install -tags gtk3 github.com/wailsapp/wails/v3/cmd/wails3@v3.0.0-alpha2.119

# Linux: webkit2gtk 4.1 + GTK3 (project default)
#   Fedora: webkit2gtk4.1-devel
#   Debian/Ubuntu: libgtk-3-dev libwebkit2gtk-4.1-dev

# Dev with hot reload (desktop)
WEBKIT_DISABLE_DMABUF_RENDERER=1 wails3 dev -config ./build/config.yml -port 34115

# Production desktop binary → bin/croc-desktop
wails3 build -tags gtk3   # omit -tags gtk3 on macOS/Windows

# Mobile — see “Mobile (iOS · Android)” section
wails3 task ios:run
wails3 task android:run

# Tests
npm --prefix frontend ci && npm --prefix frontend run build
go test -tags gtk3 .
npm --prefix frontend test
./e2e/run.sh

More detail: e2e/README.md, design.md, and Taskfiles under build/.

How it works (short): the app depends on a croc fork with a hooks layer so progress and prompts are events in the UI, not a spawned CLI. See go.mod replace for the pin.

Acknowledgments

croc by @schollz — the protocol and transfer engine
Wails v3 — Go + web UI for desktop and mobile

License

MIT © SihanTeng. croc-desktop is an unofficial community project and is not affiliated with or endorsed by the croc authors. croc itself is MIT-licensed by its respective authors.

_{Made for people who just want to send a file.}

Name		Name	Last commit message	Last commit date
Latest commit History 42 Commits
.github/workflows		.github/workflows
.hallmark		.hallmark
build		build
docs/images		docs/images
e2e		e2e
frontend		frontend
packaging		packaging
.gitignore		.gitignore
.golangci.yml		.golangci.yml
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
LICENSE		LICENSE
README.md		README.md
Taskfile.yml		Taskfile.yml
app.go		app.go
app_api_test.go		app_api_test.go
app_options_android.go		app_options_android.go
app_options_default.go		app_options_default.go
app_options_ios.go		app_options_ios.go
app_test.go		app_test.go
backend_test.go		backend_test.go
cancel2_test.go		cancel2_test.go
cancel_test.go		cancel_test.go
codeparse.go		codeparse.go
codeparse_test.go		codeparse_test.go
design.md		design.md
go.mod		go.mod
go.sum		go.sum
history.go		history.go
history_test.go		history_test.go
history_unit_test.go		history_unit_test.go
install.ps1		install.ps1
install.sh		install.sh
logger.go		logger.go
logger_test.go		logger_test.go
main.go		main.go
notify.go		notify.go
qrdecode.go		qrdecode.go
qrdecode_test.go		qrdecode_test.go
relay.go		relay.go
relay_test.go		relay_test.go
settings.go		settings.go
settings_test.go		settings_test.go
transfer.go		transfer.go
version.go		version.go
version_test.go		version_test.go

Navigation Menu

Repository files navigation

croc-desktop

Why croc-desktop?

Install (desktop)

One-line install

Manual download

Mobile (iOS · Android)

Build & run mobile clients

How to use

Send something

Receive something

Everyday extras

Features

Transfer

App

FAQ

Contributing

Development

Acknowledgments

License

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

croc-desktop

Why croc-desktop?

Install (desktop)

One-line install

Manual download

Mobile (iOS · Android)

Build & run mobile clients

How to use

Send something

Receive something

Everyday extras

Features

Transfer

App

FAQ

Contributing

Development

Acknowledgments

License

About

Topics

Resources

Code of conduct

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages