kcd.example.toml

# kcd configuration file
# Copy this file to ~/.config/kcd/kcd.toml and edit to taste.
# All settings are optional — safe defaults are applied automatically.
# Reload requires a daemon restart: systemctl --user restart kcd

# ─── Identity ─────────────────────────────────────────────────────────────────

# The name other devices see when discovering this machine.
# Default: system hostname.
# device_name = "my-desktop"

# Device type advertised to the KDE Connect app.
# One of: desktop, laptop, tablet, phone, tv
# Default: "desktop"
# device_type = "desktop"

# ─── Network ──────────────────────────────────────────────────────────────────

# TCP port for the KDE Connect control channel and UDP discovery.
# Change only if another service is using 1716.
# Default: 1716
# tcp_port = 1716

# Broadcast is disabled by default. It starts automatically when you run
# `kcd pair` (listen mode) and stops when pairing completes.
# Paired phones reconnect automatically via the last known IP.

# ─── Pairing ──────────────────────────────────────────────────────────────────

# Pairing is interactive. Run `kcd pair` (no arguments) to enter listen mode:
# it waits for any incoming pair request and auto-accepts it.
#
# To initiate pairing to a specific device, run `kcd pair <device-id>`.

# ─── Paths ────────────────────────────────────────────────────────────────────

# Directory where files received from paired devices are saved.
# Default: ~/Downloads/kcd
# download_dir = "~/Downloads/kcd"

# Unix socket used for IPC between the daemon and the kcd CLI.
# Only change this if you run multiple daemon instances.
# Default: $XDG_RUNTIME_DIR/kcd/kcd.sock  (e.g. /run/user/1000/kcd/kcd.sock)
# socket_path = "/run/user/1000/kcd/kcd.sock"

# TLS certificate and key generated on first run.
# Default: $XDG_CONFIG_HOME/kcd/cert.pem and key.pem
# cert_file = "~/.config/kcd/cert.pem"
# key_file  = "~/.config/kcd/key.pem"

# ─── Logging ──────────────────────────────────────────────────────────────────

# Log verbosity level.
# One of: debug, info, warn, error, quiet
# Default: "info"
# log_level = "info"

# ─── Plugins ──────────────────────────────────────────────────────────────────
# Each plugin can be individually enabled or disabled.
# All plugins are enabled by default.

[plugins]

# Monitor the phone's battery charge and charging state.
battery = true

# Bi-directional clipboard sync.
# Wayland: requires wl-copy / wl-paste (wl-clipboard package).
# X11:     requires xclip.
clipboard = true

# Forward phone notifications to the desktop via notify-send.
# Requires libnotify / a running notification daemon.
notification = true

# Receive files and URLs from the phone, and send files to it.
# Note: directory transfer is not supported (individual files only).
share = true

# Expose local shell commands to the phone.
# Commands are defined in the [commands] section below.
runcommand = true

# Control desktop media players (Spotify, VLC, etc.) via D-Bus / MPRIS2.
# Requires a D-Bus session bus. Disabled gracefully if unavailable.
mpris = true

# Pause music on incoming calls or when using the phone as a trackpad.
pausemusic = true

# Simple connectivity check — sends a "Ping!" notification to the phone.
ping = true

# Receive phone call and SMS notifications on the desktop.
telephony = true

# Phone signal strength and network type reporting.
connectivity = true

# Use the phone as a wireless trackpad and keyboard.
# Wayland: requires ydotool (+ ydotoold running as a service).
# X11:     requires xdotool.
mousepad = true

# Browse the phone's filesystem over SFTP.
# Optional: requires sshfs for the `kcd sftp mount` command.
# Commands:
#   kcd sftp request <id>   — Ask the phone to start its SFTP server
#   kcd sftp info <id>      — Show cached connection details and volumes
#   kcd sftp volumes <id>   — List available storage volumes (multiPaths)
#   kcd sftp mount <id>     — Request credentials, mount via sshfs, open
#   kcd sftp unmount <id>   — Unmount a previously mounted filesystem
sftp = true

# Ring the phone to locate it.
findmyphone = true

# Let the phone ring this machine to locate it.
findthisdevice = true

# Lock / unlock the desktop session via loginctl.
lockdevice = true

# Control desktop audio volume from the phone via D-Bus / PulseAudio-PipeWire.
systemvolume = true

# Send and receive SMS messages via a connected phone.
# Commands:
#   kcd sms send <id> <phone> <msg>        — Send an SMS
#   kcd sms conversations <id>             — List all conversations (results via `kcd watch --events sms.incoming`)
#   kcd sms conversation <id> <thread>     — Show a specific conversation
#   kcd sms attachment <id> <part> <uid>   — Request an MMS attachment file
# See the [sms] section below for notification settings.
sms = true

# Presenter remote — control slideshow presentations from the phone.
# Gyroscope-based pointer: requires xdotool (X11) or ydotool (Wayland).
# Screen size detection: requires xdpyinfo (X11) or wlr-randr (Wayland).
presenter = true

# ─── RunCommand: exposed commands ─────────────────────────────────────────────
# Shell commands that the RunCommand plugin makes available to your phone.
# Trigger them from the KDE Connect Android app → your device → Run command.
# Keys are the display labels; values are the shell commands executed locally.

[commands]
uptime  = "uptime -p"
lock    = "loginctl lock-session"
suspend = "systemctl suspend"
# reboot  = "systemctl reboot"
# screenshot = "grimblast save screen ~/Pictures/screenshot-$(date +%F-%T).png"

# Per-device commands override the global set for specific paired devices.
# Use the device ID shown in `kcd devices`.
# [commands_per_device."<device-id>"]
# screenshot = "grimblast save screen ~/Pictures/screenshot-$(date +%F-%T).png"

# ─── Notification filters ─────────────────────────────────────────────────────
# Control which phone app notifications appear on the desktop.
# Keys are Android app package names. Values: "show" or "silent".
# "silent" still emits a notification event (visible in kcd watch) but skips
# the desktop popup.
# The special key "*" sets the default for all unmatched apps.
#
# [notifications]
# "com.whatsapp"       = "show"
# "com.google.android.gm" = "silent"
# "*"                  = "show"

# ─── Battery: notifications and thresholds ────────────────────────────────────
# In addition to monitoring your phone's battery, the daemon also sends this
# machine's battery state to connected devices. This happens once on connect
# and whenever the phone explicitly requests it — no periodic polling.

[battery]
# notify_low = true
# notify_full = true
# low_urgency = "critical"      # low, normal, critical
# full_urgency = "normal"      # low, normal, critical
# low_message = "Battery low"
# full_message = "Battery fully charged"

# ─── Notification: desktop popup settings ────────────────────────────────────

[notification_plugin]
# urgency = ""                  # default: libnotify choice
# fetch_icons = true            # download app icons from the phone
# icon_cache_dir = ""           # persistent path for icons, defaults to temp
# max_body_length = 0           # 0 = no limit (truncates with … if set)
# expire_ms = -1                # notification timeout in milliseconds, -1 = default
# skip_non_clearable = false    # skip non-dismissible notifications (media playback, etc.)

# ─── Share: file transfer settings ────────────────────────────────────────────

[share]
# port_min = 1739               # start of TCP port range for transfers
# port_max = 1764               # end of TCP port range for transfers
# accept_timeout_secs = 120     # how long to wait for phone to connect
# auto_open = false             # automatically open received files
# open_command = "xdg-open"     # command used for auto_open
# overwrite = false             # overwrite files with same name instead of renaming

# ─── SFTP: remote filesystem mounting ────────────────────────────────────────

[sftp]
# mount_dir = ""                # parent directory for mounts, defaults to temp
# credentials_timeout_secs = 20 # how long to wait for phone credentials
# keepalive_interval_secs = 15  # sshfs ServerAliveInterval
# keepalive_count = 3           # sshfs ServerAliveCountMax
# auto_open = true              # automatically open mount in file manager
# open_command = "xdg-open"     # command used for auto_open
# extra_sshfs_opts = []         # list of strings, e.g. ["follow_symlinks", "allow_other"]

# ─── Ping: connectivity check ────────────────────────────────────────────────

[ping]
# app_name = "KDE Connect"
# icon = "smartphone"
# default_message = ""          # used if the phone sends an empty ping message

# ─── Pairing: protocol settings ──────────────────────────────────────────────

[pairing]
# timeout_secs = 30             # how long to wait for a pairing response

# ─── SMS: notification settings ──────────────────────────────────────────────

[sms]
# notify_incoming = true       # show a desktop notification on incoming SMS

# ─── Mousepad: remote input settings ─────────────────────────────────────────

[mousepad]
# backend = "auto"              # auto, ydotool, xdotool