# Managing plugins

This page is for the people who run a Bookclerk server. It covers how
plugins are installed, approved, enabled, configured and placed on the
hosts of a library, where they live on disk, and how isolation is
configured.

What a plugin may ask for is in
[Capabilities and consent](/docs/plugins/capabilities/index.md). How the jail works
is in [The guest jail](/docs/internals/guest-jail/index.md).

## Installing plugins

A third-party plugin is **installed** into the library once. A package
version is resolved and verified once, recorded in the library database,
and run byte-for-byte the same on every node.

Installing doesn't touch this node's `plugins/`. **Deploying** decides
which nodes run it (see [Placement](#placement)).

```sh
bookclerk plugins install cargo:bookclerk-plugin-source-example@1.2.0 --approve-capabilities
bookclerk plugins install example --archive ./example.tar.gz \
    --manifest ./bookclerk-package.json --allow-unverified-publisher
bookclerk plugins versions [example]         # every installed version; * marks the active one
bookclerk plugins update example [--to 1.3]  # install a newer registry version and activate it
bookclerk plugins rollback example 1.2.0     # activate an earlier installed version
bookclerk plugins approve example --yes      # record consent on the active version
bookclerk plugins deploy example             # run the default instance on this node
bookclerk plugins uninstall example          # clear the active version; undeploy everywhere
```

### What installing checks

1. **Trust.** Installing checks the trust policy.
2. **Artifacts.** It fetches each artifact and verifies it. A registry
   artifact must match the archive digest its package manifest declares.
   A local archive's digest is computed from the operator's own file.
3. **Contents.** The node extracts the archive to scratch, parses
   `plugin.toml`, checks that the file the package manifest names as
   `executable` is present, and computes the payload-root digest.
4. **Same plugin on every platform.** Every artifact must carry the same
   plugin id and version, and the same `plugin.toml` apart from its launch
   line (`command` and `args`). The version records the first artifact's
   manifest, and the host decides from it (credential sharing, settings,
   capabilities) while each node runs its own platform's artifact, so a
   package whose artifacts declare anything else differently, such as
   `credentials`, is refused.
5. **Record.** The version row records the PluginKey, the version from
   `plugin.toml`, the manifest and settings schema, one artifact per
   target (URL, archive digest, payload-root digest), the coordinate it
   came from, and the consent grant.

Installing the same version twice does nothing. Installing different bytes
under an installed version is refused.

A local archive's path names no stable plugin, so a later archive of an
alias that is already installed reuses that alias's key. One alias names
one plugin: a version may not take an alias another plugin's active
version answers to.

### Artifact URLs

- A registry artifact keeps its download URL. Installing streams it to
  disk (at most 512 MiB) and resumes a dropped or timed-out transfer from
  where it stopped; each attempt has two minutes, and the archive's digest
  is checked once it is complete.
- A local archive up to 1 MiB is stored in the database
  (`blob:sha256:<hex>`), so every node can materialize it. It is split into
  chunks small enough for the database plugin's cell, request and result
  limits, so it fits every adapter, D1 and the host minimums included.
- A larger local archive is referenced in place as a `file://` URL. Only
  nodes that see that path (shared storage) can materialize it; the others
  record an `error` observation.

A branch node of another library fetches an owner's `https:` artifact only
when both are true:

- its host operator approved that exact URL, archive digest and payload
  digest (they are part of the reviewed request);
- neither its host nor any redirect hop's host is, or resolves to, a local
  or private address. This is checked on the addresses actually dialed,
  with no proxy.

See [Host consent](/docs/adr/control-plane/index.md#host-consent).

### The active version

Each PluginKey has at most one active version.

- The first installed version becomes active. A later one becomes active
  with `install --activate`, `update` or `rollback`.
- An automatic install (an operator package, or `install` without
  `--activate`) never moves the active version back to an older one.
- Changing it publishes `install.changed` to every node queue, and each
  node respawns its deployments of that plugin from the new digest.

### Consent rides on the version

A version with no approved grant is recorded but not spawned. Nodes report
an `error` observation until it is approved.

A new version carries the previous active version's grant forward when
that grant still covers everything the new version requests. A version
that asks for more needs a fresh `approve`.

### Materialization

When a present deployment needs the active version, the node:

1. Fetches the artifact for its own target.
2. Extracts it under `plugins/.staging/version-<digest>.<pid>`.
3. Verifies the payload-root digest against the row.
4. Renames the tree to `plugins/.versions/<digest>`.

A partial extract never reaches the final path, and a cached digest is
immutable. Digests no deployment on the node references are swept after
an hour.

The host recomputes an installed tree's payload-root digest each time it
discovers plugins. Every pass walks the tree and checks every entry again
(symlinks, special files, added or removed files). On Unix, a file whose
inode, size, modification time and change time are unchanged reuses the
content digest from its last read. A write moves the change time, even
when the modification time is put back, and a file written in the last 2 s
is read again each time. The reuse relies on installed trees staying
read-only once materialized: a later write through a shared memory mapping
may not move the timestamps again.

### Health is an observation

A guest that fails health records an `error` observation, and the version
stays active. Nothing rolls back automatically: use `plugins rollback` to
activate an earlier version.

### Staged packages

Platform guests (`local`, `sqlite`, `embedder`) ship with the node, and
`cargo stage-plugins` stages development trees under `plugins/<fs-id>`.
Those are staged on one machine, not installed into the library. Their
provenance is `platform_bundled`, `verified_staged` or
`local_development`, while an installed version is `installed`.

### Install API

The daemon offers the same operations to an operator session:

| Method | Path | Body / result |
| --- | --- | --- |
| `GET` | `/api/config/plugins` | Every installed plugin: `active_version` and its `versions` (each with `active`, `approved`, and artifacts) |
| `POST` | `/api/config/plugins` | Install: `{coordinate}` or `{package}` (a directory under `plugin-packages/`), plus `activate`, `approve`, `allow_unverified_publisher` |
| `GET` | `/api/config/plugins/{key}` | One plugin with its versions and pinned settings `schema`; 404 when not installed |
| `DELETE` | `/api/config/plugins/{key}` | Uninstall: clear the active version, drop placements, undeploy everywhere |
| `PUT` | `/api/config/plugins/{key}/active` | `{version}`: update or roll back |
| `POST` | `/api/config/plugins/{key}/versions/{version}/approve` | Record the requested consent |

`{key}` is the percent-encoded PluginKey. A conflict with an installed
version or alias is `409`, and an unknown plugin or version is `404`.

## Enabling and settings (database)

Plugin configuration has one home: the **plugin instance document** in
the library database.

> [!NOTE]
> There is no `[sources.<id>]`, `[output.<id>]` or `[integrations.<id>]`
> table, and no `BOOKCLERK_SOURCE_<ID>_ENABLED` override. Only
> `[database]` (which database to open) stays in `config.toml`.

### Instances

Every discovered plugin, except database adapters, gets a **default
instance** at enrollment, with a document seeded from the manifest's
`[[settings]]` defaults.

- Operators may create more instances of one plugin
  (`bookclerk plugins instances create <plugin> --name …`).
- A bare plugin key or alias routes to the default instance, and jobs may
  pin another with `--instance`.

### Deployments

**Enabled on a node** means the instance's deployment row for that node
says to run it. Each row's `desired` state also says whose decision it
is:

| `desired` | Written by | The node |
| --- | --- | --- |
| `present` | An operator (`plugins deploy`, the Settings switch) | Runs it |
| `absent` | An operator (`plugins undeploy`) | Retires it |
| `placed` | The library scheduler ([placement](#placement)) | Runs it |
| `unplaced` | The library scheduler | Retires it |

Only an operator writes `present` and `absent`, and only the scheduler
writes `placed` and `unplaced`. The library refuses anything else.

The reconciler spawns rows that run, retires the guest when a row stops
running, and records observations (`materialized`, `running`, `healthy`,
`error`, `retired`).

- Third-party plugins enroll `absent` until an operator approves their
  grant and enables them.
- Platform guests (`local`, `sqlite`, `embedder`) grant themselves (the reconciler
  persists that grant before the first spawn) and come up enabled.

```sh
bookclerk plugins list                                  # instances + deployments
bookclerk plugins approve echo --yes                    # consent (third-party)
bookclerk plugins deploy echo                           # desired = present on this host
bookclerk plugins deploy echo --node <node-id>          # … on another library host
bookclerk plugins undeploy echo
bookclerk plugins instances list --plugin s3
bookclerk plugins instances create s3 --name "Backup bucket"
bookclerk plugins instances create local --name "NAS disk" --node <node-id>   # node-local
bookclerk plugins instances filter set <instance> --include storefront=libro   # which books a destination takes
bookclerk plugins config get s3                         # defaults under the document
bookclerk plugins config set s3 bucket my-audiobooks
bookclerk plugins config set s3 secret_access_key --secret   # value read from stdin
bookclerk plugins config unset s3 prefix                # back to the schema default
```

The daemon offers the same operations to an operator session:

| Method | Path |
| --- | --- |
| `GET` / `POST` | `/api/config/plugin-instances` (list; create `{plugin_key, display_name, node_id?}`) |
| `DELETE` | `/api/config/plugin-instances/{id}` (no deployments left) |
| `GET` / `PUT` | `/api/config/plugin-instances/{id}/config` (`{expected_revision, settings, secret_refs, secrets}`; `secrets` are sealed server-side) |
| `GET` / `PUT` | `/api/config/plugin-instances/{id}/filter` (a storage destination's filter: `PUT` takes `{rules: [{field, value, effect}]}`, and both answer `{plugin_instance_id, revision, filter}` with the rules under `filter`; see [Output](/docs/server/output/index.md#choosing-which-books-a-destination-takes)) |
| `GET` / `PUT` / `DELETE` | `/api/config/plugin-instances/{id}/intake` (whether a storage instance is a drop folder: `PUT` takes the settings, `DELETE` makes it a destination again, and both `GET` and `PUT` answer `{plugin_instance_id, revision, intake}`; see [Drop folders](/docs/server/drop-folders/index.md)) |
| `PUT` | `/api/config/plugin-instances/{id}/deployments/{node_id}` (`{desired, expected_revision}`) |
| `GET` | `/api/config/nodes`; `/api/config/plugins/{key}` carries the pinned schema |

### Settings → Plugins

**Settings → Plugins** shows each instance from its pinned schema:

- The Deployed switch writes this node's deployment (after consent, when
  needed).
- Secret fields are write-only.
- Save writes the document with compare-and-swap.

`PATCH /api/settings` no longer edits plugin keys (see
[Configuration](/docs/server/configuration/index.md) for the keys it takes).

### The pinned schema

Writes are checked against the schema pinned in `plugin_schemas` at
enrollment. So a plugin can be configured from any host in the library,
including hosts where it isn't installed.

The pin carries the package version. The newest installed version wins,
and every enrollment pass reconciles documents to its schema. A host still
running an older package refuses to spawn the plugin until it is upgraded
(see [`[[settings]]`](/docs/plugins/manifest/index.md#settings)).

A spawn checks the document against the host's local manifest. Unknown
keys are dropped with a warning, and a missing `required` key is an
`error` observation.

### What the reconciler runs

The reconciler runs a plugin's active
[installed version](#installing-plugins) when it has one, materializing it
by digest. It falls back to a host-local tree only for a plugin with no
installed version.

An operator package under `$BOOKCLERK_FILES_DIR/plugin-packages/<name>/`
(`package.json` plus `archive.tar.gz`, with artifact URLs limited to files
inside that directory) is published as an installed version the first
time a present deployment needs it. That happens offline, with the key's
existing `plugin-grants.json` approval carried onto it.

- The reconciler respawns a guest that has exited, even when the last
  observation was healthy.
- The daemon keeps one guest map for the process.
- A config reload enrolls the node again and leaves running guests in
  place, unless the database connection changed. Then every guest is
  retired, and the reconciler brings the present deployments back.

### Plugins that sleep when idle

Integration plugins work through calls: events, queue messages, cron
fires, metadata lookups, cover fetches, sign-ins and remote-library work
such as scans. The reconciler starts one of these once, checks its health,
and then lets it sleep:

1. After 60 seconds with no call in flight, the host stops the guest
   process. The deployment stays healthy and keeps its subscriptions,
   schedules and placement budget.
2. The next delivery, cron fire or lookup starts the guest again before
   the call goes through. On a 1-CPU machine a native or JavaScript
   plugin starts in about 60 to 80 ms.
3. If the guest cannot start, the call fails and the event or job is
   retried the usual way.

While a plugin sleeps, its health reads "asleep; starts on its next call"
without waking it.

A remote library such as Audiobookshelf sleeps the same way once every
plugin database it declares is granted, since that is where it remembers
what it already reported; without them it stays running. The host asks it
for new users every 5 minutes, and that poll wakes it, so a new user can
wait up to 5 minutes for a claim ticket. See
[Watching users](/docs/server/integrations/index.md#watching-users). A sign-in provider
(`oidc`) starts on the next sign-in. The host keeps its sign-in client
list after the first answer, so a config sync does not wake it; a failed
read is asked again on the next sync.

Storefronts sleep the same way, after 5 minutes without a call, because
their work comes in bursts: a scan pages through a library and an acquire
fetches several parts. A sign-in, scan, fetch, catalog search or Discover
lookup starts the store's guest again. Listing a store's accounts reads
the library and does not wake it. Credentials a guest refreshes are
written back as they change, so a guest started later begins from the
stored ones.

Storage plugins (destinations), built-in or not, sleep after 5 minutes
without a call. Any storage call, such as an acquire writing a book, a listing or
a playback read, starts the guest again. A write holds the guest until it
has committed, and an open read stream holds it until the reader is done,
so a long download or an hour of playback never loses its guest midway.
The destination's name and instance id stay known while it sleeps, so
checks that only need to know which destination is which do not wake it.

> [!NOTE]
> A plugin that belongs to more than one family, such as a storage plugin
> that also consumes events, stays running for now.

A Python plugin's first start takes several seconds while Python loads and
the plugin imports its modules. The host keeps a snapshot of the plugin
taken right after those imports, one per installed plugin version, and
later starts begin from it instead. On one CPU that takes a start from
about 5 seconds to about 1 second, so Python plugins sleep like the
others: the first call after a sleep waits about a second longer than it
would for a plugin written in JavaScript or Rust.

1. The first start of a new plugin version runs normally and saves the
   snapshot.
2. Once that start answered, the host stores the snapshot in
   `plugin-state/<PluginKey fs-id>/snapshot/`, about 45 MB per plugin
   version, and removes the one for the previous version.
3. Later starts load it. If a stored snapshot fails to start, the guest
   starts normally and saves a fresh one.

The snapshot is taken before the plugin receives its settings or
secrets, so it holds only code. The plugin can read its own snapshot but
never write the stored copy.

### How a node hears about a change

Each node consumes its own queue, `node.<node_id>`, on the outbox.

- Every committed deployment write (create, desired-state change, delete)
  publishes a `deployment.changed` message to the deployment's node.
- Every committed configuration document (library settings and instance
  documents) publishes `configuration.changed` to every registered node.
- The daemon's delivery worker claims those messages under the catalog id
  `node:<node_id>`, and wakes the deployment and configuration
  reconcilers.

There is no fixed 5-second re-read any more, only a 60-second backstop
pass for a wakeup sent while the node's catalog row wasn't live. Messages
are wakeups, not state: the reconciler always re-reads the authoritative
rows.

The CLI only produces them (`bookclerk plugins deploy --node <id>` wakes
that node). `bookclerk queues list` shows each node queue with its
`node:<id>` consumer.

### Instances and jobs

A deployed guest is registered under its plugin instance id.
`bookclerk library scan` and `bookclerk library acquire` pin their queued
jobs to a named plugin key's default instance. Pass `--instance` to pin
another.

Accounts are keyed by plugin key, not instance. Every instance of a
plugin, on every host, serves the same connected accounts.

## Placement

By default an operator deploys an instance node by node with
`plugins deploy --node`. **Placement** hands that job to the library
scheduler:

1. The operator says how many nodes should run the instance, and which
   nodes may.
2. The scheduler picks the nodes with the most room, and writes the
   per-node deployments.

Nodes never connect to each other. Everything below travels through the
shared library database.

```sh
bookclerk nodes list                              # liveness, capacity, budget, use, labels
bookclerk nodes set --memory-budget 50            # this node (or pass a node id)
bookclerk nodes set <node-id> --drain             # move scheduled replicas away
bookclerk nodes label --add nas --add zone=eu
bookclerk nodes owner <node-id> --user alice      # alice may now set its budgets and drain it
bookclerk plugins deploy example --replicas 2 --on nas --on '!slow'
bookclerk plugins deploy example --replicas all   # every node with room
bookclerk plugins deploy example --replicas 0     # keep the placement, stop every replica
bookclerk plugins deploy example --manual         # back to deploy/undeploy by hand
```

### Heartbeats and budgets

Every daemon writes a heartbeat row to `node_status` every 15 seconds. It
reports:

- **Capacity** the node detects: logical CPUs and memory, each capped by
  the daemon's cgroup (`cpu.max`, `memory.max`) when it runs in one.
- **Budget**: the share of that capacity the scheduler may commit to
  plugin guests, from the node's `node.runtime` document. The defaults
  are 80% of the CPU and 75% of the memory, so a desktop keeps room for
  its user. Set them with `bookclerk nodes set --cpu-budget/--memory-budget`,
  the nodes API, or **Settings → Nodes**. The node applies a change at its
  next heartbeat. The same document can also hold the node's own image
  cache budget (`--cache-budget`; see
  [Cache retention](/docs/server/integrations/index.md#cache-retention)).
- **Reservations**: the sum of the jail ceilings (memory and CPU, after
  `[plugins.jail]` limits) of the guests running there. The reconciler
  records each guest's ceiling on its deployment observation when it
  spawns it.
- **Measured use**: CPU busy since the previous heartbeat, and memory
  available, for the whole machine (or the daemon's CPU-limited cgroup on
  Linux).
- **Image cache**: what the node's image caches hold, their budget and
  when they were last swept (see
  [Cache retention](/docs/server/integrations/index.md#cache-retention)). A Host reports
  none.
- **Availability**: how much of the recent past the node was up, as a
  decaying average over about a day. A desktop that is off every night
  ends up around 60%; an always-on VPS stays near 100%.

Every desktop platform reports memory, measured use and free disk:

| Platform | Memory (total / available) | CPU busy | Free disk |
| --- | --- | --- | --- |
| Linux | `/proc/meminfo` `MemTotal` / `MemAvailable`, capped by cgroup `memory.max` | `/proc/stat`, or cgroup `cpu.stat` under a CPU quota | `statvfs` |
| macOS | `hw.memsize` / free + inactive pages (`HOST_VM_INFO64`) | `HOST_CPU_LOAD_INFO` ticks | `statvfs` |
| Windows | `GlobalMemoryStatusEx` `ullTotalPhys` / `ullAvailPhys` | `GetSystemTimes` | `GetDiskFreeSpaceExW` |

> [!NOTE]
> Only Linux reads a container ceiling (cgroup v2). A daemon confined by a
> Windows Job Object or a macOS resource limit is measured against the
> whole machine.

A node is **live** while its last heartbeat is younger than three
intervals (45 s). A node where only the CLI ran has no heartbeat and is
never live.

**Draining** a node (`nodes set --drain`, or the Drain button) stops the
scheduler placing anything there and moves its scheduled replicas
elsewhere. Deployments made by hand keep running.

A node's **headroom** is its budget minus what is committed:

- For CPU, committed is the larger of the reservations and the measured
  use, so work outside Bookclerk on a shared desktop counts.
- For memory, headroom is the budget minus the reservations, and never
  more than the memory the machine has free.

### Candidates

A node qualifies for an instance when:

- it is live and not drained;
- it carries every label the constraints name, and none that a `!label`
  constraint names;
- for an installed plugin, the active version has an artifact for the
  node's target, or a target-independent `any` artifact (workerd
  packages).

Labels are `name` or `name=value` (lowercase letters, digits and `._/-`).
Every node also carries `node=<node_id>` and `target=<target>`
(`linux-x64-gnu`, …). So `--on node=<id>` pins an instance, and
`--on target=linux-arm64-gnu` restricts it to one platform.

### Planning

The scheduler estimates what one guest of the instance needs, its
**demand**. That is the largest ceiling any node recorded for it, else
the active version's grant (`memoryMib`, `cpuRatePercent`), else the grant
defaults (512 MiB, 0.8 cores).

It scores each qualifying node by how many more such guests fit its CPU
and memory headroom, weighted by availability. An always-on node counts in
full, and a node that is never on counts half. Then:

- Replicas stay where they run while their node qualifies. Nodes that
  stopped qualifying (dead, drained, label removed) get `unplaced`.
- New replicas go to the highest-scoring nodes, and only where the demand
  fits the memory headroom. Memory is the hard limit, because a guest over
  its memory ceiling is killed; CPU only ranks.
- A scale-down drops the replicas on the nodes with the least room first.
- When a replica's node is over its memory budget and another qualifying
  node has room, the replica moves there. At most one moves per instance
  per pass, so the library doesn't thrash.
- `--replicas all` runs the instance on every qualifying node where it
  fits.

Each pass commits the demand of every replica it adds against that node's
headroom, so one pass doesn't stack several instances on the same node.

When fewer nodes qualify or fit than requested, the scheduler places what
it can and records why on the placement, for example: "1 of 2 replica(s)
placed: 2 node(s) are live, schedulable, and match nas; 1 lack memory
budget for 512 MiB".

Each node's reconciler then converges on its own deployment rows, exactly
as it does for hand-written ones.

### Routing deliveries

Event and queue deliveries addressed to an instance go to the best live
node running it, without any node contacting another.

1. Every node that runs an instance ranks the live nodes whose guest of it
   is up (a `running` or `healthy` observation), by the same score
   placement uses. So all nodes agree on the order.
2. The best node claims a delivery as soon as it is due. The node ranked
   `r` claims it only once it has been due for `r × 10 s`.
3. Ranks are re-read every 10 seconds.

A best node that is saturated, stalled or gone therefore costs at most a
short delay before the next one takes over. The claim's compare-and-swap
still guarantees one runner.

Deliveries addressed to a plugin key or alias, and a node's own queue,
aren't routed.

> [!NOTE]
> Jobs (scan, acquire) aren't routed yet: whichever node claims a job runs
> it with its own sources and destinations. A synchronous HTTP call runs
> on the node that receives it.

### One scheduler

Every daemon runs the scheduler loop, but only the holder of the
`scheduler` row in `library_leases` acts.

- The holder renews the lease (60 s) on every pass. When it stops, the
  next daemon to try takes over, with a larger fencing token.
- A pass runs on a `placement.changed` or `install.changed` node-queue
  wakeup, and at least every 20 seconds.
- Deployment writes are compare-and-swap, so a holder that lost its lease
  mid-pass can at worst add one replica too many, which the next pass
  removes.

### Placed instances are the scheduler's

- `plugins deploy|undeploy` and the deployment API refuse a placed
  instance (409).
- The Settings Deployed switch is read-only for it.
- Enrollment records a new node `unplaced` for it, rather than `present`.

`plugins deploy --manual` (or deleting the placement) hands the
deployments back without changing what any node runs: `placed` becomes
`present`, and `unplaced` becomes `absent`. Uninstalling a plugin
(`plugins uninstall`, `DELETE /api/config/plugins/{key}`) drops its
placements first.

| Method | Path | Body / result |
| --- | --- | --- |
| `PUT` | `/api/config/plugin-instances/{id}/placement` | `{replicas, constraints, expected_revision}`. `replicas` is a count or `"all"`; `expected_revision` 0 (or omitted) creates; 409 on a stale revision |
| `DELETE` | `/api/config/plugin-instances/{id}/placement` | Back to hand-managed |
| `GET` | `/api/config/nodes` | Each node's `labels`, `implicit_labels`, `target`, `live`, `kind`, `owner`, `runtime` (budgets, drain) and `status` (latest heartbeat), plus the caller's `capabilities`. A node owner gets only its own nodes |
| `PUT` | `/api/config/nodes/{node_id}/runtime` | Any of `{label, cpu_budget_percent, memory_budget_percent, schedulable}`. A node owner may edit only its own nodes |
| `PUT` | `/api/config/nodes/{node_id}/labels` | `{labels}`: the node's complete operator label set (operator only) |
| `PUT` | `/api/config/nodes/{node_id}/owner` | `{user_id}` (or `null`): the user who administers the node (operator only) |
| `GET` | `/api/library-status` | Node counts, committed CPU and memory across live nodes, active jobs, delivery backlog, and the nodes the caller may see |

In the web app:

- `GET /api/config/plugin-instances` and the Settings plugin groups carry
  each instance's `placement` (requested and placed replicas,
  constraints, detail).
- **Settings → Plugins** shows "Placed n/m" on the row. Expanded, it has
  replica and label fields, and **Manage by hand**.
- **Settings → Nodes** shows each node's heartbeat, reservations and
  measured use against its budget, and availability. It has fields for
  the budgets and labels, and a Drain switch.

### Node-local instances

`plugins instances create <plugin> --node <node-id>` (or `node_id` on
`POST /api/config/plugin-instances`) creates an instance owned by that
node, typically a node's own `local` output.

- It deploys only on that node. A deployment to any other node, and any
  placement, are refused.
- It adds to the library's outputs on that node, rather than replacing
  them. Acquires a branch node uploads reach every destination deployed on
  the shared node that received them whose filter takes the book,
  node-local ones included.

### Running on branch nodes

A branch node (a separate install that joined the library, see
[Libraries and branches](/docs/server/branches/index.md)) runs an owner's plugin only
after **its own** operator approves it. The narrowing is the same as on
any host (see
[Consent before enable](/docs/plugins/capabilities/index.md#consent-before-enable-and-every-spawn)).

To approve, use **Settings → Library** on the host, or:

```sh
bookclerk libraries approve <plugin_key> --request <DIGEST> [--deny-domain …] [--deny-binding …] [--deny-network]
```

`<DIGEST>` is the digest of the request being approved, from
`bookclerk libraries consents`.

- The owner's grant is the request. The host's approval may only remove
  from it.
- A later version that asks for more waits for approval again.
- A revoke cancels the plugin's jobs there and hands them back.
- The guest runs in the host's jail through `bookclerk-workerd`, as the
  host's own plugins do.

A platform plugin is approved automatically only when all of these hold:

- its key is a Bookclerk platform key;
- the host's own provenance check finds its install of that key
  platform-bundled;
- that bundled payload's digest equals the owner's artifact digest;
- the request stays inside the platform envelope (no network, only
  `config` and `work_fs`);
- the host's operator has neither revoked it nor approved it by hand. An
  operator's approval, which may narrow the request, is never replaced
  automatically.

## Host-local plugin namespace

What a plugin *is* (its installed versions, consent, instances, settings,
and where it is deployed) lives in the library database, shared by every
host in the library (see [Installing plugins](#installing-plugins)). What
a host *runs* is host-local: `$BOOKCLERK_FILES_DIR` holds the
materialized trees, guest state and the mutation lock for that host only.

```text
$FILES_DIR/
  node-identity.json             # this host's stable HostId
  plugins/.versions/<digest>/    # materialized installed version (read-only, shared by instances)
  plugins/.staging/              # partial extracts; never spawned from
  plugins/<PluginKey fs-id>/     # host-local tree: platform guests, dev trees, older installs
  plugin-packages/<name>/        # operator-placed package.json + archive.tar.gz
  plugin-state/<PluginKey fs-id>/data
  plugin-state/<PluginKey fs-id>/tmp
  plugin-state/<PluginKey fs-id>/session-<nonce>/  # host-owned; native-behind only
  plugin-state/<PluginKey fs-id>/snapshot/<key>/  # host-owned; Python start-up snapshot
  plugin-state/link-<32 hex>/<PluginKey fs-id>/      # on a branch: one subtree per library it joined
  plugin-grants.json             # consent for host-local trees (installed versions carry their own)
  install-ledger.json            # trust anchor for host-local installs only
  .plugin-mutation.lock          # OS advisory lock for cache and tree mutation
  .plugin-hold/                  # held trees/state during remove transactions
```

- The cache directory names a digest, not a plugin. Two instances of one
  version, or two plugins that ship identical bytes, share one tree.
- The `.versions` and `.staging` names start with a dot, so discovery and
  alias scanning skip them. An installed version is found through the
  database, never by walking `plugins/`.
- `.plugin-mutation.lock` is scoped to the files directory. Two hosts that
  share one PostgreSQL or D1 database each take their own lock and never
  block each other. Library coordination goes through database rows and
  compare-and-swap, not a shared-database advisory lock.

Host-local trees remain for three cases:

- platform guests that ship with the host (`sqlite`, `local`, `embedder`);
- development trees staged by `cargo stage-plugins` or `cargo dev`;
- installs committed before library installs existed.

Those use `plugin-grants.json` for consent and `install-ledger.json` for
identity. `receipt.json` inside such a tree is metadata only. Remove and
install identity is bound to the ledger plus the tree's place on disk
(`basename == PluginKey.fs_id()` for `pk-*` directories), so a tampered
receipt can't redirect `--purge-state` onto another PluginKey.

## Isolation modes

```toml
[plugins]
isolation = "required"  # required | best-effort | off
# jail_bin = "/usr/local/bin/bookclerk-jail"
```

These environment variables override the file:

| Variable | Sets |
| --- | --- |
| `BOOKCLERK_PLUGIN_ISOLATION` | The isolation mode |
| `BOOKCLERK_PLUGIN_JAIL` | The path to `bookclerk-jail` |
| `BOOKCLERK_PLUGIN_WORKERD` | The path to `bookclerk-workerd` |
| `BOOKCLERK_WORKERD_BIN` | The path to the pinned `workerd` |

The modes:

- **`required`** (default): a plugin that can't be jailed isn't loaded.
  The error names the reason and the plugin is skipped; the rest of the
  host runs.
- **`best-effort`**: start the guest unconfined when the platform or the
  installation can't support a jail, with a warning that says so per
  plugin.
- **`off`**: no jail. For development only.

> [!IMPORTANT]
> Isolation is only about the **OS jail**. The `bookclerk-workerd` front
> door is required in all three modes. `best-effort` and `off` still spawn
> every guest through `bookclerk-workerd`, and a missing launcher or
> `workerd` binary is a hard spawn error, not a fallback to direct native.

These are the same three modes as `[media].isolation`, for the same
reasons: the tiers differ in what they reach for, not in how a missing
jail is handled. Confirm what is in effect with
`bookclerk config get plugins.isolation`.

| Platform | Backend | File system | Syscalls | Network | Memory, CPU, PIDs |
| --- | --- | --- | --- | --- | --- |
| Linux | Landlock and seccomp-bpf | Allowlist, ABI-probed | Deny list | Per policy | cgroup v2 best-effort (`memory.max`, `cpu.max`, `pids.max`) when the spec sets limits |
| macOS | Seatbelt (`sandbox_init`) | Deny-default SBPL profile | Not applicable | Per policy | Not supported (file system and network only; no fake enforcement) |
| Windows | AppContainer | ACL allowlist at spawn | Not applicable | Capability SIDs | Job Object (spec fields override label heuristics) |

## Installing the launcher

The host looks for `bookclerk-jail` in this order:

1. `plugins.jail_bin` in `config.toml`
2. `BOOKCLERK_PLUGIN_JAIL`
3. `bookclerk-jail` beside the running executable

Each candidate must exist, so a stale configured path fails loudly
instead of quietly running an unconfined guest.

Build it and ship it with the hosts, with `bookclerk-workerd` when
shipping workerd guests:

```sh
cargo build --release -p bookclerk-cli -p bookclerkd \
    -p bookclerk-media-worker -p bookclerk-jail -p bookclerk-workerd
```

The Docker image ships the helpers in the read-only bundle under
`/opt/bookclerk`, next to `bookclerk` and `bookclerkd` (see
[Running Bookclerk → Docker](/docs/server/operations/index.md#docker)).

## Troubleshooting

### `refusing to run plugin <id> unconfined: bookclerk-jail not found in <dir>`

The launcher isn't installed beside the host binary. Install it, point
`plugins.jail_bin` at it, or accept unconfined guests with
`isolation = "best-effort"`.

### `refusing to run plugin <id> unconfined: this host cannot confine a process`

There is no backend: a kernel without Landlock, a container runtime that
blocks the Landlock syscalls, or a Windows host where an AppContainer
profile can't be created. The message names the backend that fell short.

### `bookclerk-jail: these allowlist paths do not exist: …`

A granted folder vanished between planning and launch. Both backends
reject a rule naming a missing path, and the launcher refuses rather than
quietly narrowing the jail.

### A plugin fails on a path it used to read

The path is outside the four grants. A guest that needs host data should
ask for it over RPC. The file system allowlist can't be negotiated from a
manifest.

### Everything fails right after spawn

Check the guest's stderr. The host inherits it, so it lands in the daemon
log directly under the `bookclerk-jail:` line that reports what was
applied.

### "Enable / spawn refused: run `bookclerk plugins approve` first"

The consent grant is missing, or the plugin widened `capabilities` since
the last grant. Approve again, then run `bookclerk plugins deploy <id>`.
Spawning also fails closed until the grant covers the current manifest.

An upgrade that only asks for more (another binding, fetch host, TCP port
or CIDR) doesn't stop the plugin: it keeps running under the earlier
grant, and `bookclerk plugins info <id>` lists what is waiting for
consent (see [Upgrades](/docs/plugins/capabilities/index.md#upgrades)).

## Next steps

- [Capabilities and consent](/docs/plugins/capabilities/index.md): what a plugin
  may ask for.
- [The guest jail](/docs/internals/guest-jail/index.md#the-guest-jail): how the
  jail is built.
- [Libraries and branches](/docs/server/branches/index.md): running plugins on branches.
- [Stores reference](/docs/server/stores/index.md) and [Output and destinations](/docs/server/output/index.md):
  the first-party plugins' settings.
