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.

Checkpoint: if command -v prints nothing, stop and install or enable the package through your normal system administration process. Do not copy a binary from an unrelated host.

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.

Warning: do not expose an unauthenticated desktop session to an untrusted network. Prefer a firewall rule, an SSH tunnel, or a private network, and test the exact route before using real applications. There is no service unit or persistent configuration here: Ctrl-C removes the running listener, and any firewall rule or tunnel you added outside this guide needs its own rollback.

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.

Warning: do not paste the password or the hash into shell history, tickets or logs. If either is exposed, stop broadwayd, replace the hash with a freshly generated one, and restart the server. To remove this guide's password configuration, stop broadwayd first and delete only the specific file after confirming no other Broadway session uses it.

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.

Done means

Confirmed broadwayd is installed and its local option syntax is understood.
Kept a display server running on the chosen display with the GTK application using the same BROADWAY_DISPLAY.
Matched the browser URL to the actual HTTP port, or used a Unix socket deliberately instead.
Avoided accidental remote access, and gave any shared session a protected route and password hash.
Stopped the server with Ctrl-C and removed only the session-specific password or socket artefacts when finished.