Building Maktaba plugins

Status: planned. The plugin system is designed but not built yet. There is no plugin host, plugin API, SDK, mkp tool or store today. These guides describe the design in Epic 54, and the details can change before it ships.

What a plugin is

A plugin adds a function to a Maktaba home without changing Maktaba's own code. It:

• takes jobs from the queue. Your plugin declares stages. Maktaba queues a job for a stage when a stable event happens (a video was added, a transcript is ready), on a schedule, or when another of your own stages asks for it.
• has no internet. It cannot open a socket, resolve a name or make an HTTP request. It cannot see the disk. This is enforced twice: the WebAssembly runtime links no network or filesystem interfaces, and the process that runs plugins is locked down by the operating system.
• gets only the API access the admin grants. You declare capabilities such as library.read or chapters.write. The admin grants them at install, picks which libraries the plugin can see, and the API checks both on every call.

A plugin writes its results back through the API: metadata fields, tags, chapters, subtitles, artwork, suggestions for the admin to review, and its own data. It can declare a settings form and, later, read-only panels that the apps draw.

A plugin is one signed package (.mkplugin) holding a WebAssembly component, a manifest, English and Arabic strings, an icon and optional UI declared as data. You can write it in Rust, TypeScript or JavaScript, Python, or Go (TinyGo).

What a plugin cannot do

• Reach the internet, under any permission. There is no network capability.
• Change playback or streaming, or add API routes for the apps.
• Run code inside the apps. Settings forms and panels are data; Maktaba draws them.
• Run at boot or outside a job.
• Read users, sessions, tokens, secrets, file paths or machine addresses.
• Talk to another plugin, except by reading data that plugin chose to export, with a grant.

Plans and phases

The design ships in phases. Each guide marks which phase a feature belongs to.

Maktaba's own queue stages are also planned to move behind the same manifest, dispatch and plugin API as first-party plugins. That work does not change what third-party plugins can do.

What exists today

Maktaba's pipeline can load Python packages registered under the maktaba.extensions entry point group. That is a developer feature for Maktaba's own integrations: such a package runs inside the pipeline worker with full access. It is not the plugin system and is not meant for code from other people.

The guides

• The manifest and the package: the plugin contract, manifest.toml and the .mkplugin format.
• The sandbox: no internet, the OS sandbox, resource limits, crash isolation and health.
• Queue stages and the plugin API: events, schedules, how a job runs, the API interfaces, media handles, grants, settings, panels and local compute.
• Testing and packaging: the SDK, templates, the local test harness, building, packing and installing from a file.
• Publishing: signing keys, the Maktaba store, review, the catalog, the kill switch and paid plugins.

A plugin in one picture

queue job (pool "plugins")
  -> pipeline worker asks the API for a per-job token
  -> plugin host runs your component's run(stage) in a fresh sandbox
       your code calls maktaba:plugin/* imports
       the host forwards each call with the token to the plugin API
       the API checks token, capability, library scope and quota
  -> result goes back to the queue (retry, park or done)

Read more

• Epic 54 design
• Research behind the design

View the source of this page on GitHub