Configuration

Overview

The desktop reads a single TOML file:

~/.config/tde/config.toml

A missing file, a missing section or a missing field all fall back to defaults, so the desktop always starts. You never need to write this file — the Control Center edits most of it for you — but every setting is here if you would rather keep it in version control.

Around it sit a handful of sibling files in the same directory that extend the desktop without touching config.toml: notch.toml, commands/*.toml, widgets/*.toml and themes/*.toml.

A complete example

[theme]
mode = "tonal-slate"          # product default
# name = "gruvbox"            # overrides mode; built-in id or themes/<name>.toml

[[startup]]                   # apps opened when the desktop finishes booting
title = "Monitor"
command = "btop"

[[startup]]
title = "Logs"
command = "journalctl"
args = ["-f", "-n", "200"]

[wm]                          # Alt + <key>, or Esc then <key> in kiosk/SSH
close = "w"
minimize = "m"
cycle = "tab"
maximize = "up"
new_window = "enter"
overview = "o"
pan_left = "h"
pan_down = "j"
pan_up = "k"
pan_right = "l"
always_on_top = "p"
esc_leader = true
esc_leader_timeout_ms = 220

[tiling]                      # the drag-to-tile overlay at the top of the screen
shortcuts = ["left", "top-left", "bottom-left", "fullscreen",
           "bottom-right", "top-right", "right"]
bar_height = 5                # cells, 3-12
trigger_band = 2              # cells of hover padding around the bar

[privacy]
idle_timeout_secs = 300       # 0 disables the idle lock
lock_on_sleep = true

[keyboard]
layouts = ["us", "br:abnt2"]  # switcher appears with 2+ entries
switch = "grp:alt_shift_toggle"

[default_apps]                # TDE Files opens these before host xdg defaults
[[default_apps.files]]
extensions = ["sql"]
command = "tde"
args = ["database", "{path}"]

[[default_apps.files]]
extensions = ["png", "jpg"]
command = "xdg-open"
args = ["{path}"]
host = true                   # run on the host, not in a TDE PTY window

[files]
pinned_places = ["/srv/www", "/home/you/projects"]

[intro]
splash = true                 # the animated boot splash

Colors

Anywhere a color is accepted, four spellings work:

An unparsable color is a config error, not a silent fallback.

[theme]

mode accepts the three stable modes and their historical aliases:

• "tonal-slate" (slate, default) — the product default;
• "editorial-paper" (eink, e-ink, paper, kaleido);
• "editorial-ink" (midnight, dark, tde).

name is resolved in this order:

1. Any of the sixteen built-in ids, labels or aliases — Tonal Slate, Editorial Paper, Editorial Ink, Tonal Porcelain, Tonal Graphite, Tonal Sand, macOS, macOS Dark, Ubuntu, Windows XP, Dracula, Nord, Gruvbox, Solarized Dark, Catppuccin Mocha and Monokai.
2. Otherwise, ~/.config/tde/themes/<name>.toml.

A theme that fails to load prints a warning and the desktop falls back to mode, rather than refusing to start.

The [theme] table also accepts backdrop, window_bg, window_fg and accent colors. They parse, so old configs keep working, but the palette the desktop actually paints with comes from mode / name — use a theme file for per-role overrides. See Themes.

Theme files

A themes/<name>.toml file inherits every role it does not set from a base palette, so a one-line file is valid:

base = "tonal-slate" # omitted base also inherits Tonal Slate

[colors]
accent = "#3b5bdb"
accent_fg = "#ffffff"
surface = "#f7f5ee"
warn = "#b46b00"
danger = "#b3261e"

The [colors] table accepts bg, fg, dim, bright, accent, accent_fg, sel_bg, sel_fg, surface, backdrop, menu_bg, success, warn, danger, icon, input_bg, input_fg, border_on, border_off, title_on, title_off, btn_off, btn_bg, shadow, pill_on and pill_off. Setting accent without accent_fg re-derives a readable foreground rather than inheriting a clashing pair.

[[startup]]

An array of tables, one per app launched when the desktop finishes booting. Empty by default, so a fresh install opens clean.

Control Center → Startup Apps edits this list.

[wm]

Window-manager shortcuts. Values are compact key names — a letter (w, m), or one of tab, enter, up, down, left, right. TDE interprets them with Alt, and optionally through an Esc leader for terminals where Alt combinations are eaten in transit (kiosk sessions, some SSH clients, mobile keyboards).

[tiling]

The drag-to-tile overlay that appears at the top of the screen while you drag a title bar.

shortcuts accepts fullscreen (aliases full, maximize), left, right, top-left, top-right, bottom-left, bottom-right. Hyphenless and two-letter forms (topleft, tl, br) are accepted too. An unknown name is a config error. The overlay re-sorts the list into its canonical order regardless of how you write it.

[privacy]

[keyboard]

Codes look like us, br, or br:abnt2 for a layout with a variant. The status-bar layout switcher only appears once more than one layout is configured. An empty switch disables OS-level switching.

[default_apps]

File associations owned by TDE. These sit above the host's xdg-open, so TDE Files can prefer a native or TUI app even when running inside a Linux desktop. Associations are matched in order, by extension, case-insensitively.

Each entry is a [[default_apps.files]] table:

Placeholders available in args: {path}, {dir}, {file}, {stem} and {ext}.

[files]

[intro]

What the desktop writes back

Editing settings in the Control Center rewrites config.toml, merging into the existing document so hand-written sections survive. The sections it manages are [privacy], [wm], [tiling], [keyboard], [files], [[startup]] and [intro].

Sibling files

Everything below lives in ~/.config/tde/ next to config.toml, and each is loaded independently — a broken file falls back to built-in defaults instead of breaking the desktop.

notch.toml — quick-launch shortcuts

The Notch is the centered bar at the top of the screen. With no file, it shows built-in defaults (Apps, Shell, Files, Web, Chat, Control).

[settings]
enabled = true
icons_only = false

[[items]]
icon = "🚀"
label = "Apps"
action = "launcher"

[[items]]
icon = "🗄"
label = "Backups"
action = "cmd:restic snapshots"

An action is one of:

• A built-in id: launcher, terminal, files, browser, editor, database, aichat, control, myloop, store.
• cmd:<shell command> — run it in a terminal window.
• app:<catalog name> — launch a Store app.
• url:<address> — open it in the TDE Browser.

An entry with an empty action is dropped; if that leaves the list empty, the defaults come back. Control Center writes this file when you edit the Notch.

commands/*.toml — command-palette actions

Any .toml file in ~/.config/tde/commands/ adds rows to the Launcher's command palette, using the same action grammar as the Notch plus the control:<panel-id> and myloop:<section> deep links.

[[commands]]
app = "Deploy"
title = "Ship staging"
action = "cmd:make deploy-staging"
icon = "🚢"

[[commands]]
app = "Deploy"
title = "Open the dashboard"
action = "url:https://dash.internal/deploys"

The palette matches against "<app> <title>" and labels rows App: Title, so typing either the app name or a word from the action finds it.

widgets/*.toml — task-detail buttons

A widget is a button on a My Loop task that injects a prompt into the task as a comment, which the task's agent picks up on its next run. Drop one .toml per widget in ~/.config/tde/widgets/; a file widget with the same id as a built-in overrides it.

id = "screenshot"
label = "Screenshot"
icon = "📸"
requires = "agent-browser"
install_hint = "npm i -g agent-browser"
prompt = """
Open the app running from {worktree}, capture the main screen,
and attach the image to task {task}.
"""

requires names a CLI that must be on PATH; while it is missing the button shows install_hint instead of running. Placeholders in prompt: {worktree}, {demo_dir}, {task} and {tracker}.

themes/*.toml — custom palettes

Covered under [theme] above. The file stem is the name you put in theme.name.

Related

• Themes — the palettes and ANSI remapping in depth.
• Notch, taskbar and launcher — what the Notch and the palette drive.
• Windows and workspaces — the shortcuts in [wm] and [tiling] in context.
• Control Center — the UI that writes most of this file.
• Extending without code — commands, widgets and the rest of the no-code surface.