pc-heiniandClaude Fable 5.1
05105a6532
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018jkHZhr7ZzHGGuE2bJQmGa
105 lines
4.2 KiB
Markdown
105 lines
4.2 KiB
Markdown
# heiniremote-flatpak
|
|
|
|
Flatpak packaging for the [HeiniRemote](https://git.pc-heini.de/pc-heini/HeiniRemote)
|
|
customer agent (`de.pc_heini.HeiniRemoteAgent`) — an additional distribution
|
|
channel next to the plain release binary, with all dependencies (GStreamer,
|
|
libnice, wl-clipboard, …) pinned inside the freedesktop 25.08 runtime (24.08 ships libpipewire 1.2,
|
|
whose buffer negotiation fails against KWin 6.7 / PipeWire 1.6 hosts).
|
|
|
|
Same setup as [o3de-flatpak](https://git.pc-heini.de/pc-heini/o3de-flatpak):
|
|
a Gitea Action builds the Flatpak **without** `flatpak-builder` (no bubblewrap
|
|
needed in CI), exports it into an OSTree repo and force-pushes that to the
|
|
`pages` branch. The difference: the agent is compiled from upstream source
|
|
(newest `v*` tag, falling back to `main` while no release exists) instead of
|
|
repackaging a prebuilt archive.
|
|
|
|
## Install
|
|
|
|
> **Note:** this repository must stay **public**. Flatpak fetches the OSTree
|
|
> repo from the raw `pages` branch without any credentials — with the repo set
|
|
> to private, `flatpak remote-add` / `flatpak install` fail with a 404.
|
|
> (The agent's source lives in the private HeiniRemote repo; only the built
|
|
> binary is published here.)
|
|
|
|
From the Flatpak remote (gets updates via `flatpak update`):
|
|
|
|
```sh
|
|
flatpak remote-add --if-not-exists heiniremote \
|
|
https://git.pc-heini.de/pc-heini/HeiniRemote-AgentFlatpak/raw/branch/pages/heiniremote.flatpakrepo
|
|
flatpak install heiniremote de.pc_heini.HeiniRemoteAgent
|
|
```
|
|
|
|
Or as a single-file bundle (attached to each release of this repo, no remote
|
|
needed, but no auto-updates either):
|
|
|
|
```sh
|
|
flatpak install ./heiniremote-agent-<version>.flatpak
|
|
```
|
|
|
|
## Configure
|
|
|
|
The agent needs a server URL and device token. Inside the sandbox the config
|
|
path is:
|
|
|
|
```
|
|
~/.var/app/de.pc_heini.HeiniRemoteAgent/config/heiniremote/agent.toml
|
|
```
|
|
|
|
If a native install already left a config at `~/.config/heiniremote/agent.toml`,
|
|
the wrapper picks it up automatically (read-only). `HEINIREMOTE_SERVER_URL` /
|
|
`HEINIREMOTE_TOKEN` env overrides work as usual:
|
|
|
|
```sh
|
|
flatpak run --env=HEINIREMOTE_SERVER_URL=wss://… de.pc_heini.HeiniRemoteAgent
|
|
```
|
|
|
|
## Autostart
|
|
|
|
The native install runs as a systemd user service; the Flatpak equivalent is a
|
|
user unit wrapping `flatpak run`:
|
|
|
|
```ini
|
|
# ~/.config/systemd/user/heiniremote-agent.service
|
|
[Unit]
|
|
Description=PC-Heini Fernwartung (HeiniRemote Agent, Flatpak)
|
|
After=graphical-session.target
|
|
|
|
[Service]
|
|
ExecStart=flatpak run de.pc_heini.HeiniRemoteAgent
|
|
Restart=on-failure
|
|
|
|
[Install]
|
|
WantedBy=graphical-session.target
|
|
```
|
|
|
|
## How the sandbox is punched
|
|
|
|
Screen capture and input injection go through xdg-desktop-portal
|
|
(ScreenCast + RemoteDesktop) — that is the normal, fully sandboxed path and
|
|
needs no special permission. Two things do:
|
|
|
|
- **`--talk-name=org.freedesktop.Flatpak`** — the PTY rescue console must show
|
|
the *host*, not the sandbox. The wrapper sets `SHELL=/app/bin/host-shell`,
|
|
which execs the user's real login shell via `flatpak-spawn --host`. This is
|
|
a deliberate sandbox escape; for a remote maintenance tool the sandbox is
|
|
packaging, not a security boundary.
|
|
- **`--filesystem=xdg-config/heiniremote:ro`** — adopt a native install's
|
|
`agent.toml` (see above).
|
|
|
|
Everything else is standard: `network` (signaling + WebRTC/TURN), `wayland`
|
|
(bundled wl-copy/wl-paste), `dri` (dmabuf screencast buffers), and the
|
|
StatusNotifier names for the tray icon.
|
|
|
|
## Repo layout
|
|
|
|
| File | Role |
|
|
|---|---|
|
|
| `.gitea/workflows/build-flatpak.yml` | CI: resolve upstream version → cargo build → assemble → publish `pages` + release bundle. Daily schedule picks up new upstream versions. |
|
|
| `scripts/get-latest-version.sh` | Newest upstream `v*` tag, else `main` HEAD (`0.0.0-git.<date>.<sha>`). |
|
|
| `scripts/make-flatpak.sh` | bwrap-free assembly: `build-init` → copy files → `build-finish` → `build-export`. |
|
|
| `heiniremote-wrapper.sh` | Entry point: host-shell `$SHELL` override + config adoption. |
|
|
| `host-shell.sh` | `flatpak-spawn --host` bridge for the PTY console. |
|
|
| `de.pc_heini.HeiniRemoteAgent.*` | Desktop file, AppStream metainfo (version stamped by CI), icon. |
|
|
|
|
Builds track the newest upstream `main` commit; a push to this repo (even a README change like this line) triggers a fresh build.
|