How PurposeOS is put together

A thin local executor, a set of small daemons, and apps that declare what they can do. Everything talks over Unix sockets on your machine.

The layers

What happens when you speak

1. 1

   listend Hears your wake word

   Audio features live in its own memory for a few seconds. Only “heard it” crosses over.

2. 2

   voiced Turns speech into text, live

   A 120 second ring buffer in RAM. A fast engine shows words as you speak, Whisper replaces them with the final text.

3. 3

   actiond Decides what you meant

   Matches your sentence to an intent that an app declared. Opens, closes, or starts a capture.

4. 4

   execd Runs it, only if allowed

   Each app has its own socket. The executor checks what that app may call, then logs the command without its content.

5. 5

   your app Does the work

   Journal saves one file per entry under its own data folder. Nothing else can read it.

The executor

The executor is a local-only command runner. It never opens a TCP port. A command is data (an id, an action and a JSON input), so it can be retried, logged and replayed.

• Runtimes are pluggable. A runtime can be a C-ABI library, a WASM component (WASI preview 2) or a service on a Unix socket.
• Retry, then fall back. A transient error retries on the same runtime with backoff, then moves to the next. unavailable skips ahead. permanent stops.
• Plugins are checked before they load. Manifest version, then the binary header (format and CPU, before any code runs), then required symbols, then the plugin's own ABI version, then every declared action.
• New services need no restart. If an action is unknown, the executor rescans its plugin folders once and retries. At most one rescan per half second.

Where things live

~/.local/share/purpose/apps/<id>/        app code (read-only) and data/
~/.local/share/purpose/plugins/          generated service manifests
~/.local/share/purpose/session.d/        generated start hooks
~/.config/purpose/                       settings, wake word, keys
~/.local/state/purpose/activity_log/     encrypted daily logs
$XDG_RUNTIME_DIR/purposeos/execd.sock    the main executor socket
$XDG_RUNTIME_DIR/purposeos/services/     one socket per service
$XDG_RUNTIME_DIR/purposeos/apps/<id>.sock  each app's own executor socket

Install model

Everything ships prebuilt as static executables. Nothing is compiled on your machine. Apps install per user with no root, from a checksum-verified .papp bundle, and an upgrade carries the app's data across.

The installer is layered on stock Arch and records every change in a ledger, so cleanup.sh removes exactly what it added and restores files it replaced.