Nuvaka › Developer docs › Program compatibility

Program compatibility and dependencies

Every program package must declare where it runs (compat), and every version must declare what it needs (dependencies). A version with missing declarations cannot be submitted for review. The store uses them to show a summary such as "Ubuntu 22.04+, Fedora 39+ · x86_64" on the card. The app uses them to pick the right package for the device and to tell the user about missing dependencies.

Compatibility declaration (compat)#

compat is given per package, i.e. once for each platform key. There are two ways:

• while uploading, in the ?compat= query field as URL-encoded JSON;
• later, with PUT /api/programs/dev/{id}/versions/{v}/packages/{platform}/compat and the JSON as the body.

The server validates and normalizes the declaration. The normalized declaration goes into the package record and is signed.

Format#

// Windows: windows-msi, windows-exe, windows-exe-arm64, windows-msix
{ "arch": "x86_64", "os": { "minVersion": "10.0.19041" },
  "launch": { "uninstallKey": "Nuvaka GPU Control", "exe": "bin\\GpuControl.exe" }, "processName": "GpuControl.exe" }

// macOS: macos-dmg
{ "arch": "universal", "os": { "minVersion": "12.0" }, "launch": { "bundleId": "com.nuvaka.gpucontrol" } }

// Android: android-apk
{ "arch": "universal", "os": { "minSdk": 26 } }

// Linux package managers: linux-deb, linux-rpm, linux-pacman
{ "arch": "x86_64", "linux": { "distros": [ { "id": "ubuntu", "min": "22.04" }, { "id": "debian", "min": "12" } ] },
  "launch": { "desktopId": "gpu-control.desktop" }, "processName": "gpu-control" }

// AppImage: linux-appimage ("any distribution with glibc 2.31 or newer")
{ "arch": "x86_64", "linux": { "glibc": "2.31" }, "launch": { "desktopId": "gpu-control.desktop" } }

Unknown fields are rejected. Linux keys allow arch, linux, launch, processName, packageName, replaces, ui, bridge and background; Windows and macOS allow arch, os, launch, processName, ui, bridge and background; Android allows only arch and os. ui, bridge and background exist only in desktop packages (Local endpoints). The old minOsVersion field is derived from compat: minVersion on Windows and macOS, minSdk on Android, empty on Linux.

Launch details and process name#

launch is required for desktop packages (Windows, macOS, Linux). The app starts the program only from these details and never uses a path supplied by an extension.

processName is optional: the process name (not a path) used for a "running" status, e.g. GpuControl.exe or gpu-control. Both are part of compat: they go into the signed package record and are returned in packages[].compat in the detail reply. Error paths include compat.launch, compat.launch.exe and compat.processName.

Distribution families#

A distribution outside the key's family is rejected. For example, fedora in a deb package returns:

{ "success": false, "error": "compat_invalid", "path": "compat.linux.distros[1].id",
  "message": "fedora bu paket türüne uymaz; linux-deb için: debian, ubuntu, linuxmint, …" }

Error messages are in Turkish; rely on error and path in your tooling.

Example: five packages in one version#

launch is left out for brevity; every desktop package needs it.

// windows-msi
{ "arch": "x86_64", "os": { "minVersion": "10.0.19041" } }
// windows-exe-arm64 (arch implied: arm64)
{ "os": { "minVersion": "10.0.22000" } }
// linux-deb
{ "arch": "x86_64", "linux": { "distros": [ { "id": "ubuntu", "min": "22.04" }, { "id": "debian", "min": "12" }, { "id": "linuxmint", "min": "21" } ] } }
// linux-rpm
{ "arch": "x86_64", "linux": { "distros": [ { "id": "fedora", "min": "39" }, { "id": "opensuse-tumbleweed" } ] } }
// linux-pacman
{ "arch": "x86_64", "linux": { "distros": [ { "id": "arch" }, { "id": "manjaro" }, { "id": "endeavouros" } ] } }

Local endpoints: ui, bridge, background#

The program's UI and widget connect to the app through local endpoints. They are declared per package in compat: they are part of the signed package record, and their paths differ per operating system. They exist only in desktop packages (Windows, macOS, Linux); on Android these fields count as unknown fields and are rejected.

• ui: the program's UI that opens inside the Nuvaka window. Required in every desktop package of a runMode:"embedded" program.
• bridge: the bridge through which the companion extension's widget talks to the program. Required in every desktop package of a widget.kind:"extension" version.
• background: a background part the app can start with the user's consent.

Embedded UI (ui)#

// recommended: unix socket or named pipe (no port hijacking, no token needed)
"ui": { "transport": "unix", "path": "runtime:gpu-control-ui.sock", "args": ["--serve"] }          // Linux, macOS
"ui": { "transport": "pipe", "pipe": "\\\\.\\pipe\\nuvaka-gpu-control-ui", "args": ["--serve"] }  // Windows
// http: token file (handshake "file", the default with portFile)
"ui": { "transport": "http", "portFile": "gpu-control-ui.json" }
// http: handshake through an environment variable (the app starts the UI server)
"ui": { "transport": "http", "port": 47123, "handshake": "env", "args": ["--serve"], "urlPath": "/app" }

Per-user runtime directory. runtime: paths and portFile resolve against it:

• Linux: $XDG_RUNTIME_DIR (otherwise /run/user/<uid>);
• Windows: %LOCALAPPDATA%\Nuvaka\run;
• macOS: $TMPDIR (getconf DARWIN_USER_TEMP_DIR).

The app rejects any path that leaves this root (symbolic links included).

http handshake (required). It protects against port hijacking and DNS rebinding:

• handshake:"file": the program's own user-level UI server (never a root service) writes portFile with mode 0600: { "port": 47123, "token": "<at least 32 random bytes, base64url>" }. The app checks that the file is owned by the user and not open to group or others.
• handshake:"env": the app starts the UI server itself (with args) and puts NUVAKA_UI_TOKEN=<random> into its environment. Before the view opens, an unauthenticated GET http://127.0.0.1:<port>/.well-known/nuvaka-ui must return { "token": "<NUVAKA_UI_TOKEN>" }; otherwise nothing is shown. When used with portFile, the file may contain only { "port" }.
• In both modes the app proxies requests through its own private scheme, with Host: 127.0.0.1:<port> and Authorization: Bearer <token>. The token never reaches the view (webview). The program's server must reject any other Host value and requests without the token (401 or 421), and must bind only to 127.0.0.1.
• unix sockets and pipes have no token; endpoint ownership is checked instead (below).

Widget bridge (bridge)#

// Linux: system service (gpud)
"bridge": { "source": "service", "transport": "unix", "path": "/run/nuvaka-gpud/gpud.sock", "protocol": "jsonl-v1",
            "hello": { "cmd": "hello", "proto_version": 1 },
            "methods": [ { "name": "status", "readOnly": true }, { "name": "set_profile", "readOnly": false, "rateLimitPerMin": 30 } ] }
// Windows
"bridge": { "source": "service", "transport": "pipe", "pipe": "\\\\.\\pipe\\nuvaka-gpud", "protocol": "jsonl-v1", "methods": [ … ] }
// background part and a user socket
"background": { "args": ["--background"] },
"bridge": { "source": "background", "transport": "unix", "path": "runtime:gpu-control.sock", "protocol": "jsonl-v1", "methods": [ … ] }

Bridge contract (jsonl-v1) and app limits#

The extension calls the bridge with nuvaka.programs.call(method, params?), which returns a Promise. The call works only in an extension that has companionOf and the programs: "companion" permission, and that the program's installed version record names in widget.kind:"extension" with widget.extensionId (Home page widget). The app builds the request itself; the extension cannot send raw lines.

Framing: UTF-8, one JSON object per line, each line ends with \n (no raw newlines inside a line). Requests on a connection are sequential; every request line gets one reply line.

→ {"cmd":"hello","proto_version":1}                       // if hello is set: the connection's first line (unchanged)
← {"ok":true}
→ {"id":1,"method":"status","params":{}}
← {"id":1,"result":{"temp":61,"profile":"quiet"}}
→ {"id":2,"method":"set_profile","params":{"name":"perf"}}
← {"id":2,"error":{"code":"busy","message":"…"}}

• Over http (only source:"background"): each request line is the body of a POST /.well-known/nuvaka-bridge; the reply body is a single line. The handshake and the Host/Bearer rules are the same as for ui.
• Limits: params at most 64 KB, a reply line at most 1 MB, reply timeout 5 s. rateLimitPerMin is enforced per method in the app.
• Write methods (readOnly:false) can be called only after a user gesture (a click or key press, within about 1 s); otherwise gesture_required.
• Endpoint ownership: a unix socket must be owned by root or the user and must not be world-writable (runtime: sockets belong to the user; 0600 is recommended). On Windows, the pipe server's process (GetNamedPipeServerProcessId) must be an image under the program's InstallLocation. If this does not hold, the app does not connect (bridge_unavailable).

Errors arrive as a Promise rejection, with the code in error.code:

An error code returned by the program itself (e.g. busy) arrives unchanged in error.code, without a prefix.

Background part (background)#

"background": { "args": ["--background"], "persist": false }

• args: 1–16 strings (each at most 256 characters, no NUL). persist: optional bool, default false.
• The app starts only the compat.launch target with these arguments: the Exec line of the .desktop file on Linux (field codes removed), InstallLocation\exe on Windows, the bundleId on macOS. It does so without root or administrator rights and only after the user's explicit consent ("Let GPU Control run in the background?"); the user can withdraw it in settings.
• The background part starts when Nuvaka opens and stops when Nuvaka closes. With persist:true it keeps running.

Dependencies#

dependencies are given per version: when you create the version with POST …/versions, or later with PUT …/versions/{v}. The field is required. If there are no dependencies, send the empty list []; it explicitly means "no dependencies". If you never send the field, the version cannot be submitted (dependencies_required).

[
  { "kind": "driver", "name": "NVIDIA driver", "version": ">=535", "required": false, "platforms": ["windows", "linux"],
    "note": { "tr": "Yalnız NVIDIA ekran kartlarında", "en": "NVIDIA GPUs only" }, "url": "https://www.nvidia.com/drivers" },
  { "kind": "hardware", "name": "NVIDIA or AMD GPU", "required": true },
  { "kind": "runtime", "name": ".NET Desktop Runtime", "version": ">=8.0", "required": true, "platforms": ["windows"],
    "url": "https://dotnet.microsoft.com/download/dotnet/8.0" },
  { "kind": "program", "name": "nuvaka.gpu-runtime", "version": ">=1.0.0", "required": true }
]

• Up to 30 dependencies. The same kind and name pair cannot appear twice. Unknown fields are rejected.
• Declare Linux system libraries in the package's own dependency field (Depends:, Requires:, depends=()), not here. The package manager installs those. This list is for things the package manager cannot install.
• For a program dependency, the app offers to install that program first. Its package is picked by its own compat declaration. If the program you depend on is later taken down, submitting and approving new versions is refused.

Error codes#

What the store and the app see#

List cards (GET /api/programs) carry a per-OS summary built from the latest version's packages:

"compat": {
  "windows": { "arch": ["x86_64", "arm64"], "minVersion": "10.0.19041" },
  "linux":   { "arch": ["x86_64"], "distros": [ { "id": "ubuntu", "min": "22.04" }, { "id": "fedora", "min": "39" } ], "glibc": "2.31", "anyDistro": true },
  "android": { "arch": ["universal"], "minSdk": 26 }
}

The values are the lowest across the packages. anyDistro: true means there is an AppImage package, so the program runs on any distribution with a recent enough glibc. The detail endpoint (GET /api/programs/{id}) returns each package's full compat, each version's dependencies and the latest version's dependencies, with a store card attached to program dependencies.

Matching rules#

The app can decide on the device. It can also ask the server: add the device details to the detail request and the reply contains a compatibility field.

GET /api/programs/{id}?platform=linux&arch=x86_64&distro=ubuntu&distroVersion=24.04&distroLike=debian&glibc=2.39

"compatibility": {
  "compatible": true, "recommended": "linux-deb",
  "packages": [
    { "platform": "linux-appimage", "compatible": true,  "reasons": [], "warnings": [] },
    { "platform": "linux-deb",      "compatible": true,  "reasons": [], "warnings": [] },
    { "platform": "linux-rpm",      "compatible": false, "reasons": ["distro_not_supported"], "warnings": [] }
  ]
}

Parameters:

• arch: x86_64 (amd64 and x64 also work) or arm64 (aarch64 also works).
• osVersion: the build number on Windows (10.0.22631), the version on macOS (14.5), the API level on Android (34).
• distro, distroVersion, distroLike: the ID, VERSION_ID and ID_LIKE values from /etc/os-release.
• glibc: the device's glibc version.

Details you leave out are not checked. The rules apply to each package separately:

• Architecture: a universal package runs on every architecture. The same architecture fits. arm64 Windows and Apple Silicon Macs run x86_64 packages under emulation: the package fits and the warning arch_emulated is added. Any other difference fails with arch_mismatch.
• Windows and macOS: if the device version is lower than minVersion, the reason is os_too_old. Versions are compared part by part as dotted numbers.
• Android: if the API level is lower than minSdk, the reason is os_too_old.
• glibc: if the device's glibc is older than the declared one, the reason is glibc_too_old.
• deb, rpm, pacman:
  • If the distribution is listed and has a min, the device version must be at least min; otherwise distro_too_old. If the version is unknown, the warning distro_version_unknown is added.
  • If the distribution is not listed, but it or one of its ID_LIKE values belongs to the package's family, the package fits and the warning distro_family_match is added. The version is not checked in this case. Example: Linux Mint when only ubuntu is listed.
  • Otherwise distro_not_supported.
• AppImage: the distribution is ignored; only the architecture and glibc are checked.

recommended is picked among the fitting packages: exact matches first, then family matches and emulation, AppImage last. Ties follow the order of the platform key list. If no package fits, compatible is false and recommended is null.

Nuvaka Apps API v1 · last updated 2026-10-17