Why your wayfire autostart is not working

Why the wayfire.ini autostart block never runs

A Wayland desktop always has one compositor owning the screen, and that compositor reads its own startup configuration. On images before October 2024 the compositor was wayfire, which is why the INI recipe is everywhere. The October 2024 release made labwc the default on every model, and the release notes give the reason: labwc is a much better fit for the board's graphics hardware. A current image therefore boots labwc and ships no wayfire at all. That is exactly what the "command not found" result showed on a fresh build. Running sudo apt install wayfire adds version 0.9.0-unknown (Oct 7 2025) beside it. labwc's current release, 0.9.2 (October 2025), builds on wlroots 0.19.x.

Each compositor keeps its own startup file. labwc reads ~/.config/labwc/autostart and runs every line in it when the session starts. wayfire reads ~/.config/wayfire.ini, but only when wayfire is the compositor owning the session. With labwc owning the session, the INI file is never opened, so the [autostart] block never runs. Nothing complains: a file nobody reads raises no error.

The black window tells the same story from the other side. Type wayfire in a terminal and it starts a second compositor nested inside the labwc session. wlroots, the library both compositors build on, provides that window, and the title bar names it: "wlroots - WL-1". Inside the window, wayfire behaves perfectly: it reads your INI and launches Chromium into its own little session. The command was never wrong; it was filed with the wrong compositor.

Symptoms and what each one points to

• The reboot lands on the desktop, the browser never starts, and no log or dialog complains anywhere. Points to an unread configuration file: the session compositor is labwc, and labwc never opens wayfire.ini.
• wayfire --version printed "command not found" on the fresh image. The OS has shipped without wayfire since October 2024, so the desktop you are looking at cannot be wayfire.
• A black window titled "wlroots - WL-1" opens when you run wayfire by hand, with the browser inside it. wayfire is running nested inside labwc, and it read your INI as a guest.
• printenv XDG_SESSION_TYPE prints "wayland". That names the display protocol, and the answer is "wayland" under labwc and wayfire alike, so this check picks neither compositor.
• chromium-browser comes back "command not found" while chromium runs. On this OS the binary is named chromium.
• Chromium starts by hand but asks for keyring credentials at every login. That is the desktop keyring service, a separate nuisance with its own fix; see the last question on this page.

Checks that settle which compositor you run

1. Run wayfire --version before installing anything. "command not found" means the image never carried wayfire, and the running desktop is labwc. If it prints a version, either you installed it or the image predates October 2024.
2. From the desktop, run wayfire in a terminal. A black "wlroots - WL-1" window with Chromium inside proves wayfire is a guest compositor there, and that its INI works only inside that window. Close the window afterwards.
3. Prove the kiosk command by hand first: chromium --kiosk https://example.com, with your own URL. Chromium should fill the screen within about 10 seconds. This exact command is what goes into the autostart file, so settle it here.
4. Confirm Desktop Autologin is on. In raspi-config that is System Options, Boot / Auto Login, Desktop Autologin. The labwc session exists once that user logs in, and autostart runs with the session.

The fix: one line in ~/.config/labwc/autostart

The shape of the fix is the same as any Chromium kiosk autostart setup on a Linux panel; the only difference here is which file the running compositor actually reads.

1. Work in the home folder of the user that logs in at boot. Create the directory if it is missing: mkdir -p ~/.config/labwc.
2. Create or edit ~/.config/labwc/autostart. This is a plain script, so the syntax differs from the INI you wrote: no [autostart] section header, no key, no equals sign. One command per line, and a line beginning with # is a comment.
3. Put the command you confirmed by hand on one line, with its full path: /usr/bin/chromium --kiosk https://example.com. The full path removes any doubt about the search path at session start.
4. For more than one startup command, add each on its own line, in the order they should start.
5. Remove the wayfire you installed by hand: sudo apt remove wayfire. Keep it only if you plan to switch the session to it on purpose, which the next section covers.
6. Reboot. Give the session 60 seconds. Success looks like this: the desktop comes up with autologin, and within a few seconds Chromium fills the screen with no launcher, no panel and no keyring prompt.

If the browser still does not start, check where the file sits. It must be in the home folder of the user that logs in at boot; the copy in root's home folder is never read by that session. And if the kiosk broke at the OS update on a build that ran for months, the same update moved other autostart pieces too; fixing kiosk autostart after the Bookworm update walks through the rest of that breakage.

Once the browser comes up on its own, the vendor splash that shows at power-on is a separate session setting; showing only a splash screen on an embedded Linux kiosk boot covers that file.

Recommendation: on any image dated October 2024 or later, put the kiosk command in ~/.config/labwc/autostart as one line with the full binary path, and remove the manually installed wayfire package. Keep a wayfire.ini [autostart] block only where the session was deliberately switched back to wayfire through the configuration tool.

If you really want wayfire

The configuration tool keeps a Wayland screen with three choices: wayfire, labwc and X. Selecting wayfire there makes it the session compositor at the next boot. From then on ~/.config/wayfire.ini is read exactly the way the older recipes expect.

Weigh two things before switching. The apt package is 0.9.0-unknown (Oct 7 2025) while labwc is at 0.9.2, and the vendor moved to labwc because it suits the board's graphics hardware better. Your INI already works, as the nested-window test showed; the switch earns its keep only when you need a wayfire feature. Watch the kiosk across a few reboots afterwards.

Worked example: a fresh December 2025 image on an 8 GB board

The inputs, and where each comes from:

• Board: single-board computer with 8 GB RAM and a 32 GB microSD card.
• OS: 64-bit image dated December 2025, written fresh to the card.
• Session: desktop with Desktop Autologin, set in raspi-config under System Options, Boot / Auto Login, Desktop Autologin.
• Added by hand: sudo apt install wayfire, giving version 0.9.0-unknown (Oct 7 2025), then ~/.config/wayfire.ini containing [autostart] and the line foobar = chromium --kiosk https://example.com.

The rule, in words: one compositor owns the session and reads its own startup file. On this image that compositor is labwc, reading ~/.config/labwc/autostart. wayfire reads ~/.config/wayfire.ini only when wayfire owns the session.

The check chain, step by step:

1. printenv XDG_SESSION_TYPE returns "wayland". That answers the protocol question, and "wayland" is the answer under both compositors, so this step moves nothing.
2. wayfire --version before the install returned "command not found". An image carrying no wayfire cannot be running wayfire as its session, so the session compositor is labwc, so wayfire.ini is never opened at boot, so the [autostart] block never runs. This chain also explains the total silence: a file nobody reads raises no error.
3. wayfire --version after the install returned 0.9.0-unknown. Launching wayfire by hand opened the black "wlroots - WL-1" window with Chromium inside: wayfire became a nested guest, read its INI, and ran your command into its own window while labwc kept the screen.
4. The 8 GB of RAM and the 32 GB card sit outside this chain. They decide how many tabs and how much cache the kiosk has, never which file the boot reads, so swapping the card or re-imaging at the same image date changes nothing about the fault.

Result: the [autostart] block is dead configuration on this image. wayfire owned the session on zero boots.

Decision: on an image from October 2024 onward, move the command to ~/.config/labwc/autostart as the single line /usr/bin/chromium --kiosk https://example.com and drop the INI block. On an image older than October 2024, or a session deliberately set to wayfire, keep the INI block, because there wayfire owns the session and reads it at every login.

When a browser kiosk is more than the job needs

If the screen's whole job is a set of slides that changes every week or two, a menu board, a notice board, a lobby directory, the browser and its compositor are one more layer than the content needs. An offline signage display plays JPG, PNG and WebP images and MP4 video straight from a microSD or USB card. The playlist is set up once, the show starts full screen at power-on, and there is no subscription and no network in the chain. It takes no video input, so it cannot stand in for the live Chromium page. For static content it removes the compositor, the autostart file and the keyring prompt from the job entirely.

Three pointers for that route: the choosing article for an offline signage kiosk display covers the operator-view version of the decision, our lobby displays are the flush-mounted fit for reception and entrance screens, and the one-time card setup is the same idea as setting up offline playlist autostart on a signage screen.

Questions