---
title: "Custom-widget packages and installations"
description: "Understand immutable package versions, workspace installations, local data bindings, upgrades, provenance, and current distribution limits."
section: "Dashboards"
canonical: "https://banksync.io/docs/dashboards/custom-widget-packages"
---

A **package** is portable code plus a manifest. An **installation** is a workspace-owned widget that
pins one immutable package version and binds its logical inputs to local data. A **placement** is that
installed widget pinned on a particular dashboard, with optional placement settings.

> **Private workspace beta:** The dashboard creator, Packages library tab, installer, and compatible-version upgrader are
> available for workspace-scoped packages. Cross-workspace and public distribution remain blocked.

| Layer           | Portable?       | Contains local data identity?               | Mutable?                     |
| --------------- | --------------- | ------------------------------------------- | ---------------------------- |
| Package version | Yes             | Never                                       | No                           |
| Installation    | Workspace-local | Yes: compiled bindings and grant            | Yes, with version/OCC checks |
| Placement       | Dashboard-local | No credentials; may carry display overrides | Yes                          |

## Create and version

Package creation submits source and a validated manifest to the workspace package endpoint. BankSync
builds it server-side, stores source behind a private content reference, computes the digest from the
bundle + manifest + SDK/runtime/toolchain provenance, and writes version 1 immutably.

Submitting changed source or manifest creates a new version. Reusing a version number is idempotent
only when every immutable field is identical; different content is rejected.

Penny and MCP may build the same source-and-manifest contract into an inert package proposal. That
proposal is not package persistence, installation, binding, or consent. The in-app Penny handoff
opens the ordinary creator and installer for explicit review. MCP returns the portable artifact to
its caller; direct MCP-to-app import is a later surface and generation cannot authorize data.

## Install

After a successful author build, **Create package** stores the immutable version and opens the
installer. An existing workspace package can also be opened from **Add a widget → Packages**.
Installation chooses a package version, local widget name/slug, installation settings, and one local
binding for each required input. The server—not the browser—validates the package status, loads the
immutable version, resolves the selected source's actually available schema, compiles field mappings
and source scopes, fills setting defaults, and creates the v2 Widget. No source bytes are copied into
the Widget document.

The beta installer accepts direct feed and direct bank inputs. It provides server-authoritative
auto-mapping, manual field repair, bank-account scope, transaction/trade date scope, and declarative
installation settings. It fails loudly for missing inputs, unknown input IDs, incompatible fields,
archived packages, or unsupported composed sources.

## Upgrade

An upgrade is not a floating `latest` reference. The installation continues to pin its old digest
until the inspector shows a newer version and the user explicitly upgrades. The inspector summarizes
input, setting, and capability changes. Compatible direct bindings are recompiled against the target
manifest; a new required input blocks the one-click upgrade until that input can be configured. The
previous grant never transfers automatically: the new digest pauses data until consent is reviewed.

## Portability rule

Exportable package/template metadata may contain a package reference and logical input requirements.
It must not contain concrete feed IDs, bank IDs, account IDs, query IDs, source fingerprints,
credentials, grants, or installation binding fingerprints. Those are collected again in the target
workspace.

## Visibility and distribution

Current creation supports `private` and `workspace` visibility. Repository models reserve `unlisted`
and `public` states, but public creation, marketplace listing, public/portal execution, publisher
verification, signing, moderation, and takedown distribution are gated off. Archived packages are a
render/install kill switch; deprecated packages may continue running while users migrate.

## Assumptions

- Package IDs are global opaque identifiers; visibility checks still apply in the requesting
  workspace.
- Versions and content-addressed source/bundle references are retained while installations pin them.
- Slug uniqueness, automated upgrade rollout, marketplace ranking, billing, and publisher identity
  policy are outside the private workspace beta and must be designed before public launch.
- The current package contract editor is JSON-oriented for developer beta users; a future visual
  contract builder may author the same manifest without changing package identity.
- Reserved public model states do not imply public availability.