Skip to main content

Environment and IPC

A running kiln is scriptable from the outside: it loads its config from a fixed search order, exports its socket path to every child process, and evaluates any Lua written to that socket.

# ask a running kiln a question from a shell
kiln-client eval 'return #client.all()'

Environment variables​

Read by the compositor:

VariableDescription
KILN_BACKENDheadless, nested or drm. Unset: nested when WAYLAND_DISPLAY is set, otherwise drm. Nested needs a parent that offers wl_compositor 4, xdg_wm_base and zwp_linux_dmabuf_v1 4; DRM needs a logind session.
KILN_HEADLESS_OUTPUTSNumber of 1280x720 headless outputs to create (default 1).
KILN_DRM_DEVICEThe card to drive (/dev/dri/cardN). Default: the first card with a render node and a non-writeback connector.
KILN_XWAYLANDThe Xwayland executable (default Xwayland, found on PATH).
KILN_RCExplicit path to the config file to load; overrides the search order below.
KILN_SOCKPath for the IPC socket. Default: $XDG_RUNTIME_DIR/kiln.sock (falling back to /tmp/kiln.sock). Set it to give an instance a private socket, for example a nested session next to a headless test run.
KILN_IMAGE_BUDGET_MBImage decode cache budget in MB (default 64). A working set larger than the budget stays correct but re-decodes per frame.
KILN_PAINT_DEBUG1 logs every render pass with its damage and repaint boxes.
WAYLAND_DEBUG1 or server traces the protocol messages kiln exchanges with its clients. Other values are ignored.
LC_ALL, LC_CTYPE, LANGChecked in that order to build the keyboard compose table (dead keys). A locale with no compose table, such as C, leaves compose off.

Set for child processes (everything launched via core.spawn and friends):

VariableDescription
WAYLAND_DISPLAYThe compositor's Wayland socket, so spawned clients connect to this kiln.
DISPLAYThe Xwayland display, when XWayland is available. The display number is reserved at startup; the X server itself starts on the first X client.
XDG_ACTIVATION_TOKENSet only for core.spawn_with_token children, so the launched client can raise itself as user-initiated.

Read by the default config, not the compositor:

VariableDescription
KILN_WALLPAPERPath to a wallpaper image; the default config's backdrop recipe reads it and draws the image behind every client. A custom rc.lua only honors it if it does the same.

Config search order​

First hit wins:

  1. KILN_RC (used verbatim if set and non-empty)
  2. $XDG_CONFIG_HOME/kiln/rc.lua when XDG_CONFIG_HOME is set, otherwise ~/.config/kiln/rc.lua
  3. The compiled installed default, <datadir>/kiln/rc.lua
  4. kilnrc.lua in the working directory

Flags​

FlagDescription
-s <command>Run a startup command once the compositor is up.
-hPrint the usage line and exit.
kiln -s 'foot'

IPC: the eval socket​

kiln listens on a unix socket (mode 0600, owner only) and evaluates whatever Lua you send, inside the same VM that runs your config: a live REPL into the config VM, and everything in this reference is drivable over it. The same socket also carries a fixed command surface for the kiln-client CLI; commands travel wrapped in kiln_ipc(...), so bare text is always read as Lua.

The protocol:

  1. Connect to the socket and write Lua source.
  2. Half-close the write side (send EOF). The compositor evaluates on half-close.
  3. Read one reply, then the connection closes.

Evaluation tries expression form first (so 1+1 answers 2), then statement form, so both expressions and statements work. The reply is the results tab-joined through tostring with a trailing newline, or ERROR: <msg> on a load or runtime error, Replies have no size limit. The CLI's eval verb takes a Lua chunk, so write eval 'return 6*7' there; the raw socket (and scripts/kiln-eval in the source tree) accepts 6*7.

Use the installed CLI (or ./build/kiln-client in the source tree). Select the instance with KILN_SOCK or kiln-client -s PATH (not the same as kiln -s):

kiln-client eval 'return core.output.list()[1].name'
kiln-client eval 'core.spawn({ "foot" })'
kiln-client eval 'require("kiln").notify{ title = "hi", message = "from IPC" }'
warning

Anything that can connect to the socket evaluates arbitrary Lua in your compositor, including while the screen is locked. The 0600 mode keeps that to your own user; do not loosen it.

See also​