Configuration

turtile uses a configuration file written in the libconfig format , which must be explicitly passed to the compositor with the -c [path/to/config.cfg] option. This guide explains each configuration option available and provides examples for customization.

Loading the Configuration

To load a configuration file, start the compositor with the -c flag, followed by the path to the configuration file:

turtile -c path/to/config.cfg

Sample Configuration

The configuration file has several sections that control application behavior, workspace setup, keyboard shortcuts, and appearance.

autostart = (
  "kitty",
  "nautilus",
);

workspaces = (
  "main",
  "work",
  "fun",
);

keybinds = (
  {mod = [], key = "Escape", cmd = "./build/ttcli exit"},
  {mod = ["alt"], key = "Return", cmd = "kitty"},

  {mod = ["alt"], key = "Tab", cmd = "./build/ttcli window cycle"},
  {mod = ["alt"], key = "q", cmd = "./build/ttcli window kill"},

  {mod = ["alt"], key = "1", cmd = "./build/ttcli workspace switch main"},
  {mod = ["alt"], key = "2", cmd = "./build/ttcli workspace switch work"},
  {mod = ["alt"], key = "2", cmd = "./build/ttcli workspace switch fun"},
  {mod = ["alt", "shift"], key = "1", cmd = "./build/ttcli window move-to main"},
  {mod = ["alt", "shift"], key = "2", cmd = "./build/ttcli window move-to work"},
  {mod = ["alt", "shift"], key = "3", cmd = "./build/ttcli window move-to fun"},
);

background_color = (0.2, 0.2, 0.3);

Configuration Options

autostart

Defines a list of applications to start automatically when the compositor launches.

Format: A list of strings, where each string is the command to launch an application.

autostart = (
  "kitty",
  "nautilus",
);

workspaces

Specifies the names of workspaces that will be available in the compositor. Each name in the list represents a workspace that can be switched to or configured independently.

Format: A list of strings, each representing a workspace name.

workspaces = (
  "main",
  "work",
  "fun",
);

keybinds

Defines keybindings for actions within the compositor, such as switching workspaces or launching applications. Each keybinding specifies a modifier (optional), a key, and a command to execute.

Format: A list of objects, each containing:

• mod: A list of modifier keys (e.g., mod4 for the “Super” key). Leave empty for no modifier.
• key: The key to bind (e.g., “1”). It’s important to capitalize the first letter of keys like “Escape”
• cmd: The command to execute when the key combination is pressed, this can be any shell command.

keybinds = (
  {mod = [], key = "Escape", cmd = "./build/ttcli exit"}, 
  {mod = ["alt"], key = "Return", cmd = "kitty"},
  {mod = ["alt"], key = "Tab", cmd = "./build/ttcli window cycle"},
);

background_color

Sets the background color of the compositor in RGB format, with values between 0 and 1.

Format: A list of three floating-point numbers, representing the RGB color channels.

background_color = (0.2, 0.2, 0.3);  # A muted dark blue