Basic Configuration

Sweets is configured with a constrained Lua 5.4 API. It loads maintained defaults first, then applies your personal configuration as an override.

Create a personal configuration

Your personal configuration belongs at:

${XDG_CONFIG_HOME:-$HOME/.config}/sweets/sweets.lua

Create its directory, then open sweets.lua in your editor:

mkdir -p "${XDG_CONFIG_HOME:-$HOME/.config}/sweets"

A personal file can contain only the values you want to change:

sweets.general({
    mod_key = "SUPER",
})

sweets.gaps({
    inner = 12,
    outer = 12,
    smart = true,
})

sweets.bind("MOD+D", "spawn", { "fuzzel" })

Load order

PREFIX/share/sweets/sweets.lua

${XDG_CONFIG_HOME:-$HOME/.config}/sweets/sweets.lua

If the personal file is missing, Sweets uses the installed defaults unchanged. If both files are missing, it starts with typed Rust defaults and a small set of emergency bindings.

XDG_CONFIG_HOME and HOME must resolve to absolute paths. Sweets reports a configuration path error when neither produces a usable location.

How the layers combine

The personal layer does not replace the installed configuration wholesale. Each API has a defined merge rule:

A singleton such as sweets.general, sweets.layout, or sweets.gaps may be declared once in each layer. Included files are part of their parent layer, so declaring the same singleton twice across one layer and its includes is an error.

Validate before reloading

Validate the installed and personal layers together without opening a Wayland socket or acquiring the seat:

sweets --check-config

Validate one specific file without loading the installed defaults:

sweets --check-config ./test-config.lua

A successful check prints the resolved path and exits with status 0. Syntax errors, unknown fields, wrong types, duplicate declarations, invalid values, and unsafe include paths produce a nonzero exit status with the failing source and message.

Automatic and manual reload

Sweets watches the installed file, personal file, and every included file. Saving, creating, replacing, or deleting any watched source requests a debounced reload.

Reload manually with the default MOD+Shift+R binding or IPC:

sweets msg reload

Every reload builds and validates a complete candidate before changing runtime state. An accepted candidate is applied atomically. A rejected candidate leaves the last valid configuration active.

Individual setting pages explain when a valid reload affects only future actions, future windows, or requires a compositor restart.

Errors and recovery

• Invalid startup configuration — Sweets shows the error on every monitor and starts with typed Rust defaults plus emergency bindings.
• Invalid reload — Sweets shows the error, keeps the last valid configuration, and continues watching the failed sources.
• Corrected reload — The accepted candidate replaces the active baseline and clears the recorded error.
• Unavailable filesystem notifications — Sweets falls back to polling; manual reload remains available.

Inspect the active path, origin, generation, pending state, and latest error:

sweets msg config

The session log also records rejected and accepted reloads. See the installation guide for the default log location.

Configuration API

The global sweets table is the only compositor API exposed to Lua.

Unknown API names and fields are rejected. Values are converted into validated Rust types before a configuration becomes active. Reads of undeclared Lua globals are rejected too. This catches values such as trueee, falsed, or an unquoted name instead of silently treating the affected field as absent.

local enabled = true
sweets.pointer({ follow_focus = enabled }) -- valid

sweets.input({ natural_scroll = falsed }) -- error: unknown global `falsed`

Declare variables before reading them. An explicit literal nil keeps normal Lua behavior and omits that table entry.

Lua sandbox

Configuration runs in a sandbox. Lua functions, loops, tables, and the string, table, math, and utf8 libraries are available.

The global environment is strict for reads. Local variables work normally, and a global assigned before use can be shared with later included files. Reading a missing global rejects the complete candidate and reports the source line.

Filesystem, process, and native-module access are not exposed. This includes io, os, package, require, debug, dofile, loadfile, and load. Sweets also removes protected calls and other functions that could bypass resource enforcement, including pcall, xpcall, collectgarbage, and print.

Use sweets.include(...) instead of require or dofile. Use sweets.exec_once(...) or a spawn binding to start programs. Commands are direct argument arrays and are not interpreted by a shell.

Each complete load is limited to:

• 5 million Lua instructions
• 250 milliseconds of evaluation time
• 16 MiB of Lua-managed memory
• 128 nested Lua calls
• 32 configuration sources and 16 levels of include nesting
• 256 KiB per source file and 512 KiB across all sources

Exceeding a limit rejects the complete candidate like any other configuration error. Numeric settings must also be finite; math.huge, -math.huge, and 0/0 are rejected.

Next steps

• Split the configuration with bounded relative includes
• General settings for workspaces, focus, and cross-monitor behavior
• Key bindings for actions, commands, and key sequences