Settings
Cadmus reads settings from Settings/Settings-*.toml.
Settings can be changed via Main Menu → Settings, which opens the built-in settings editor.
Legend:
- ✏️ Editable in the settings editor
- 🔑 Required for feature to work
- 🧪 Only available in test builds
- 📱 Kobo
Example Full Config
Expand Me
# selected-library = 0
# Possible values: "English", "Russian".
keyboard-layout = "English"
frontlight = true
wifi = false
# Invert the display's colors.
inverted = false
# Handle the Sleep Cover event.
sleep-cover = true
# Automatically enters shared mode when connected to a computer.
auto-share = false
# Automatically synchronize the device time via NTP when WiFi connects.
# This will also set the correct timezone, it uses
# time.cloudflare.com and ipapi.co
auto-time = false
# Automatically adjust frontlight warmth based on sun position.
# Coordinates are auto-detected during time sync (via ipapi.co)
# unless manually specified below.
auto-frontlight = false
# Night brightness level when the sun is down (0.0 to 100.0).
auto-frontlight-night-brightness = 10
# Manual GPS coordinates override (latitude, longitude).
# auto-frontlight-manual-coordinates = [51.5074, -0.1278]
# Last auto-detected coordinates from time sync (written automatically).
# auto-frontlight-last-coordinates = [48.8566, 2.3522]
# Defines how the back and forward buttons are mapped to the
# *page forward* and *page backward* actions.
# Possible values: "natural", "inverted".
button-scheme = "natural"
# The number of minutes of inactivity after which a device
# will automatically go to sleep. *Zero* means *never*.
auto-suspend = 30.0
# The delay, in days, after which a suspended device
# will power off. *Zero* means *never*.
auto-power-off = 3.0
# Formats used for the clock and the clock's pop-up menu.
# The available specifiers are described at:
# https://docs.rs/chrono/latest/chrono/format/strftime/index.html
time-format = "%H:%M"
date-format = "%A, %B %-d, %Y"
# Appends the tapped external URLs to this file.
external-urls-queue = "bin/article_fetcher/urls.txt"
# The number of old versioned settings files to keep.
# Cadmus stores each version's settings in a separate file (e.g., Settings-v0.1.0.toml)
# for backward and forward compatibility across version upgrades.
# Files older than this count are automatically removed. Set to 0 to keep all files.
settings-retention = 3
# The number of database backup files to keep.
# A fresh backup is created on every startup. When the count exceeds this limit,
# the oldest backups are deleted automatically. Set to 0 to disable backups.
db-backup-retention = 2
# The preferred language for the user interface, using BCP 47 format.
locale = "en-US"
# What to show when Cadmus starts. Possible values: "home", "last-file".
startup-mode = "home"
[logging]
# Enable or disable structured JSON logging.
enabled = true
# Possible values: "trace", "debug", "info", "warn", "error".
level = "info"
# The number of rotated log files to keep. Use 0 to keep all files.
max-files = 3
# Directory for log files (relative to the installation directory).
directory = "logs"
# Optional OTLP endpoint for exporting logs when the build enables the otel feature.
# otlp-endpoint = "https://otel.example.com:4318"
# Optional Pyroscope server URL for continuous profiling when the build enables the profiling feature.
# Env var PYROSCOPE_SERVER_URL takes precedence over this value.
# pyroscope-endpoint = "http://pyroscope.example.com:4040"
# Capture kernel logs (requires test build with kobo feature).
# enable-kern-log = false
# Capture D-Bus signals via the built-in zbus-based DbusMonitorTask (requires test build with
# kobo feature; no external dbus-monitor tool is needed).
# enable-dbus-log = false
# You can create libraries by adding further [[libraries]] entries.
[[libraries]]
name = "On Board"
path = "/mnt/onboard"
# Possible values: "database", "filesystem".
mode = "database"
sort-method = "opened"
first-column = "title-and-author"
second-column = "progress"
thumbnail-previews = true
# This example fetcher retrieves articles through the *Wallabag* protocol.
# See `doc/ARTICLE_FETCHER.md` on how to configure it.
[[libraries.hooks]]
path = "Articles"
program = "bin/article_fetcher/article_fetcher"
sort-method = "added"
first-column = "title-and-author"
second-column = "progress"
# Remove this entry if you don't have an external card slot
# on your device.
[[libraries]]
name = "Removable"
path = "/mnt/sd"
mode = "database"
sort-method = "opened"
first-column = "title-and-author"
second-column = "progress"
thumbnail-previews = true
[[libraries]]
name = "Dropbox"
path = "/mnt/onboard/.kobo/dropbox"
[[libraries]]
name = "KePub"
path = "/mnt/onboard/.kobo/kepub"
# finished = "go-to-next" # Optional: overrides reader.finished for this library
# Defines the images displayed when entering an intermission.
# Suspend supports "logo:", "cover:", "calendar:", "blank:",
# "blank-inverted:", and custom image paths.
# Power-off and share support "logo:", "cover:", "blank:",
# "blank-inverted:", and custom image paths.
# If a relative file path is given, it will be relative to
# the installation directory.
# Setting suspend to "calendar:" will show the calendar when the device
# wakes every 5 minutes to refresh it, then goes back to sleep.
[intermissions]
suspend = "logo:"
power-off = "logo:"
share = "logo:"
[home]
# Show the address bar that display the path of the current directory.
address-bar = false
# Show the navigation bar that displays the directory hierarchy.
navigation-bar = true
# The maximum number of levels shown above the current directory.
max-levels = 3
# The size limit, in bytes, of the trash. Once the limit is reached,
# documents will be automatically removed until the invariant is restored.
max-trash-size = 33_554_432
[reader]
# How to react when a book is finished.
# Possible values: "notify", "close", "go-to-next".
finished = "close"
# The action triggered when tapping the south-east corner.
# Possible values: "go-to-page", "next-page".
south-east-corner = "go-to-page"
# The action triggered when making bottom right corner gesture.
# Possible values: "toggle-dithered", "toggle-inverted".
bottom-right-gesture = "toggle-dithered"
# The action triggered when tapping the south strip.
# Possible values: "toggle-bars", "next-page".
south-strip = "toggle-bars"
# The action triggered when tapping the west strip.
# Possible values: "previous-page", "next-page", "none".
west-strip = "previous-page"
# The action triggered when tapping the east strip.
# Possible values: "previous-page", "next-page", "none".
east-strip = "next-page"
# The width ratio, relative to `min(W, H) / 2`, of the strip and corner touch regions.
# Launch the *Touch Events* application to display the current touch regions.
strip-width = 0.6
corner-width = 0.4
# The path for the user's custom font directory.
# Note: this does not exist by default.
font-path = "/mnt/onboard/fonts"
# The default serif font.
font-family = "Libertinus Serif"
# The default, minimum and maximum font sizes, in points.
font-size = 11.0
min-font-size = 5.5
max-font-size = 16.5
# The default text alignment.
# Possible values: "left", "right", "center", "justify".
text-align = "left"
# The default, minimum and maximum margin widths, in millimeters.
margin-width = 8
min-margin-width = 0
max-margin-width = 10
# The default line height, in ems.
line-height = 1.2
# Determine the scroll mode used for the fit-to-width zoom mode
# when opening a new document.
continuous-fit-to-width = true
# Whether to ignore the document's style sheets.
ignore-document-css = false
# The file extensions of the files that will automatically be dithered
# when opened for the first time.
dithered-kinds = ["cbz", "jpg", "png", "jpeg"]
[reader.paragraph-breaker]
# The penalty for hyphenated lines. The maximum value is 10_000.
hyphen-penalty = 50
# The stretch/shrink tolerance of inter-word spaces.
stretch-tolerance = 1.26
# Refresh the screen every `regular` page turns when the colors aren't inverted,
# and every `inverted` page turns when they are. *Zero* means *never*.
[reader.refresh-rate]
regular = 8
inverted = 2
# Override the refresh rates for individual file types.
# [reader.refresh-rate.by-kind]
# cbz = { regular = 1, inverted = 1 }
[import]
# When a document changes, re-extract its metadata.
sync-metadata = true
# The file extensions of the documents for which the metadata extraction
# process will occur.
metadata-kinds = ["epub", "pdf", "djvu"]
# The file extensions of the documents that will be considered during the
# import process.
allowed-kinds = ["djvu", "xps", "fb2", "txt", "pdf", "oxps", "cbz", "epub"]
[dictionary]
# The default font size and margin width, for the Dictionary application.
# The units are the same as in the `[reader]` section.
font-size = 11.0
margin-width = 4
[sketch]
# The path to a directory where the sketches will be saved.
# Relative paths are relative to the current library's path.
save-path = "Sketches"
# Create a notification when a sketch is successfully saved.
notify-success = true
[sketch.pen]
# The diameter of the pen tip, in pixels.
size = 2
# The current pen color.
# Possible values: 0 … 255.
color = { gray = 0 }
# Vary the diameter according to the pen's velocity.
dynamic = true
# The amplitude of the diameter variation when `dynamic` is set.
amplitude = 4.0
# The pen speeds, in pixels per seconds, that clamps the pen's speed.
# min-speed = 0.0
# max-speed = 3000.0
[calculator]
# The default font size and margin width, for the Calculator application.
# The units are the same as in the `[reader]` section.
font-size = 8.0
margin-width = 2
# The number of remembered inputs.
history-size = 4_096
[battery]
# Warn about the battery level being low, when the level
# goes below `warn` percents.
warn = 10.0
# Shut the device down when the battery level goes below
# `power-off` percents.
power-off = 3.0
[frontlight-levels]
intensity = 0.0
warmth = 0.0
# Over-The-Air (OTA) updates allow you to download and install
# Cadmus builds directly from GitHub.
# Authentication for main branch and PR builds is handled via GitHub device auth flow.
[ota]
General Settings
keyboard-layout
✏️
Keyboard layout to use for text input.
- Possible values:
"English","Russian".
keyboard-layout = "English"
sleep-cover
✏️
Handle the magnetic sleep cover event.
sleep-cover = true
auto-share
✏️
Automatically enter shared mode when connected to a computer, skipping the “Share storage via USB?” prompt.
Tip
Turn this on if you update Cadmus via USB often — you won’t have to confirm the sharing dialog each time you plug in.
auto-share = false
auto-time
✏️
Automatically synchronize the device time via NTP when WiFi connects. This will also set the correct timezone. Uses time.cloudflare.com and ipapi.co.
auto-time = false
auto-frontlight
✏️
Automatically adjust the frontlight warmth and brightness based on the sun’s position at the device’s location.
- During the day warmth is at its minimum.
- Around sunrise and sunset warmth ramps gradually between zero and full.
- After sunset brightness is reduced to
auto-frontlight-night-brightnessand warmth stays at its maximum until sunrise.
Coordinates are auto-detected during each time sync (via ipapi.co) and stored in auto-frontlight-last-coordinates. Set auto-frontlight-manual-coordinates to override the detected location.
auto-frontlight = false
auto-frontlight-night-brightness
✏️
Frontlight brightness level (0.0–100.0) applied when the sun is below the horizon.
This setting is optional. When not set, a default of 1.0 is used.
auto-frontlight-night-brightness = 10.0
auto-frontlight-manual-coordinates
✏️
GPS coordinates [latitude, longitude] to use for sun-position calculations instead of the auto-detected location. Takes priority over auto-frontlight-last-coordinates.
This setting is optional.
auto-frontlight-manual-coordinates = [51.5074, -0.1278]
auto-frontlight-last-coordinates
GPS coordinates [latitude, longitude] last detected during a time sync. Written automatically — do not edit this by hand; set auto-frontlight-manual-coordinates to override the location instead.
This setting is optional and managed automatically.
# auto-frontlight-last-coordinates = [48.8566, 2.3522]
auto-suspend
✏️
Number of minutes of inactivity after which the device will automatically go to sleep.
- Zero means never.
auto-suspend = 30.0
auto-power-off
✏️
Delay in days after which a suspended device will power off.
- Zero means never.
auto-power-off = 3.0
button-scheme
✏️
Defines how the back and forward buttons are mapped to page forward and page backward actions.
- Possible values:
"natural","inverted".
button-scheme = "natural"
locale
✏️
The preferred language for the user interface, using BCP 47 format (e.g., "en-US", "de-DE").
This setting is optional. When not set, en-GB is used.
locale = "en-GB"
startup-mode
✏️
What to show when Cadmus starts.
"home"— open the home screen (default)."last-file"— re-open the last book you were reading. If there is no unfinished book in the selected library, the home screen is shown instead.
startup-mode = "home"
Reader
Settings that control the reading experience.
reader.finished
✏️
What to do when you finish reading a book.
Possible values:
"notify"(show a notification)"close"(close the book and go back)"go-to-next"(open the next book in the library).
[reader]
finished = "close"
reader.dithered-kinds
✏️
File extensions rendered with dithering by default.
[reader]
dithered-kinds = ["cbz", "png", "jpg", "jpeg", "webp"]
Libraries
✏️
Document library configuration. Each library has a name, path, and mode.
[[libraries]]
name = "On Board"
path = "/mnt/onboard"
mode = "database"
libraries.name
✏️
Display name for the library.
libraries.path
✏️
Directory path containing documents.
libraries.mode
✏️
Library indexing mode.
- Possible values:
"database","filesystem".
libraries.finished
✏️
Override the reader.finished setting for this specific library.
When set, this takes precedence over the global reader setting.
Possible values:
"notify""close""go-to-next".- Leave unset to inherit the global
reader.finishedsetting.
[[libraries]]
name = "KePub"
path = "/mnt/onboard/.kobo/kepub"
finished = "go-to-next"
Intermissions
✏️
Defines the images displayed when entering an intermission state.
[intermissions]
suspend = "logo:"
power-off = "logo:"
share = "logo:"
intermissions.suspend
✏️
Image displayed when the device enters sleep mode.
Setting this to "calendar:" also enables the calendar refresh: every 5
minutes, the device wakes, shows the calendar, and then goes back to sleep
automatically.
- Possible values:
"logo:"(built-in logo),"cover:"(current book cover),"calendar:"(built-in calendar), or a path to a custom image file.
intermissions.power-off
✏️
Image displayed when the device powers off.
- Possible values:
"logo:"(built-in logo),"cover:"(current book cover), or a path to a custom image file.
intermissions.share
✏️
Image displayed when entering USB sharing mode.
- Possible values:
"logo:"(built-in logo),"cover:"(current book cover), or a path to a custom image file.
Import
These settings control how Cadmus imports documents from your device. They are available in the Settings → Import menu.
Import scanning happens automatically on startup using incremental file checking — files are only re-scanned if their modification time or size has changed since the last import.
To trigger a full re-scan of all files regardless of cached values, use the Force Full Import action button in the Import settings category.
import.sync-metadata
✏️
Re-extract metadata (title, author, etc.) whenever a document changes.
[import]
sync-metadata = true
import.metadata-kinds
File extensions of documents whose metadata is extracted during import.
[import]
metadata-kinds = ["epub", "pdf", "djvu"]
import.allowed-kinds
✏️
File extensions of documents considered during the import process.
[import]
allowed-kinds = ["djvu", "xps", "fb2", "txt", "pdf", "oxps", "cbz", "epub"]
OTA
The OTA feature downloads builds from GitHub.
Authentication for main branch and PR builds uses GitHub device auth flow.
When you select a build that requires authentication,
Cadmus will display a short code and a URL. Visit
github.com/login/device on any device, enter the code, and Cadmus will
automatically continue the download once you authorize.
The token is saved to disk after the first authorization so you will not be prompted again on subsequent downloads.
For step-by-step instructions with screenshots, see the OTA updates guide.
Telemetry
Cadmus writes JSON logs to disk. When the build enables the tracing feature, it
can also export logs to an OpenTelemetry endpoint.
These settings are available in the Settings → Telemetry menu.
Important
Changes to these settings only take effect after restarting Cadmus. The application initializes telemetry on startup.
logging
[logging]
enabled = true
level = "info"
max-files = 3
directory = "logs"
# otlp-endpoint = "https://otel.example.com:4318"
logging.enabled
✏️
Enable or disable structured JSON logging.
[logging]
enabled = true
logging.level
✏️
Minimum log level to record.
- Possible values:
"trace","debug","info","warn","error".
[logging]
level = "info"
logging.max-files
Number of log files to keep. Only the most recent N files are kept — older ones are deleted automatically when Cadmus starts.
- Default:
3 - Set to
0to keep all log files.
[logging]
max-files = 3
logging.otlp-endpoint
✏️ (only when the tracing feature is enabled)
Optional OTLP endpoint for exporting logs to an OpenTelemetry collector.
[logging]
otlp-endpoint = "https://otel.example.com:4318"
Environment override:
OTEL_EXPORTER_OTLP_ENDPOINTtakes precedence overlogging.otlp-endpoint.
logging.pyroscope-endpoint
✏️ (only when the profiling feature is enabled)
Optional Pyroscope server URL for continuous profiling. When set, Cadmus starts both a heap profiling agent (via jemalloc) and a CPU profiling agent (via pprof) that push profiles to this endpoint.
[logging]
pyroscope-endpoint = "http://localhost:4040"
Environment override:
PYROSCOPE_SERVER_URLtakes precedence overlogging.pyroscope-endpoint.
logging.enable-kern-log
🧪 📱 ✏️
Captures kernel logs via logread -F and forwards them to structured logging
with the target cadmus_core::logging:kern.
[logging]
enable-kern-log = false
logging.enable-dbus-log
🧪 📱 ✏️
Captures D-Bus signals via the built-in zbus-based DbusMonitorTask and forwards them to structured logging.
[logging]
enable-dbus-log = false
Settings Retention
Cadmus stores each version’s settings in a separate file in the Settings/ directory (for example, Settings-v1.2.3.toml).
This ensures backward and forward compatibility when you upgrade.
settings-retention
Number of recent version settings files to keep. Only the most recent N version files are kept. When a new version is saved, older versions beyond this limit are deleted automatically.
- Default:
3 - Set to
0to keep all version files
settings-retention = 3
db-backup-retention
Number of database backups to keep. When a new backup is created and the total would exceed this limit, the oldest backups are deleted automatically.
- Default:
2 - Set to
0to disable backups entirely.
See Database Backup for more details.
db-backup-retention = 2