One config file, shared by the desktop app, keibidrop-cli, and kd.
The config file is at the same relative path on every platform:
| Platform | Path |
|---|---|
| macOS | /Users/<you>/.config/keibidrop/config.toml |
| Linux | /home/<you>/.config/keibidrop/config.toml |
| Windows | C:\Users\<you>\.config\keibidrop\config.toml |
The file is created on the first run, with comments. All three interfaces read it. Restart after you edit it.
From 0.5.0 the app shows the settings below under Settings, Advanced settings, each with what it does and what it costs, and a Reset to defaults button. The defaults suit most people: change one only for a reason you know. kd help lists the same settings for the agent.
Source: pkg/config/config.go.
Values resolve in this order. Later wins:
| Key | Default | Meaning |
|---|---|---|
relay | https://keibidroprelay.keibisoft.com/ | Relay server used for pairing over the internet. |
save_path | ~/KeibiDrop/Received | Where received files are saved. |
mount_path | ~/KeibiDrop/Mount | FUSE mount point. On Windows, use a free drive letter such as K:. The Windows mount point must not already exist. |
log_file | per platform | Log file path. Defaults: macOS ~/Library/Logs/KeibiDrop/keibidrop.log; Linux and Windows ~/.local/share/keibidrop/keibidrop.log. |
inbound_port | 26431 | TCP listen port for peer connections. Must be in 26000-27000. The kd agent falls back to 26441 and kdmcp to 26451. A port set here is used by all of them, as given. |
outbound_port | 26432 | TCP outbound port. Must be in 26000-27000. The kd agent falls back to 26442 and kdmcp to 26452. |
bridge_addr | bridge.keibisoft.com:26600 | Bridge relay used when a direct connection fails. |
strict_mode | false | Disable the bridge fallback. Connections are direct or they fail. The same speed when a direct path works, with no relay speed limit. |
no_fuse | false | Disable the FUSE mount. The app runs in direct-transfer mode. |
incognito | false | Ephemeral keys every session. No identity or contacts on disk. |
prefetch_on_open | false | Fully prefetch any file when it is opened, whatever its size. Overrides prefetch_auto_mb. The most data of all: programs that show previews open files, and each open fetches the whole file. |
prefetch_auto_mb | 0 | Background-prefetch files at or above this many MB on open. 0 is off. Off by default: on a constrained or relayed link, bulk prefetch saturates the pipe and freezes interactive seeks. |
read_ahead_window_mb | 64 | Cap in MB for sequential read-ahead, so streaming over a high-latency link does not stall at block boundaries. Self-tunes below the cap. 0 disables. Higher fetches data that may never be read; 0 makes video over a long link pause. |
push_on_write | false | No effect at present. |
live_collab | false | macOS only: turn on the macFUSE auto_cache option, which checks a file's time each time a program opens it. From 0.5.0 a peer's edit shows without it, same file size included, because KeibiDrop drops the Mac's cached copy of each file the peer changes. In 0.4.8 and earlier it was the only way to see such an edit at once. auto_cache can corrupt files that programs write through memory maps (some databases), so leave it off unless an edit still shows late. No effect on Linux and Windows. |
passphrase_protect | false | Encrypt the identity with a passphrase (Argon2id). The app then asks for the passphrase at startup. |
scan_shared_on_start | false | Announce the files already in save_path when a session starts, so a folder that is already populated appears on the peer without adding each file again. Metadata only; content still streams on demand. |
rescan_shared_seconds | 30 | With scan_shared_on_start: walk save_path again this often while a session runs and announce the files that landed since the last pass, so a folder that fills up during the session (an FTP upload, a card copy) reaches the peer without a reconnect. A file whose modification time is still moving waits for the next pass. 0 turns it off. |
auto_connect_peer | "" | Name or fingerprint of a saved contact to connect to at startup, retrying while the peer is offline. Needs a persistent identity and a saved contact. |
share_read_only | false | Refuse every peer change to this node's files, checked on this node before anything reaches disk. The share becomes one way, so the peer can read and nothing else. Serving a read also avoids updating access times. |
mount_read_only | false | The local mount returns EROFS for write operations, so tools fail immediately instead of appearing to succeed. This is a courtesy on the reading side. share_read_only on the origin is the enforced one. |
preserve_metadata | false | When a received file finishes writing, apply the origin's permission bits and timestamps to the saved bytes. For work where the original times have to survive the transfer. |
update_check | true | At start, the app asks keibidrop.com for the newest version number and shows a notice when it is older. The request carries nothing about the install. Set false on a computer that must not call out. |
Two settings sound alike and do different jobs. Set both when the share must not be changed.
| Setting | Runs on | What it gives you |
|---|---|---|
share_read_only | The machine that holds the files | The guarantee. Every write, delete, rename, and attribute change arriving from the peer is refused before it reaches disk. |
mount_read_only | The machine doing the reading | Fast, clear failures. A tool that tries to write gets EROFS rather than a write that is later thrown away. |
Setting only mount_read_only is not a guarantee. It is a local courtesy on the reading side and a peer that chose not to set it could still send changes. The enforcement that counts is share_read_only, on the machine that owns the files.
On the origin, a read-only share is also the simpler path: there is no write-back, no conflict copies, and no inbound bitmap to maintain.
preserve_metadata applies the origin's mode and times to each file once it is complete on disk. Combined with share_read_only, reads served from the origin avoid touching access times, using O_NOATIME on Linux and a handle sentinel on Windows, so the times on the source stay as they were.
Three limits worth knowing before relying on it:
stat output and hashes right after the transfer, and keep save_path on a noatime or read-only mount during analysis.share_read_only = true mount_read_only = true preserve_metadata = true scan_shared_on_start = true
That set turns a machine into a one-way source: it announces what it already holds, serves reads without altering anything, and the reading side cannot write back.
Each setting has two names. The first non-empty value wins. Both names do the same thing.
| Setting | Names |
|---|---|
| Relay URL | KEIBIDROP_RELAY, KD_RELAY |
| Save path | TO_SAVE_PATH, KD_SAVE_PATH |
| Mount path | TO_MOUNT_PATH, KD_MOUNT_PATH |
| Log file | LOG_FILE, KD_LOG_FILE |
| Inbound port | INBOUND_PORT, KD_INBOUND_PORT |
| Outbound port | OUTBOUND_PORT, KD_OUTBOUND_PORT |
| Bridge address | BRIDGE_ADDR, KD_BRIDGE |
| Strict mode | STRICT_MODE, KD_STRICT |
| Disable FUSE | NO_FUSE, KD_NO_FUSE |
| Incognito | KEIBIDROP_INCOGNITO, KD_INCOGNITO |
| Rescan shared folder | KEIBIDROP_RESCAN_SHARED_SECONDS, KD_RESCAN_SHARED_SECONDS |
| Passphrase protection | KEIBIDROP_PASSPHRASE_PROTECT, KD_PASSPHRASE_PROTECT |
| Prefetch on open | KEIBIDROP_PREFETCH_ON_OPEN, PREFETCH_ON_OPEN_ENV |
| Prefetch threshold (MB) | KEIBIDROP_PREFETCH_AUTO_MB, PREFETCH_AUTO_MB_ENV |
| Read-ahead window (MB) | KEIBIDROP_READ_AHEAD_WINDOW_MB, READ_AHEAD_WINDOW_MB_ENV |
| Push on write | KEIBIDROP_PUSH_ON_WRITE, PUSH_ON_WRITE_ENV |
| Live collaboration | KEIBIDROP_LIVE_COLLAB, LIVE_COLLAB_ENV |
Two more variables sit outside the config file:
| Variable | Meaning |
|---|---|
KEIBIDROP_CONFIG_DIR | Moves the whole config directory: config, identity, and contacts. This is the supported way to run a second instance. See How to run two instances. |
KD_SOCKET | The kd daemon socket path. Default /tmp/kd.sock. Only kd reads it. |
Rule: 0, false, no, and off (any case) mean false. Any other non-empty value means true. So NO_FUSE=false keeps FUSE on, and NO_FUSE=1 turns it off.
To run two instances on one machine, give each one its own config directory, its own ports, and, for kd, its own socket:
KEIBIDROP_CONFIG_DIR=~/.config/kd-alice \ KD_SOCKET=/tmp/kd-alice.sock \ KD_INBOUND_PORT=26001 KD_OUTBOUND_PORT=26002 \ kd start
The full recipe is in How to run two instances.
The config file is not rewritten on upgrade. A key added in a new release is absent from your existing file and takes its built-in default. To set it, add the key to the file yourself.
Example: an older install that never had read_ahead_window_mb uses the default 64. Add the line to change it:
read_ahead_window_mb = 128