# Offscale — the first real plugin **Status: LIVE DOCUMENT, opened 2026-08-14.** Decisions and findings from the session that started the plugin system. Correct it in place; it is meant to be edited, not archived. Offscale is Headscale extracted into a plugin. It is the pilot: chosen because it is a genuine vertical slice (schema + backend router + sidecar + frontend screen + capabilities) without being pathological. Related, and older: `sidecar-app-store.md` is the origin design and is largely implemented despite its "Nothing implemented" header. `sidecar-topology.md` is where the runtime shape was going. --- ## The reframe **Core is `officer` and nothing else. Everything else is a plugin** — `officer-pty`, `officer-opencode`, `officer-claude-code`, offscale. `officer-anthropic-proxy` is a known exception to think about later; the intuition is that it is one plugin requiring two sidecars. The old baseline was six PM2 processes. Headscale was removed from it on 2026-08-14 (`services.sh`, the local ecosystem file, `catalogue.test.ts`'s `CORE[]` mirror, and PM2 itself), so the machine this was written on runs five. ### Two words, because "core" was doing two jobs - **baseline** — what a fresh install actually runs - **first-party** — what Officer Dev publishes They come apart immediately: offscale is first-party and no longer baseline. Saying "core" for both makes "is X core?" a question with two answers. --- ## What a plugin is made of Combined per plugin as needed. **Only `meta` and the ID are always required.** - a **meta** object — id, name, dock item, backend/frontend mount, etc. - an **ID** (see below) - a **sidecar** - a **backend router** and its routes - a **db schema** - **default permissions per user group** - what it stores in the **secret store**, and whether that is per-user or plugin-global - a **frontend router**, its routes, and the frontend code - how it **mounts into the file browser context menu** - a set of **capabilities added to officer-items** - **plugin settings page** definitions - an accompanying **mobile app** A plugin is completely self-contained. The platform's installed/enabled state decides whether its routers mount, whether its sidecar is in the ecosystem file, and so on. ### What offscale needs db schema · backend router + routes · frontend router + routes · sidecar. **Not** a context menu, **not** officer-items capabilities, and (probably) **not** a settings page. --- ## Identity and routing **The app-name is the ID.** One identifier, not two — it names the plugin, prefixes its tables, and is its route. A random ID plus a separate app-name was considered and dropped: splitting the uniqueness guarantee across two namespaces means whichever is weaker becomes the real attack surface. **Uniqueness comes from two mechanisms**, because one is not enough: - **globally** — the marketplace owns the namespace for published names, with human review. A name as generic as `notes` gets refused: it is a name Officer Dev may want later. - **locally** — the platform refuses to install a plugin whose app-name is already taken on this machine. Needed because a private plugin never asks the marketplace anything. The marketplace works like the Chrome extension store. Anyone may write plugins for their own use with no restrictions; publishing is what invites review. ### Mount prefixes ``` first-party /api/ e.g. /api/offscale third-party /api/p// e.g. /api/p/alice/notes ``` `p` is a literal segment meaning "plugin". First-party plugins sit at the root because Officer Dev owns that namespace anyway, and because provenance is then legible at a glance in a log or a route table. **The prefix must be derived by exactly one function from the manifest.** Nothing about a first-party plugin's code may know it is first-party. If that difference ever leaks past the one derivation — a special case in the router, a bypassed check, a different install branch — first-party and third-party become two systems, and only one of them gets tested. `/p/` does **not** solve plugin-vs-plugin collisions; the marketplace and the local check do. What it guarantees is that a plugin can never shadow a **core** route, which also means the platform can keep adding core routes forever without breaking installs. --- ## The database **Tables live in `public`, prefixed with the app-name** — `offscale_servers`, exactly as the codebase already does (`headscale_servers`, `music_favorites`, `vault_tokens`). No new machinery. ### A Postgres schema per plugin was tested and rejected Not rejected on suspicion — it was built and proven to work, then dropped as more complexity than it earns. Recorded so nobody re-runs the experiment: | Property | Result | | ----------------------------------------------------------------- | ------------------------- | | `pgSchema('offscale')` + `drizzle-kit push` creates the namespace | works | | Cross-schema FK to `public.users` | works | | Partial unique index preserved | works | | Push is idempotent, no spurious re-creation | works | | Cascade delete across the schema boundary | works | | `DROP SCHEMA offscale CASCADE` as uninstall | works, `public` untouched | **The finding worth keeping: `schemaFilter` is mandatory, and the docs are wrong.** Drizzle's config documentation states that push "will by default manage all schemas". On drizzle-kit **0.31.8** that is false. A push with the table verifiably exported reported `No changes detected` and created nothing; naming the schema in `schemaFilter` made the identical push work. If per-plugin schemas are ever revisited, that is the trap: **a plugin install would report success and silently create no tables.** Same failure shape as several bugs found the same day — a refusal wearing the costume of a normal result. --- ## Mounting is dynamic Three options were considered: - **A** — mounted always, refuses when not installed _(what ships today)_ - **B** — mount set decided at boot from the install table, restart `officer` on install - **C** — genuinely dynamic, mounted and unmounted at runtime **C is the decision.** Explicitly not an intermediate step: the platform must not need to know a plugin exists in advance, and B still bakes the answer at boot. This contradicts `sidecar-app-store.md`, which leans on "every API route stays mounted regardless" as a simplification. That premise is retired. ### What has to change with it `assertCapabilityTotality` runs before `serve()` and throws if a mounted router has no registry entry. It exists for a real reason: a Member 403'd on `GET /api/tasks` while opening `/api/tasks/pipeline/ws` with a 101 in the same minute, because Bun's route table matches the socket before the `/api/*` catch-all. **It does not die, it relocates.** Today it asks "does every mounted route have a permission?" once, at boot. Under C the same question is asked **per mount**: registering a router and registering its capability become one transaction, and an incomplete one is refused. ### Foundations that already exist - Sidecars register at **runtime** over `/api/sidecar/register` and are found **by capability, never by name** — which is how `officer-agent` was renamed to `officer-claude-code` without touching a caller. - `sidecar/proxied-prefixes.ts` is already a runtime-mutable `Set`, self-registered by `createSidecarProxy` "so a new sidecar cannot forget to add itself". What is compile-time is only the routes and permissions, not the sidecar's existence. --- ## Permissions A plugin declares capabilities. **A plugin may declare `app`, and nothing else.** `CapabilityKind` is `core | app | confined | execution | admin`. `core` means _every account, not deniable_, so a third-party manifest naming its own kind is a privilege-escalation surface: "malicious plugin declares itself core" is an ungated grant to every user. `core`, `execution` and `admin` stay the platform's to assign. ### Three different things are called "capability" here A manifest needs three names, not one: 1. `capabilities/registry.ts` — **permissions** (`headscale`, `vpn`) 2. `$OFFICER_ROOT/capabilities/` — the **file-based item store** (skills, tools, tasks) 3. `sidecar-registry` `capabilities: ['music']` — **routing keys** for `sendCommand` Offscale needs (1) and (3), and not (2). --- ## Secrets Two stores, and a plugin author will reach for the wrong one unless told: - **plugin-global keys** → the secret store (`officer_db/src/secret-store.ts`, real: `getKey(purpose)`, `hasKey`, `retiredKeys`). Purpose-keyed encryption and signing keys, not arbitrary values. - **per-user credentials** → `service_connections`, which already does the hard part: the row is keyed `(userId, service)` and **a NULL `url` means "inherit the instance"**, so a member structurally cannot see or supply the URL. `service` is free text with no namespacing yet — that needs solving before third parties touch it. Offscale's own coupling is small and instructive. `headscale/queries.ts` imports exactly two things from the host: ```ts import { db } from '../db'; // the connection import { encryptSecret, decryptSecret } from '../crypto'; // at-rest encryption, 10 uses ``` A plugin cannot carry its own `db` (it must share the connection to reference `users.id`) and should not carry its own crypto (the key lives in the platform's store). **So those two are provided to a plugin rather than imported by it.** That is the first concrete piece of the plugin↔host API, and it fell out of the pilot rather than being invented. --- ## `/api/vpn` is being deleted Officer had two headscale surfaces: | | `/api/vpn` | `/api/headscale` | | ---------- | ---------------------------------------- | -------------------------------------- | | capability | `vpn`, kind `app` — grantable to members | `headscale`, kind `admin` — owner only | | purpose | enrol your own device | the tailnet: machines, routes, ACLs | | surface | one route, `POST /enroll` | the whole admin API | `POST /api/vpn/enroll` was one-tap enrollment for a phone already signed into Officer. **It has no caller anywhere.** Verified against the mobile monorepo: 1. `enrollVpn()` has one call site, `useVpnScreen.ts:617`, inside `enroll()` 2. `enroll()` is reached only via `if (embedded) await enroll()` 3. `embedded` is optional and defaults to `false` 4. `VpnScreen` is rendered in exactly one place — `apps/offscale/src/App.tsx` — which never passes it `apps/mobile` and `apps/headscale` have zero references to `enrollVpn`, `VpnScreen` or `api/vpn`. Neither does the Officer web app. The live database holds no `vpn` grants. **And it will never come back.** Offscale is permanently standalone: no login, no backend calls, no dependency on Officer or the platform. The reasoning is the app's own and it is sound — _the thing that gets you to the platform cannot itself need the platform_, or a broken tailnet locks you out of both. ### Everything collapses to one namespace `/api/offscale/*`. The comment in `vpn/router.ts` claiming "the path is a contract" no longer binds: the contract has no counterparty. **The invite flow stays and does not need the mobile app changed.** `claimInvite` calls `${invite.base}/api/v1/enroll/claim` — the **Companion** on the server, at a base URL carried in the invite link. `/api/v1/` is Headscale's own namespace. The phone never talks to Officer for invites. - **phone → Companion** — untouched by anything here - **web admin → Officer → sidecar** — ours to rename freely ### There are THREE components, not two Easy to miss, and worth stating because two of them contain the word "enroll": | Component | Repo | Enrolment surface | | ---------------- | ---------------------------- | ------------------------------------------------ | | Officer platform | `officerdev/platform` | `/api/offscale/*` — web admin only | | Mobile suite | `officerdev/monorepo-mobile` | calls the Companion, never Officer | | **Companion** | `officerdev/offscale-server` | `/api/v1/enroll/*` under basePath `/officer-api` | The Companion ships beside each Headscale server. Confirmed against its source on 2026-08-14: zero references to `/api/vpn/*`, and its only outbound calls are the docker socket and its sibling headscale's `/health`. It never calls Officer and does not use `/api/offscale/*` either. **`/api/v1/enroll/*` is the Companion's and is not ours to collapse.** The phone claims at `${invite.base}/api/v1/enroll/claim`, where `invite.base` is the `sidecarOrigin` the Companion itself put in the invite (`https:///officer-api`). **Trap when deleting:** do not delete the sidecar's `enroll.ts`. Line 71 dispatches `/enroll/invites` to `handleInvitesRoute`, so it is the invite flow's entry point. Only the bare `POST /_officer/enroll` handler below it is dead. **A public route is possible if ever needed.** `/api/vault` is already exempt from platform auth (`EXEMPT_API_PREFIXES`) because Bitwarden clients carry a Vaultwarden bearer rather than a platform JWT. The exemption must be declared with a reason or the boot check refuses. Not needed today. **Open:** the `vpn` capability is the only member-grantable piece of headscale — everything else is `admin`. If it disappears with the route, members lose the ability to enrol their own devices. Decide deliberately rather than losing it in the move. --- ## The state of the app store, as found It **is** the plugin system, roughly 90% built, with one structural hole. `ecosystem.config.cjs` is generated once at setup and **nothing appends to it on install**, so the installer's final step runs `pm2 start ecosystem.config.cjs --only officer-jellyfin`, matches no app, and silently does nothing. Acknowledged in `app-store/pm2.ts:23-29`: > _"Installing a plugin has to append its entry here before starting it — that is the plugin system's job > and it is not built."_ Net: **nothing in the catalogue installs end-to-end today.** Containers come up, `service_connections` is written, assets publish, the dock tile appears — and the sidecar never starts. Also found: - The `schema` install step is a **logged no-op** (`effects.ts:117-124`). Every table still ships via `bun db:push`. - Of 8 entries declaring a compose template, **only 2 exist on disk** (`transmission`, `vaultwarden`). `slskd` has an icon and nothing else. `catalogue.test.ts` asserts a template _name_ is declared but never that the directory exists. - `hono.ts` has **28 routers mounted and 15 commented out**; `officer_db/src/schema.ts` has **11 commented schema exports** under "uncomment when the plugin is installed". Today, installing a plugin literally means editing two files and rebuilding. - `catalogue.test.ts` asserts every entry's process has a matching `src/servers/sidecar/`. A plugin in its own repository has no such directory, so that test inverts — as `sidecar-app-store.md` predicted. - A **dead, unrelated** plugin system still exists: `GET /server-settings/plugins` scans `src/workspaces/plugins/`, which does not exist, so it always returns `[]`. `PluginsSection.tsx` still renders against it. Not to be confused with any of the above. --- ## Where the code lives `plugins/offscale` on `gitea.officer.dev` — private, default branch `main`, topic `officer-plugin`. The `plugins` org exists because Gitea has **no nested organizations** (verified: no `parent` field on the org object), so `/` is the only real namespace it has. Topics work and are searchable, and are used in addition rather than instead — they span orgs, which matters because browser extensions under `extensions/` may become plugins later. --- ## Open questions 1. **Frontend code is the hard one.** Everything else on the list is data or a process; the SPA is compiled. `public/plugins//` exists but carries only icons. Shipping a third party's React that shares the shell's React, router and query client is a different problem class — federation, an iframe, or a manifest-driven generic UI. Do not design the package format as though this is solved. 2. **Migrations and versioning.** A plugin needs a version and a platform-compatibility range, and something has to apply schema changes over time. Cheap now, miserable to retrofit. 3. **Health, distinct from enabled.** The store already renders amber for "installed and enabled but the process is not online". That state needs a definition a plugin can satisfy. 4. **No inter-plugin dependencies.** Measured: zero sidecar-to-sidecar dependencies, and every non-core schema references only `auth.ts`. Worth promoting from accident to rule while it is still free. 5. **`service_connections.service` namespacing** before third parties touch it. 6. **`officer-anthropic-proxy`** — one plugin, two sidecars. 7. **Gitea is installed but invisible.** Containers `gitea` and `gitea-postgres` run, `officer-gitea` is not in PM2, and there is no `sidecar_installs` row — it predates the store. "Already there, but not by us" needs an answer, and the store deliberately refuses to adopt directories it did not create.