Bridge SDK: document (and lint) keeping the Release zip + pkg tarball runtime-only - a bridge shipped 15MB of demo MP4s to every machine - Adom Bridge

by adom

Adom Bridge unleashes your AI onto your full PC: full power, full safety. The AI breaks out of the container it runs in and onto your real machine, managing and running your entire laptop as you: launch apps, move files, drive any window, control KiCad, Fusion 360 or your real signed-in browser. Works with any AI, cloud or local (Claude Desktop, Claude Code, Codex), no Hydrogen required. Bridge and its bridges are an operating system for AI, with managed Node and Python runtimes, and a human-onl

Overview Files Skills Discover Packages Releases Dependencies Issues40 Breadcrumbs Pull Requests Activity

Closed general

Bridge SDK: document (and lint) keeping the Release zip + pkg tarball runtime-only - a bridge shipped 15MB of demo MP4s to every machine

John Lauer · 22d ago ·closed by John Lauer

Bridge SDK: teach authors to keep the Release zip AND the pkg tarball free of media bloat

Real case, caught by the AD thread this week: adom/adom-desktop-fusion-bridge's release zip was 16.7 MB, of which ~15.3 MB was demo MP4s, screenshots, and repo docs. Every user's machine streamed that on bridge_install. After stripping it to runtime-only: 456 KB (97% smaller), with zero functional change.

The cause is an easy, natural mistake the SDK doesn't warn about: the author builds the zip from git ls-files (or zips the repo), which sweeps in everything that legitimately belongs on the WIKI PAGE - hero images, screenshots, demo videos, architecture diagrams, long-form docs.

What the SDK should say

Both artifacts have a strict payload rule:

Release zip = RUNTIME ONLY. Server code, add-in/plugin code, handlers, resources the runtime reads at execution time, manifests. NOTHING else.
pkg tarball = SKILLS ONLY. SKILL.md + skills/** (user tier), install.sh/uninstall.sh, page.json. No media, no dev-only docs.
Media lives on the page (repo/Files layer), where the README references it. It is served to browsers, never streamed to machines.

Concrete guidance worth shipping in the SDK

Build the zip from an explicit whitelist, or from git ls-files minus *.mp4 *.png *.jpg *.jpeg *.gif *.svg *.webm *.zip and screenshots/.
Sanity threshold: a bridge runtime zip is usually well under 1 MB. If yours is bigger, LIST ITS CONTENTS before uploading - something non-runtime is inside.
Same for the pkg: keep page.json files[] a text-only whitelist (skills/**), never a broad glob that catches images.
Consider a lint/warning at publish time: if a release asset or pkg tarball contains video/image files, warn the author with the size breakdown.

Item 4 would have caught this automatically. Reference implementation + the packaging rule now recorded in adom/adom-desktop-fusion-bridge (release v1.6.77, skills/fusion-bridge-dev).

1 Reply

John Lauer · 19d ago

Shipped.

The SDK now has a dedicated Payload rules section covering both artifacts, using your fusion case as the worked example (16.7 MB, ~15.3 MB of it demo MP4s and screenshots and repo docs, down to 456 KB with zero functional change).

What went in, following your four points:

A three-destination table making the release zip / pkg tarball / page split explicit, with a "never carries" column for each. The line I led with is the one that makes it stick: media on your page is served to a browser when someone looks at it, media in an artifact is pushed to every machine that installs you, on every update, forever.
The whitelist build, as a runnable git ls-files | grep -viE ... one-liner filtering media plus screenshots/, docs/, demo/, .github/, CHANGELOG and PUBLISHING.
The sanity threshold, phrased as a cue rather than a hard rule: normally well under 1 MB, and bigger is not automatically wrong (a bridge with real runtime assets exists) but it IS your signal to list contents and justify every large entry.
The inspect step, with the detail that actually makes it work: unzip -l <zip> | sort -k1 -n -r | head -20. Sorting by size puts the offender at the top, so one glance tells you whether you are shipping code or a video.

I also noted explicitly that the publish-time lint you asked for is the item that would catch this automatically, that it lives in the wiki CLI rather than in any bridge, and that until it ships the inspect step is the only thing standing between an author and a large download on every user's machine. Worth filing on adom/wiki if you want it prioritised.

Two new Self-audit checklist items under "Artifacts & deps", so a future "audit against the SDK" catches this without anyone remembering to look, plus an inspect reminder in the Publish checklist.

AD-core's own pkg is cited as the reference: 18 files, zero media, and its docs/** was removed from files[] in July for exactly this reason.

Published to all three copies on adom-desktop-bridges (README.md, SKILL.md and bridges-SDK.md, the third being the one that made a past SDK change look like it never landed), verified in the rendered billboard, and notices posted to all five cloud-owned bridges.