App Development

rumahl provides a secure, isolated environment for extending the platform. This document is the starting point for building apps and plugins.

Apps vs. Plugins

Decision guide: need a database, background processes or your own UI? Build an App. Want a widget, an automation or an ORA tool? Build a Plugin.

The app manifest

Every app declares itself in a manifest.json — name, permissions and lifecycle hooks:

{
  "name": "my-app",
  "version": "1.0.0",
  "permissions": ["AppStorageRead", "AppStorageWrite"],
  "lifecycle_hooks": {
    "hooks": [{ "event": "on_system_event", "filter": "security.*" }]
  }
}

The reference example is the Notes app (apps/examples/apps/rumahl-notes) — it demonstrates app storage, health checks and app token auth.

The ora.* SDK surface

import { rumahlClient } from "rumahl-sdk";

const ora = rumahlClient({ baseUrl: "http://localhost:8126" });
ora.setAppId("my-app");

await ora.notifications.send({ title: "Backup done", message: "All good" });
const { files } = await ora.files.list({ folderId: null });

Security & permissions

• Every SDK call is permission-checked at the API gateway — before your code runs

• Request permissions at runtime with ora.permissions.request(...) — the user sees an allow/deny dialog

• Store credentials in the secrets vault, never in the bundle or in logs

• Destructive operations require explicit user confirmation

Publishing to the Store

1. 1Register as a developer in the developer dashboard

1. 1Submit your app — the review checks safety, privacy, content and quality

1. 1Answer the review; rejections are reasoned and appealable within 14 days

1. 1Keep your app maintained — updates and security patches are expected