Package as a Flatpak, and decide where the agent runs #5

New issue

Open

opened 2026-08-19 15:38:53 +00:00 by dusan · 0 comments

dusan commented

2026-08-19 15:38:53 +00:00

Owner

Context

Terminalko installs three binaries that work together:

Binary	What it does
`terminalko`	the window: GTK4, libadwaita, VTE
`terminalko-agent`	owns every pseudo-terminal, spawns the sessions, outlives windows
`terminalkoctl`	looks at and steers sessions from a shell

The window starts the agent on demand (crates/terminalko/src/link.rs,
agent_program(): TK_AGENT_PATH, else a binary beside the window, else PATH)
and talks to it over a unix socket in $XDG_RUNTIME_DIR/terminalko/, passing pty
descriptors with SCM_RIGHTS. See docs/spec/session-agent.md.

An rpm exists and is verified (build-aux/terminalko.spec); meson install
works. There is no Flatpak manifest.

The decision to make first

A session may be local, ssh, a container (podman, docker, toolbox,
distrobox) or root (sudo, run0, pkexec) — see docs/spec/session-types.md.
Inside a sandbox, none of the last three work usefully: there is no podman, no
toolbox, no polkit agent, and the user's ssh keys and agent are not there either.

So either:

(a) the agent runs on the host. The window stays sandboxed and starts the
agent with flatpak-spawn --host, which needs --talk-name=org.freedesktop.Flatpak.
Ptyxis does this — its ptyxis-agent runs on the host — so the shape is proven.
Consequences to work through:

the socket must be reachable from both sides: $XDG_RUNTIME_DIR inside the
sandbox is not the host's, so the path needs deciding (the host's real
runtime directory, exposed into the sandbox, or a path under ~/.var/app);
the host agent must be found: it is inside the Flatpak, so the spawn is
something like flatpak-spawn --host flatpak run --command=terminalko-agent me.dusansimic.terminalko, or the agent binary is exported to the host;
TK_AGENT_PATH and TK_RUNTIME_DIR (both already supported) are probably how
this gets wired.

(b) the agent stays in the sandbox. Simple to package, and container, ssh and
root sessions become useless or misleading. If this is chosen, the session types
must be disabled in a sandboxed build rather than left to fail — a menu that
offers containers that cannot work is worse than one that does not offer them.

Option (a) is the useful one; option (b) is only worth it as a stopgap. Whichever
is chosen, write it down in docs/spec/session-agent.md, which currently says
Flatpak is a later concern.

Work

build-aux/me.dusansimic.terminalko.yml (or .json) against a current GNOME
runtime, building with meson as the rpm does. The Rust dependencies need
handling: either a cargo-sources.json generated by
flatpak-builder-tools/cargo with --no-network builds, or vendoring.
Finish sockets and permissions: Wayland, --socket=fallback-x11,
--device=dri, --talk-name=org.freedesktop.Flatpak for option (a),
--talk-name=org.freedesktop.Notifications for exit notifications, and
whatever the socket path decision needs.
Make sure the desktop entry, AppStream metainfo, icons and the three GSettings
schemas are installed and validated inside the sandbox — the rpm build caught
that two relocatable schemas were missing from meson install, so check.
terminalkoctl on the host: flatpak run --command=terminalkoctl works, but
it needs the same socket path as the agent.

Acceptance criteria

flatpak-builder builds the manifest from a clean checkout and the result runs.
A local session works: the shell starts, output appears, resizing reflows.
A session survives closing its window and reattaches with its output replayed —
the whole point of the agent, so it must hold inside a sandbox too.
Container and ssh sessions either work (option a) or are not offered
(option b). Nothing may be offered and then fail because of the sandbox.
Exit notifications appear, or the permission is deliberately absent and the
code path already tolerates that (it does: it checks whether anything owns
org.freedesktop.Notifications).
docs/spec/session-agent.md records which option was taken and why.

Notes

flatpak-builder is not installed on the development machine as of writing;
a manifest that has never been built is worth less than no manifest.
Terminalko is BSD-2-Clause and links LGPL libraries (GTK, libadwaita, VTE)
dynamically; a Flatpak must keep them as separate shared libraries rather
than statically merged, and ship their licence texts. See CONTRIBUTING.md.

## Context Terminalko installs three binaries that work together: | Binary | What it does | |---|---| | `terminalko` | the window: GTK4, libadwaita, VTE | | `terminalko-agent` | owns every pseudo-terminal, spawns the sessions, outlives windows | | `terminalkoctl` | looks at and steers sessions from a shell | The window starts the agent on demand (`crates/terminalko/src/link.rs`, `agent_program()`: `TK_AGENT_PATH`, else a binary beside the window, else `PATH`) and talks to it over a unix socket in `$XDG_RUNTIME_DIR/terminalko/`, passing pty descriptors with `SCM_RIGHTS`. See `docs/spec/session-agent.md`. An rpm exists and is verified (`build-aux/terminalko.spec`); `meson install` works. There is **no Flatpak manifest**. ## The decision to make first A session may be **local**, **ssh**, a **container** (podman, docker, toolbox, distrobox) or **root** (sudo, run0, pkexec) — see `docs/spec/session-types.md`. Inside a sandbox, none of the last three work usefully: there is no podman, no toolbox, no polkit agent, and the user's ssh keys and agent are not there either. So either: **(a) the agent runs on the host.** The window stays sandboxed and starts the agent with `flatpak-spawn --host`, which needs `--talk-name=org.freedesktop.Flatpak`. Ptyxis does this — its `ptyxis-agent` runs on the host — so the shape is proven. Consequences to work through: - the socket must be reachable from both sides: `$XDG_RUNTIME_DIR` inside the sandbox is *not* the host's, so the path needs deciding (the host's real runtime directory, exposed into the sandbox, or a path under `~/.var/app`); - the host agent must be found: it is inside the Flatpak, so the spawn is something like `flatpak-spawn --host flatpak run --command=terminalko-agent me.dusansimic.terminalko`, or the agent binary is exported to the host; - `TK_AGENT_PATH` and `TK_RUNTIME_DIR` (both already supported) are probably how this gets wired. **(b) the agent stays in the sandbox.** Simple to package, and container, ssh and root sessions become useless or misleading. If this is chosen, the session types must be *disabled* in a sandboxed build rather than left to fail — a menu that offers containers that cannot work is worse than one that does not offer them. Option (a) is the useful one; option (b) is only worth it as a stopgap. Whichever is chosen, write it down in `docs/spec/session-agent.md`, which currently says Flatpak is a later concern. ## Work 1. `build-aux/me.dusansimic.terminalko.yml` (or `.json`) against a current GNOME runtime, building with meson as the rpm does. The Rust dependencies need handling: either a `cargo-sources.json` generated by `flatpak-builder-tools/cargo` with `--no-network` builds, or vendoring. 2. Finish sockets and permissions: Wayland, `--socket=fallback-x11`, `--device=dri`, `--talk-name=org.freedesktop.Flatpak` for option (a), `--talk-name=org.freedesktop.Notifications` for exit notifications, and whatever the socket path decision needs. 3. Make sure the desktop entry, AppStream metainfo, icons and the three GSettings schemas are installed and validated inside the sandbox — the rpm build caught that two relocatable schemas were missing from `meson install`, so check. 4. `terminalkoctl` on the host: `flatpak run --command=terminalkoctl` works, but it needs the same socket path as the agent. ## Acceptance criteria - `flatpak-builder` builds the manifest from a clean checkout and the result runs. - A local session works: the shell starts, output appears, resizing reflows. - A session survives closing its window and reattaches with its output replayed — the whole point of the agent, so it must hold inside a sandbox too. - Container and ssh sessions either **work** (option a) or are **not offered** (option b). Nothing may be offered and then fail because of the sandbox. - Exit notifications appear, or the permission is deliberately absent and the code path already tolerates that (it does: it checks whether anything owns `org.freedesktop.Notifications`). - `docs/spec/session-agent.md` records which option was taken and why. ## Notes - `flatpak-builder` is **not installed** on the development machine as of writing; a manifest that has never been built is worth less than no manifest. - Terminalko is BSD-2-Clause and links LGPL libraries (GTK, libadwaita, VTE) **dynamically**; a Flatpak must keep them as separate shared libraries rather than statically merged, and ship their licence texts. See `CONTRIBUTING.md`.

No labels

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

dusan/terminalko#5

No description provided.

Rows
Columns