Skip to content
Select theme
Select languageEnglish

Capabilities

Pages only get the standard Web APIs. There is exactly one way into system capabilities: the built-in acde: modules, imported the same way as node:fs:

import { fs } from 'acde:fs'
import { window } from 'acde:window'
import fs2 from 'acde:fs' // the default export is the same object

There is no acdev global, and the runtime never attaches anything non-standard to window.

Talking to other hosts needs no capability: fetch, WebSocket, and the other standard APIs work as usual, through the system's proxy when one is set. See Web compatibility.

The capabilities in your config decide which modules an app can import:

{
"capabilities": {
"fs": true,
"openFiles": true,
"open": ["notes", "viewer"]
}
}
Capability Grants
fs acde:fs. true: the app's private folder and the folders the user picks for it. { "roots": ["downloads", … ] } adds shared places; see Files and folders
terminal acde:terminal: pseudo-terminals
network acde:network: network settings, Wi-Fi (Linux only, including Dopame OS)
system acde:system: host name, time zone and clock sync, storage, the user (Linux only)
bluetooth acde:bluetooth: the adapter, pairing and devices (Linux only)
audio acde:audio: sound devices, volume, streams (Linux only)
devices acde:devices: drives (mount, eject, automount) and printers (Linux only)
power acde:power: batteries, power profiles and settings, suspend, brightness (Linux only)
input acde:input: keyboard layouts, mouse and touchpad, input methods (Linux only)
display acde:display: display modes, scale, rotation, brightness, night light (Linux only)
office acde:office: office document service (Linux only)
open Opening other apps with acde:open. true for any app, or a list of app ids
openFiles acde:openPath / acde:handlers, and open(request) without a target app: a file or a link goes to its default app
launch start in acde:launch: start native programs
slots embed in acde:launch: native programs embedded in your own window (Dopame OS only)
camera / microphone navigator.mediaDevices.getUserMedia() video / audio (not on Windows); the user is asked, see below
idleDetection IdleDetector (Linux only); the user is asked when the page calls IdleDetector.requestPermission()

Every app can import these without requesting anything: acde:window (its own window), acde:capabilities (what it has, see below), acde:apps (list() and open()), and acde:open (opening another app still needs open).

A name that is not in the table is an error in acdev check:

  • Desktop services are listed under services, not under capabilities: "services": ["clock"], then import { clock } from 'acde:clock'. The app then starts only in a desktop that runs the service. See Services.
  • Shell modules (acde:windows, acde:packages, acde:session, acde:desktops, acde:inspect, acde:desktop, acde:setDefault, acde:permissions) belong to the desktop. Only the desktop page, its services, and the apps bundled with a desktop (system apps) get them; see Desktops.

Importing a module the app has no right to fails with an AcdeError (an Error with name === 'AcdeError', code: 'forbidden', status: 403, and module, the name without acde:) whose message names the missing declaration; a module whose service stopped fails the same way with code: 'service_not_running' and status: 503 (see Errors). acdev check and acdev build report the same thing for every import in your source before anything runs:

error: app "notes": capability "clock" is not a system capability; list desktop services under services
error: src/main.js:1: app "notes": acde:terminal needs "terminal" in the capabilities of Notes
error: src/main.js:2: app "notes": acde:windows is a shell module: only the desktop, its services and system apps may import it, and Notes is not a system app

Calling a method the app has no right to is rejected with status: 403 (code: 'forbidden'), for example open('mail') when open lists only other apps.

Declaring a capability is what gives the app access to it: nothing is asked, also for shared places in fs.roots, terminal, network, launch and slots. Only the camera and the microphone ask the user, and idle detection (idleDetection, when the page calls IdleDetector.requestPermission()), which asks the same way. The apps bundled with a desktop (system apps) are not asked.

  • When: the first time a page calls navigator.mediaDevices.getUserMedia() (or request(), below); the call waits for the answer. This holds for a camera or microphone the app requires too.
  • Allowed: the decision is stored per app ($XDG_CONFIG_HOME/acde/permissions.json) and the user is not asked again.
  • Denied: getUserMedia() rejects with NotAllowedError, as in a browser. The app keeps running and stays in the app list, also when it requires the one denied.
  • Who asks: in a desktop, the desktop shows the prompt (see Desktops). In the host window of a single app, Windows asks in a dialog, a macOS host window in a sheet (Allow / Don't Allow) and a Linux host window in a desktop notification with Allow and Deny (without a notification service, nothing shows).
  • In a Dopame OS session: the camera and the microphone are not available yet, also when declared: getUserMedia() rejects at once with NotAllowedError and nothing asks.
  • In a dev session: answer with acdev allow or acdev deny (also when nothing shows, and headless), take a decision back with acdev revoke; see Debugging. Tests answer with acde.allow() (see Testing).

Everything in capabilities is required by default: if the platform lacks one, the app does not start. List the ones the app can run without in optional:

{
"capabilities": { "terminal": true },
"optional": ["terminal"]
}
  • The app also starts on a platform that lacks the capability.
  • An optional module must not be imported statically (acdev check: acde:terminal is optional ("terminal" is in optional): import it dynamically, await import('acde:terminal'), which rejects where this platform lacks it). Import it dynamically; the promise rejects while the module is unavailable.
  • camera and microphone have no module to load: the page calls navigator.mediaDevices.getUserMedia(), which asks the user the first time. See Web compatibility.
const terminal = await import('acde:terminal').then((m) => m.default, () => null) // null where this platform lacks it

Making fs optional makes its shared places optional too.

import { capabilities } from 'acde:capabilities'
capabilities.level // 1: the contract level of the runtime
capabilities.platform // 'linux' | 'darwin' | 'win32'
capabilities.mode // 'session' (Dopame OS) | 'desktop' (a desktop in the host window) | 'standalone' (a single app in the host window)
capabilities.get('terminal') // { name, kind: 'system' | 'service', state, reason, optional }
capabilities.list() // the same for every system capability and shell module, notifications, and each fs.<place> and service the app declares
await capabilities.request('camera') // asks the user for the camera or microphone; resolves with the status
state Meaning
available Declared and this platform has it (camera, microphone: and the user allowed it)
not-asked Camera or microphone, and the user was not asked yet: request() asks
asking The camera or microphone prompt waits for the user's answer
not-declared Not in the app's capabilities / services
unsupported This platform, or this way of running, lacks it
service-not-running The desktop service is not running
shell-only A shell module, and the app is not a system app
denied Camera or microphone: the user denied it, or the decision was taken back

request() of any other capability, or of one the user already answered, resolves at once with the current status.

notifications is the standard Notification API, which needs no declaration: it is available, or unsupported where this way of running shows no notifications (a single app on Windows).

Types for every module ship in the SDK, @dopame/acde-api. Reference the entry point that fits the project and your editor understands the acde:* modules it can import:

/// <reference types="@dopame/acde-api/app" />
  • @dopame/acde-api/app: the modules of an app (acde:fs, acde:window, acde:open, ...).
  • @dopame/acde-api/shell: those plus the shell modules, for a desktop and its bundled apps.
  • @dopame/acde-api: all of them.

To preview the same code in an ordinary browser:

  • Import acde: modules dynamically and fall back when the import rejects (a browser has no acde: modules):
const fs = await import('acde:fs').then((m) => m.default, () => null)
Module Purpose Docs
acde:window Your own window: title, menus, closing, state, shortcuts, events Windows
acde:capabilities What the app has, asking for optional capabilities Above
acde:fs Files Files and folders
acde:apps acde:open acde:openPath acde:handlers Other apps, opening files and links Opening apps
acde:launch Native programs Reference
acde:terminal Pseudo-terminals Reference
acde:network Networking Reference
acde:windows acde:packages acde:desktop acde:inspect acde:permissions acde:session acde:desktops acde:setDefault Shell modules: the desktop and system apps Desktops

For full signatures, see Reference: acde: modules.