schollz/croc

This project’s future depends on community support. Become a sponsor today.

Supporting organizations:

croc is a tool that allows any two computers to simply and securely transfer files and folders. AFAIK, croc is the only CLI file-transfer tool that does all of the following:

• Allows any two computers to transfer data (p2p with relay fallback)
• Provides end-to-end encryption (using PAKE)
• Enables easy cross-platform transfers (Windows, Linux, Mac, Browser)
• Allows multiple file transfers
• Allows resuming transfers that are interrupted
• No need for local server or port-forwarding
• IPv6-first with IPv4 fallback
• Can use a proxy, like Tor

For more information about croc, see my blog post or read a recent interview I did.

You can use croc without installing anything at getcroc.com.

The browser version is fully compatible with the CLI, so you can send and receive files between them.

You can download the latest release for your system, or install a release from the command-line:

curl https://getcroc.com | bash

When the CLI sends or receives a transfer, it checks for a newer croc release at most once every 24 hours. The check runs in the background and any update notice is shown after the transfer finishes. Run croc update --check at any time to check explicitly. Installations made by the command above can use croc update (croc upgrade is an alias) to verify and install a stable release when the executable is user-writable; pass --yes to skip confirmation. Package-managed and other installations are never overwritten; the command prints the appropriate upgrade guidance instead. Network and release-service failures in background checks are ignored; --quiet suppresses the notice.

Using Homebrew:

brew install croc

Using MacPorts:

sudo port selfupdate
sudo port install croc

You can install the latest release with Scoop or Chocolatey:

scoop install croc

choco install croc

You can install the latest release with Nix:

nix-env -i croc

You can add this to your configuration.nix:

environment.systemPackages = [
  pkgs.croc
];

Enable the community repository for your Alpine release, then install:

apk add croc

Check the Alpine package index for your branch's version. Stable branches can carry older releases; see the distribution status before selecting one.

The pkg.haus archive provides third-party Debian packages. Follow its repository setup and supported-release instructions before running:

sudo apt install croc

For a release that includes upstream .deb downloads, download the file matching dpkg --print-architecture from the release page. Replace VERSION and ARCH below with the downloaded filename:

sudo apt install ./croc_VERSION-1_ARCH.deb

This downloaded-package method also applies to older Debian and Ubuntu releases that do not provide croc in their configured repositories. It does not add an APT repository; download a newer package to upgrade it.

For a release that includes upstream .rpm downloads, choose the file matching rpm --eval '%{_arch}' from the release page. Replace VERSION and ARCH with the downloaded filename:

sudo dnf install ./croc-VERSION-1.ARCH.rpm
# On openSUSE:
sudo zypper install ./croc-VERSION-1.ARCH.rpm

These downloads install the CLI, manual, license notices, and shell completions. They require ca-certificates and start no background services. Upgrade them through the package manager; croc update leaves package-owned binaries intact. See Linux packaging for architectures and verification.

Install with pacman:

pacman -S croc

Install with pkg:

pkg install croc

Install with pkg:

pkg install croc

You can install from conda-forge globally with pixi:

pixi global install croc

Or install into a particular environment with conda:

conda install --channel conda-forge croc

Add the following one-liner function to your ~/.profile (works with any POSIX-compliant shell):

croc() { [ $# -eq 0 ] && set -- ""; mkdir -p "$HOME/.config/croc"; docker run --rm -it --user "$(id -u):$(id -g)" -v "$(pwd):/c" -v "$HOME/.config/croc:/.config/croc" -w /c -e CROC_SECRET docker.io/schollz/croc "$@"; }

You can also just paste it in the terminal for current session. On first run Docker will pull the image. croc via Docker will only work within the current directory and its subdirectories.

If you prefer, you can install Go and build from source (requires Go 1.27+):

go install github.com/schollz/croc/v11@latest

There are F-Droid apps available:

• crocgui — original port (Go, basic UI)
• croc-app — native Kotlin/Jetpack Compose client with a modern, mobile-first interface
• FlCroc — cross-platform Flutter GUI (Android, Windows, Linux) that wraps the croc binary as its transfer core.

Community made desktop apps:

• Croc GUI — unofficial desktop GUI for macOS, Windows, and Linux that bundles the croc binary for drag-and-drop transfers, QR codes, LAN mode, and relay/proxy options.
• croc-desktop — unofficial desktop GUI for Linux, macOS, and Windows (experimental iOS/Android) built with Wails v3; embeds croc in-process for send/receive, QR codes, history, logs, and optional relay hosting.
• Swamp Swap — unofficial PyQt6 GUI desktop app for macOS, Windows, and Linux, requires installing croc on its own normally in order to use. Made to be compact and simple.

To send a file, simply do:

$ croc send [file(s)-or-folder]
Sending 'file-or-folder' (X MB)
Code is: code-phrase

Then, to receive the file (or folder) on another computer, run:

croc code-phrase

The code phrase is used to establish password-authenticated key agreement (PAKE) which generates a secret key for the sender and recipient to use for end-to-end encryption.

On Linux, macOS, FreeBSD, or OpenBSD, start a shared terminal with:

croc ssh

The host receives separate six-word invitations for read/write and read-only participants. On Unix, a participant keeps the invitation out of the process list by joining with the command croc prints:

CROC_SECRET='six-word-invitation' croc ssh

Everyone sees one persistent terminal. Multiple read/write participants may type; read-only participants receive the same output but their input is discarded.

This does not expose an SSH daemon or require an account, public IP, inbound port, or SSH key setup. The invitation authenticates an ephemeral Tailcat WireGuard path and pins an ephemeral SSH host key. Tailcat uses DERP when it cannot establish a direct path; if Tailcat itself is unavailable, the client reauthenticates and carries the pinned SSH stream over the ordinary croc relay. Remote commands, forwarding, and SFTP are disabled. Anyone who receives an invitation has the role printed beside it until the host stops, so treat both invitations as secrets.

See the SSH sharing design and security guide for protocol, reconnection, platform, relay, and threat-model details.

When an immediate peer-to-peer transfer is inconvenient, croc can upload regular files as client-side encrypted ciphertext:

croc store [file1] [file2]
croc store --downloads 3 --expiration 3d [file1] [file2]
croc store --url https://files.example.com [file1] [file2]

The original croc send --store syntax remains supported, with --store-downloads, --store-expiration, and --store-url settings.

The command prints a browser link and a CLI token. The transfer expires after the selected lifetime, measured from successful upload completion, or after its configured number of receivers download, authenticate, and verify every file—whichever happens first. The lifetime defaults to one day and accepts whole minutes (m), hours (h), days (d), or weeks (w). The download limit defaults to one. Both values are subject to server policy. Run croc with no arguments and paste the token at the prompt to receive it. For automation, keep the token out of the process list:

CROC_STORE_TOKEN='croc-store-v1....' croc --out ./downloads

The browser link has the form https://host/s/id#v1.decryption-key. The decryption key is after # because URL fragments are not included in HTTP requests, so the storage service gets the opaque transfer ID but not the key. The full link is still a secret: anyone who has it can decrypt the files and claim one of the allowed downloads.

While a transfer remains available, its sender can delete it with the locally saved revoke receipt:

croc --revoke [transfer-id]

Stored mode is opt-in and separate from croc's normal live relay transfers. A self-hosted service can be selected with croc store --url (or croc send --store --store-url) or CROC_STORE_URL. See the stored-transfer design and operator guide for protocol, privacy, limits, and deployment details.

On Linux and macOS, the sending and receiving process is slightly different to avoid leaking the secret via the process name. You will need to run croc with the secret as an environment variable. For example, to receive with the secret ***:

CROC_SECRET=*** croc

For single-user systems, the default behavior can be permanently enabled by running:

croc --classic

You can send with your own code phrase (must be at least 6 characters):

croc send --code [code-phrase] [file(s)-or-folder]

For default public transfers, SHA-256 of the exact code modulo the ordered three-relay pool determines which deployment both peers use. An automatically generated sender probes all three relays and generates a normal EFF code that maps to the first healthy one to respond. A custom code maps directly without probing or fallback. --relay, CROC_RELAY, --ip, and local-only transfers bypass this public routing rule. The generated sender caches the winning address in best-relay alongside croc's other configuration files, then reuses it without probing. A relay connection failure removes the cache so the following send measures the pool again; deleting the file also forces a new measurement.

To automatically overwrite files without prompting, use the --overwrite flag:

croc --yes --overwrite <code>

To keep an existing file and receive the incoming one under a new name (e.g. video (1).mkv), use the --rename flag:

croc --yes --rename <code>

To exclude folders from being sent, use the --exclude flag with comma-delimited exclusions. This does a case-insensitive substring match against each file's relative path, so any path containing one of the given strings anywhere is excluded:

croc send --exclude "node_modules,.venv" [folder]

If you need to exclude one specific file rather than every path containing a substring (for example, two files share a name at different depths and only one should be excluded), use --exclude-file instead. It takes comma-delimited relative paths and matches them exactly:

croc send --exclude-file "subfolder/image.jpg" [folder]

You can pipe to croc:

cat [filename] | croc send

To receive the file to stdout, you can use:

croc --yes [code-phrase] > out

To send URLs or short text, use:

croc send --text "hello world"

You can send multiple files directly by listing the files and/or folders:

croc send [file1] [file2] [file3] [folder1] [folder2]

To show QR code (for mobile devices), use:

croc send --qr [file(s)-or-folder]

The QR code opens https://getcroc.com/?code=..., where the web client automatically connects in receive-only mode.

You can send files via a proxy by adding --socks5:

croc --socks5 "127.0.0.1:9050" send SOMEFILE

Relay hostnames are resolved by the proxy, so the client does not need a working DNS server to reach the relay. Bare host:port, socks5://host:port, and socks5h://host:port all use proxy-side relay DNS. Use an IP address for the proxy itself when local DNS is unavailable. Set --socks5 on both peers (or use the SOCKS5_PROXY environment variable).

For a network that only permits proxy traffic, use --transport relay on the sender to use the SOCKS5-capable relay transport for file data. The browser client uses the browser's proxy settings for its WebSocket gateway connection; the native CLI flag does not configure the browser.

Sponsored by SX.org.

Sponsored by RapidProxy.

The native CLI defaults to --transport auto. After the normal three-word-code PAKE handshake, two compatible native clients create PAKE-bound Tailcat node identities and open one or more TCP streams over an in-process Tailscale userspace WireGuard network. Magicsock starts through DERP and promotes the connection to a direct UDP path whenever NAT traversal succeeds. If the peer is a browser, an older client, or Tailcat setup fails, both clients use croc's existing relay data ports. The public spelling --transport derp is retained; in strict mode it requires Tailcat support and disables croc-relay fallback. Public DERP is best effort and may apply fairness limits; see Tailscale's DERP reference and performance guidance.

To choose a different elliptic curve for encryption, use the --curve flag:

croc --curve p521 <codephrase>

For faster hashing, use the imohash algorithm:

croc send --hash imohash SOMEFILE

By default, the code phrase is copied to your clipboard. To disable this:

croc --disable-clipboard send [filename]

To copy the full command with the secret as an environment variable (useful on Linux/macOS):

croc --extended-clipboard send [filename]

This copies the full command like CROC_SECRET="code-phrase" croc (including any relay/pass flags).

To suppress all output (useful for scripts and automation):

croc --quiet send [filename]

You can run your own relay:

croc relay

By default, it uses TCP ports 9009-9013. You can customize the ports (e.g., croc relay --ports 1111,1112), but at least 2 ports are required.

To send files using your relay:

croc --relay "myrelay.example.com:9009" send [filename]

You can also run a relay with Docker:

docker run -d -p 9009-9013:9009-9013 -e CROC_PASS='YOURPASSWORD' docker.io/schollz/croc

To send files using your custom relay:

croc --pass YOURPASSWORD --relay "myreal.example.com:9009" send [filename]

To use custom ports, set CROC_PORTS (comma-separated) or CROC_PORT (base port):

docker run -d -p 9010-9011:9010-9011 -e CROC_PORTS='9010,9011' -e CROC_PASS='YOURPASSWORD' docker.io/schollz/croc

The React/Vite client in web/ can send and receive multiple files and join croc ssh sessions hosted by normal CLI peers. The production client and its WebAssembly protocol runtime are bundled only in the standalone croc-web server, keeping generated assets and web-server code out of the cross-platform croc binary. Linux amd64 builds of croc-web are published separately with each release. It serves both the site and its same-origin WebSocket relay:

croc-web getcroc.com

This binds to 127.0.0.1:9014 by default for an HTTPS reverse proxy. / serves the website and /ws bridges to the code-selected public relay at 1.getcroc.com, 2.getcroc.com, 3.getcroc.com, or 4.getcroc.com. For a directly accessible local development server, croc-web localhost:5173 binds and serves on localhost:5173. Use --bind, --relays, and --ports before the website address to customize the local listener or upstream croc relay.

Run make build-web to generate the ignored production assets and build a local server. See web/README.md for frontend development, custom relay, and reverse-proxy instructions.

Disco is used to deploy. The root Dockerfile and disco.json deploy the croc-web web client and croc TCP relay as two Disco services built from the same image. Disco serves the website over HTTPS, while relay ports 9009-9017 are published directly as TCP ports.

Set the deployment environment variables with:

disco env:set \
  SITE_URL=yoururl.com \
  CROC_RELAY_PORTS=9009,9010,9011,9012,9013,9014,9015,9016,9017 \
  CROC_PASS=yourpass \
  --project croc

SITE_URL must be the public website hostname without https://. Change the project name if it is not croc. The web service mounts the named croc-store volume at /www/croc/storage, which is also its configured --store-dir, so stored ciphertext and metadata survive container replacement and redeployment. The web service also reserves published TCP port 9020 and maps it to unused container port 65535. This deliberate port collision makes Disco stop the previous volume-owning web service before starting its replacement, avoiding concurrent access to the store. Port 9020 carries no application traffic and should remain blocked by the server firewall.

Stored-upload policy can be set per deployment without editing disco.json:

disco env:set \
  CROC_STORE_CREATE_RATE=60 \
  CROC_STORE_ACTIVE_UPLOADS=10 \
  CROC_STORE_UPLOAD_TIMEOUT=5m \
  CROC_STORE_TRUSTED_PROXY=VERIFIED_PROXY_IP/32 \
  --project croc --disco YOUR_DISCO_HOST

Replace the proxy placeholder with the socket source address seen by croc. With Docker Swarm routing, this can be the lb-disco-main endpoint shown by docker network inspect disco-main, rather than Caddy's container address. Verify the source on each instance and again after Docker network changes. Caddy's normal forwarding configuration supplies X-Forwarded-For; verify that different external clients remain distinct and that a forged incoming header cannot choose their accounting IP. Do not edit Disco-generated Caddy configuration or trust an entire private network to work around a mismatch.

The values above are deployment overrides; croc's defaults remain five creation attempts per hour and two unfinished uploads per IP. CROC_STORE_DOWNLOADS controls downloads from each link and does not raise upload limits. See the stored-transfer operator guide for timeout, cleanup, and rate-limit response behavior.

The ports in CROC_RELAY_PORTS must match the publishedPorts entries in the relay service in disco.json; do not include the web service's deployment-only port 9020. Disco cannot generate host port mappings from an environment variable. Make sure the relay TCP ports are also open in the server's firewall or cloud security group.

croc has evolved through many iterations, and I am thankful for the contributions! Special thanks to:

• @warner for the idea
• @tscholl2 for the encryption gists
• @skorokithakis for proxying two connections

And many more!