Running carrot#

Starting a session#

Pick Carrot at your display manager's session list; every install channel registers the entry. No display manager works too: switch to a free TTY and run carrot. Either way it claims the logind session (TakeControl), flips the VT into graphics mode, and starts listening:

carrot: 0.1.0 built 2026-07-10 21:34
listening on wayland-1
carrot: vulkan: /run/opengl-driver/share/vulkan/icd.d/intel_icd.x86_64.json for xe

If you installed with Nix, the session also appears in display managers via the bundled carrot.desktop entry. Without a logind session, carrot tries direct device access instead, which covers headless and root setups.

What a session sets up#

A Wayland socket named wayland-N in $XDG_RUNTIME_DIR, picking the first free N with lockfile arbitration.
WAYLAND_DISPLAY, XDG_CURRENT_DESKTOP=carrot, and XDG_SESSION_TYPE=wayland in the compositor's environment, inherited by everything it spawns.
The IPC socket at $XDG_RUNTIME_DIR/carrot.$WAYLAND_DISPLAY.sock.
An input-injection socket (libei protocol) at $XDG_RUNTIME_DIR/eis-0, advertised via LIBEI_SOCKET, for launchers and remote-desktop tools.
The session environment (WAYLAND_DISPLAY, XDG_CURRENT_DESKTOP, and DISPLAY once XWayland is up) is pushed to D-Bus activation and the systemd user manager, so portals and bus-activated apps find the session.

XWayland starts with the session; X11 apps get DISPLAY automatically.

VT switching#

Ctrl+Alt+F1 through Ctrl+Alt+F12 switch virtual terminals. This is hardcoded on purpose: no config mistake can take it away from you.

Logs and crash reports#

carrot logs to stderr: your terminal from a TTY, the journal under a display manager. The last 256 KB of it also stay in memory, and if carrot ever panics, the hook writes the panic message, a backtrace, and that stderr tail to ~/.cache/carrot/carrotCrashLogN.log (honoring XDG_CACHE_HOME). Every crash gets its own number; nothing is ever overwritten. See Troubleshooting.

Quitting#

burrow quit over IPC, or bind the quit action to a key.
SIGINT or SIGTERM (for example kill <pid> from another VT) trigger the same graceful shutdown.

Diagnostic subcommands#

The binary doubles as its own test bench. Each probe runs standalone and exits:

Command	What it checks
`carrot --version`	prints the version and exits
`carrot check-config [path]`	parses your config (or the given file) and prints every error; exit 0 clean, 1 broken
`carrot install [--prefix DIR] [--root DIR]`	writes the binaries, session entry, and portal registration under the prefix; see Installation
`carrot doctor`	walks the whole GPU bring-up without starting a session, streaming to stderr and writing a numbered report (`~/.cache/carrot/carrotDoctorN.log`, with a copy in `$HOME`) ready to attach to a bug
`carrot render-probe`	brings up Vulkan headless and reports the renderer
`carrot drm-probe`	dumps DRM connectors, modes, and planes
`carrot spike-scanout`	standalone scanout test from a TTY
`carrot input-probe`	lists input devices and streams decoded events
`carrot dbus-probe`	exercises the D-Bus client against your session bus
`carrot xparsnip-probe`	connects to an X server as a plain client
`carrot pw-probe`	connects to PipeWire and dumps the registry
`carrot pw-pattern`	publishes a synthetic PipeWire video source
`carrot portal-probe`	exercises the screencast portal plumbing