Run GTK Apps in a Browser with broadwayd

Broadwayd runs GTK applications through a browser tab instead of a normal window, using GTK's Broadway backend. This guide covers starting a session, connecting an app, choosing a custom port or Unix socket, and adding the password protection the installed command supports. Allow about fifteen minutes.

You need the libgtk-3-bin package, a GTK application such as gtk3-demo, and a browser on the same host or a deliberately configured network path. The examples use Ubuntu's libgtk-3-bin version 3.24.41-4ubuntu1.3. Starting broadwayd is an ordinary user operation: do not use sudo unless your own service layout specifically requires a privileged account.

1. Check the installed command

Confirm which executable will run and inspect the local option spelling:

$ command -v broadwayd
/usr/bin/broadwayd
$ broadwayd --help
Usage:
  broadwayd [OPTION...] [:DISPLAY] - broadway display daemon

The manual's portable form is broadwayd [--port PORT] [--address ADDRESS] [--unixsocket ADDRESS] [:DISPLAY], and the installed help shows short forms for the same three options. Keep the display argument separate from the options: a display is written like an X display, for example :5, and the default is :0.

2. Start a private local session

Choose a display number that is not already in use. This keeps the server attached to the terminal so Ctrl-C is an obvious way to stop it:

$ broadwayd :5
Listening on /run/user/1000/broadway6.socket

The numeric part of the socket path is implementation output and can differ from the display you selected; the useful checkpoint is that broadwayd stays running and reports it is listening. In another terminal, start the GTK program with the Broadway backend and the same display:

$ GDK_BACKEND=broadway BROADWAY_DISPLAY=:5 gtk3-demo

Now open http://127.0.0.1:8085 in a browser on the same machine, as the manual documents for display :5. Keep the server and application terminals open while you use the session. On another display, calculate the documented default port as 8080 + (DISPLAY - 1), then check the actual listener rather than guessing.

To stop the session, close the GTK application and press Ctrl-C in the terminal running broadwayd. This ends the display server; it does not uninstall GTK or alter the application.

3. Set the HTTP port explicitly

An explicit port avoids confusion when a display number has already been chosen elsewhere in your setup:

$ broadwayd --port 18085 :5
Listening on /run/user/1000/broadway6.socket

With that command, use http://127.0.0.1:18085 in the browser. The port option changes where the HTTP service listens; it does not change BROADWAY_DISPLAY, so the GTK application still needs BROADWAY_DISPLAY=:5. Verify the choice from a second terminal without changing state:

$ ss -ltn | grep ':18085 '
LISTEN 0 128 127.0.0.1:18085 0.0.0.0:*

Your queue and address columns may differ. If nothing matches, check the broadwayd terminal for a bind error and choose an unused port. Do not start a second server on the same display and port while the first is still running.

4. Bind deliberately when another host needs access

The default HTTP address is loopback, http://127.0.0.1:PORT, which is a useful safety boundary: a browser on another machine cannot reach it. If you genuinely need a remote browser, provide an address understood by your installation and make the exposure part of your network security plan:

$ broadwayd --address 192.0.2.10 --port 18085 :5

Replace 192.0.2.10 with an address actually assigned to the host, not an arbitrary public one. The manual says --address replaces the default HTTP address.

5. Use a Unix socket where HTTP is not required

On Unix-like systems, --unixsocket selects a Unix domain socket and overrides both --address and --port:

$ broadwayd --unixsocket /tmp/broadwayd-session.socket :5

Use a socket path writable by the account running broadwayd and accessible to the intended client. Check that the path is actually a socket, not an ordinary file:

$ test -S /tmp/broadwayd-session.socket && echo 'Broadway socket exists'
Broadway socket exists

This option is Unix-specific and is not a second listener alongside HTTP. Because it overrides the network options, do not expect a browser to connect to the port from the earlier example. Treat a socket path in a shared directory as security-sensitive: choose permissions and ownership deliberately, and remove an unused socket after stopping the server if your system does not clean it up.

6. Add password protection before sharing a session

The manual supports a crypt-style password hash in $XDG_CONFIG_HOME/broadway/.passwd, or $HOME/.config/broadway/.passwd when XDG_CONFIG_HOME is unset. Create the directory as the account that will run broadwayd:

$ mkdir -p "$HOME/.config/broadway"
$ openssl passwd -1 > "$HOME/.config/broadway/.passwd"
$ chmod 600 "$HOME/.config/broadway/.passwd"

Type the password when OpenSSL asks for it. The redirection stores the generated hash, not the clear-text password, and chmod limits the file to its owner. Check the result without printing the hash:

$ test -s "$HOME/.config/broadway/.passwd" && echo 'Broadway password hash is present'
Broadway password hash is present

Restart broadwayd after creating or changing the file, then test authentication with a private browser window. Password protection is not a reason to use an unencrypted public network: the manual describes the file format, but this installed help does not promise TLS, so keep the session on a trusted route or add an appropriate encrypted transport.

7. Diagnose the usual failures

• Browser connection refused. Usually means broadwayd is not running, the port is wrong, or the service is bound to loopback while the browser is elsewhere. Check the server terminal, then run ss -ltn as the same user. If another process owns the port, identify it before stopping it, or choose a different port.
• Browser loads but no GTK window appears. Check the application was launched with GDK_BACKEND=broadway and that its BROADWAY_DISPLAY matches the server display. An existing graphical session does not automatically make an application use Broadway. Do not add sudo to the application command as a troubleshooting reflex; it can change its environment and file ownership.
• Unix socket test fails. Check the parent directory, the exact path, and whether a stale path remains from an earlier run. Do not delete a path blindly in a shared directory: confirm its type with stat, identify its owner, and remove it only once you know the old server has stopped.