Cratewell client

The Cratewell client syncs folders between your devices and keeps a versioned, end-to-end encrypted copy of everything in your crate. The same engine powers the desktop apps, the command line and the headless server agent.

This page covers installing the client, choosing what to sync, how the client talks to our servers, and the full CLI reference. If something isn’t covered here, write to support@cratewell.site.

Install

Installers are tied to your account, so download links live in the web app under Devices → Add device. Pick your platform there and the installer will already know which crate to connect to.

On Linux, install the package and enable the user service so the client starts with your session:

$ sudo apt install ./cratewell_4.8.1_amd64.deb
$ systemctl --user enable --now cratewell

For headless machines, install the agent as a system service instead. It runs without a logged-in user and stores its state in /var/lib/cratewell.

$ sudo install -m 755 cratewell-agent /usr/local/bin/
$ sudo cratewell-agent install --service

Sign in & devices

Each device gets its own key pair, generated locally. Signing in opens your browser to approve the device; nothing about your password is sent to the client.

$ cratewell login
Opening https://cratewell.site/login/device to authorize…
✓ Signed in · device studio-pc

On machines without a browser, use cratewell login --code. It prints a short code you enter on another device. Remove lost or retired devices from Devices in the web app; their keys are revoked immediately.

Folders

Anything you add is watched for changes and synced to every device that subscribes to it. Folders can live anywhere, including external drives and network mounts.

$ cratewell add ~/Projects ~/Photos
$ cratewell add /mnt/raid/footage --name Footage --no-placeholders
$ cratewell remove ~/Downloads --keep-remote

Moving or renaming files is detected locally and sent as a metadata change, so renaming a 200 GB folder costs a few kilobytes, not a re-upload.

Placeholders

With placeholders on, every file in the crate shows up on disk but only takes space once you open it. Files you haven’t touched in a while are evicted when free space drops under the threshold.

• Pin a file or folder to keep it on the device: cratewell pin ~/Photos/2026
• Unpin to let the client evict it again: cratewell unpin ~/Photos/2026
• Placeholders use File Provider on macOS, Cloud Files on Windows and a FUSE mount on Linux.

Ignore rules

Put a .crateignore file in any synced folder. The syntax matches .gitignore. Rules apply to that folder and everything below it.

# build output and caches
node_modules/
target/
*.tmp
.DS_Store
# keep this one even though *.log is ignored
*.log
!release.log

Versions & restore

Each change to a file creates a version. Versions are kept for as long as your plan allows: 30 days on Free, 180 days on Personal, one year or more on Archive.

$ cratewell versions ~/Documents/budget.xlsx
$ cratewell restore ~/Documents/budget.xlsx --at "2026-11-02 18:40"
$ cratewell restore ~/Projects --at "3 hours ago" --to ~/Restored

Restoring a folder never overwrites newer files unless you pass --overwrite. Instead it writes the old copies next to them, or into the path given with --to.

Connection

The client opens a single long-lived TLS 1.3 connection to cratewell.site on port 443 and multiplexes everything over it: change notifications, block uploads and downloads, and version queries. The connection stays open for as long as the client runs.

• Keep-alive frames are sent every 25 seconds while idle, so NAT gateways don’t drop the session.
• After a network change (Wi-Fi roaming, VPN, sleep), the session resumes in under a second and in-flight blocks continue where they stopped.
• If the connection drops, the client retries with exponential backoff from 1 to 60 seconds.

You can check the current session at any time:

$ cratewell status --verbose
● connected   cratewell.site:443  tls1.3  eu-central
  session     41h 12m   streams 8   rtt 38 ms
  ↑ 48.6 MB/s   ↓ 12.1 MB/s   queue 3 files / 3.5 GB

Bandwidth

There are no limits on our side. By default the client uses up to 8 parallel streams and as much bandwidth as is available. To be polite to the rest of your network, set limits per device:

$ cratewell config set network.upload_limit 20MB/s
$ cratewell config set network.schedule "09:00-18:00 limit 5MB/s"
$ cratewell pause --until 23:00

Proxies & firewalls

Outbound HTTPS on port 443 to cratewell.site is all the client needs. If your network requires an HTTP proxy, set it in the config file or with HTTPS_PROXY.

Command line

Config file

Settings live in ~/.config/cratewell/config.toml on Linux and macOS, and %APPDATA%\Cratewell\config.toml on Windows. The agent uses /etc/cratewell/agent.toml.

[sync]
region          = "eu-central"
placeholders    = true
evict_below     = "20GB"

[network]
parallel_streams = 8
upload_limit     = "0"      # 0 = unlimited
download_limit   = "0"
keepalive        = "25s"
proxy            = ""

[backup]                         # agent only
schedule  = "0 3 * * *"
retention = "180d"

Error codes