Developer DX: no documented way for a Seed owner to install their own cog

[shaal]

Summary

Building a custom cog (DOOM — see cognitum-one/cogs#28), I found there's no documented way for a Seed owner/developer to install a cog they built themselves. The only sanctioned path assumes you're Cognitum.

What I hit

• The cog-dev plugin's /cog-deploy does gsutil cp … gs://cognitum-apps/… and refuses unless you're authenticated to Cognitum's private GCS bucket. Third-party developers can't use it.
• POST /api/v1/apps/install only accepts {"id":"…"} and downloads by id from the fixed cloud registry. No upload, no arbitrary URL, no owner-configurable registry. Installing a non-registry id returns cog not found in registry or binary missing.
• To run my own cog I had to reverse-engineer the on-disk layout (place the binary + cog.toml + config.json under /var/lib/cognitum/apps/<id>/ and restart). That works but is undocumented and fragile.

Suggestions

1. A documented owner sideload/install — e.g. POST /api/v1/apps/install accepting a local file/upload from the trusted USB/loopback origin, or an owner-configurable registry URL so devs can self-host.
2. Publish @cognitum/cog-dev (currently 404 on npm; the JS plugin is listed "Soon").
3. A "deploy your own cog" guide in the developer portal.

This is the single biggest barrier to third-party cog development right now.

[proffesor-for-testing]

Thanks @shaal — confirmed end-to-end against the current tree, every claim checks out:

• /cog-deploy gates on gsutil/gcloud auth to our private bucket (tools/cog-dev-plugin/agents/cog-deployer.md refuses if not authenticated; uploads target gs://cognitum-apps/…), so third-party devs genuinely can't use it.
• POST /api/v1/apps/install accepts only {"id":…}, rejects anything with / or .., and fetches from the hardcoded cognitum-apps registry; a non-registry id returns exactly cog not found in registry or binary missing (src/cognitum-agent/src/api.rs:1759). No upload / URL / owner-registry path.
• The /var/lib/cognitum/apps/<id>/ layout (binary + cog.toml + config.json) you reverse-engineered is correct — it's just not a supported/documented surface.
• @cognitum/cog-dev is currently an in-repo Claude Code plugin only (tools/cog-dev-plugin, v0.1.0); the npm 404 is expected.

Classifying as an enhancement/RFE (nothing's broken; the owner-sideload story is missing). Likely direction: a USB/loopback-origin owner install endpoint or an owner-configurable registry URL, plus a "deploy your own cog" guide. Tracking as cognitum-one/seed#184 (docs portion to platform-docs). Appreciate the detailed write-up — this is clearly the biggest third-party blocker.

[shaal]

Update — I built suggestion #1 (an owner-configurable, self-hosted registry) as a working, signed protocol with a live store.

Since filing this I implemented the "owner-configurable registry URL so devs can self-host" path end to end:

• Protocol + tooling: shaal/gearbox — a pluggable cog-store protocol (signed store.json + app-registry.json, Ed25519 over RFC 8785 / JCS), a native Rust CLI + a Python cross-check oracle, frozen test vectors, and operator tooling that stages/signs/hosts a store.
• A live store: https://arcade.shaal.dev — self-hosted, serving the DOOM cog from Add doom cog: browser-playable DOOM on the Seed (first C-FFI cog, GPLv2) cogs#28 (signed catalog + the armhf binary + the FreeDoom asset, all sha256-pinned). Anyone can verify it today:

  curl -s https://arcade.shaal.dev/app-registry.json      # the signed catalog
  gearbox verify app-registry.json --key-id shaal-arcade-2026 --pubkey-b64 <pub>
  # → "OK: catalog verified"
  

  The cog is its own repo (shaal/cog-doom, which release-builds the armhf binary); the store pins a release, signs, and hosts it (shaal/cogstore-arcade), with a small client-rendered storefront over the same signed files a Seed verifies.

What's left is entirely Seed-side — the device still can't consume such a store. Concrete checklist (specced in gearbox's docs/cross-repo/seed/ as B1–B6):

1. Configurable stores — a StoreDescriptor list (id, catalog_url, artifact_base, trust keys, priority, enabled); drop the hardcoded gs://cognitum-apps base.
2. https:// fetcher (and file:// for air-gap).
3. Load the catalog from catalog_url.
4. Verify the catalog signature against the store's pinned key(s); fail closed if unsigned/untrusted.
5. Install by path + sha256 against the signed catalog (not a transport-supplied hash).
6. TOFU add-store — show the store key fingerprint, owner confirms, pin it.

The hard part (the signing/canonicalization format both sides must agree on byte-for-byte) is done and frozen as test vectors, so a Seed implementation has an executable contract to build against. Happy to help wire it up.

I also opened #63 for the broader layer this same mechanism enables — air-gap bundles, a tamper-evident audit log, managed-mode policy, and provenance/SBOM attestation — for the self-hosted and enterprise/fleet cases.