Manifest v3, with room for real desktop applications

A package boundary is useful only when it can carry the software people actually run. Users expect a browser to open on an X11 desktop and pair with a security key. Developers need a manifest that can ask for those abilities without quietly asking for everything around them. Manifest v3 was introduced to make that request readable and enforceable.

Two changes form the base of v3. A package now names the exact OCI image that was built and signed. Desktop permissions no longer hand complete host communication sockets to the application. One makes updates predictable; the other makes the boundary visible before the application starts.

The package no longer moves under the manifest

Tags such as main and latest are useful publishing pointers, but they can refer to new bytes after every build. A manifest that names one of them can stay unchanged while the application behind it changes. That weakens review and signing while making rollback harder, because the name no longer identifies one result.

Manifest v3 uses a digest-pinned image reference instead. The manifest and signature now identify the same immutable OCI object served by the registry. Publishers can continue to build with familiar tags; their release workflow records the resulting digest in cpak.json before the package state is signed.

A permission should describe the need

A raw bus socket says where an application can send messages, not which operation it is allowed to perform. Raw X11 has a similar cost: the same connection that draws a window can expose input and other clients on the host display. v3 therefore replaced those broad switches with permissions for concrete desktop operations. Notifications, external links, file selection and host application launches each have their own path. Other session bus use can be limited to named services, objects and methods.

That direction was right, but the first v3 publication stopped too early. Removing raw X11 did not remove the applications that still depend on X11. Bluetooth could not be reduced to one authentication flow either. It also covers discovery, pairing, GATT devices, application agents and profiles that carry their own connections. A permission model has to express legitimate use as carefully as it refuses excess access.

Private paths for X11 and BlueZ

cpak 2.9.5 adds displayX11 for applications that need X11 compatibility. cpak starts a nested Xwayland display on Wayland or a nested Xephyr display on X11. The package receives that display's socket and a private authentication cookie. It never receives the host X11 socket or the authority file used by other applications.

The new bluetooth permission provides the general BlueZ API through a private proxy at the conventional system bus path. Existing BlueZ clients can use discovery, pairing, GATT, agents, profiles, signals, callbacks and file descriptors without an application-specific protocol. Calls to unrelated system services are refused, bus enumeration is hidden and raw HCI access remains outside this permission.

Neither path makes D-Bus a requirement for cpak itself. The proxy is part of the cpak binary and is started only for a package that declares Bluetooth. Hosts need BlueZ and its existing system bus for that package; headless packages and desktop applications that do not request Bluetooth gain no new dependency.

One complete 2.9 release

When this announcement was published, cpak 2.9.5 superseded 2.9.4 and completed the 2.9 line. It included manifest v3, the Discover backend, signed installer catalog work, the trust and sandbox fixes released during the week, and the new X11 and Bluetooth paths. Use the latest stable release for a new installation; the link below remains the historical 2.9.5 release.

Existing manifest v1 and v2 packages remain readable. New packages can move to v3 when their image is pinned and each removed raw socket has an explicit replacement. The official Containerpak packages, Bottles and Bottles Next already use the v3 contract, so the same rules documented for publishers are exercised by the public Store.