Companion Release Bundle Runbook

This runbook covers generating, verifying, and launching Flynn companion shell bundles.

Generate Bundle

From a Flynn host:

flynn companion \
  --platform macos \
  --node-id companion-macbook \
  --app-version 1.0.0 \
  --export-release-bundle ./dist/companion-macos

Generated files:

companion.bootstrap.json
run-companion.sh
README.md
CHECKSUMS.sha256

Optional signed export:

flynn companion \
  --platform macos \
  --node-id companion-macbook \
  --export-release-bundle ./dist/companion-macos \
  --signing-key ./keys/release-private.pem \
  --signing-key-id team-k1

Additional file:

CHECKSUMS.sha256.sig

Generate Platform Starter Shell Template

For native app bootstrapping (without launcher/checksum artifacts), export a platform template:

flynn companion \
  --platform ios \
  --node-id companion-ios \
  --export-shell-template ./dist/companion-ios-template

Generated files:

companion.bootstrap.json
platform starter file (CompanionBootstrap.swift, CompanionBootstrap.kt, or MenuBarCompanion.swift)
README.md

Verify Bundle Integrity

On the target host (before launch), verify checksums:

cd ./dist/companion-macos
sha256sum --check CHECKSUMS.sha256

Expected result:

all bundle files report OK

If signature is present, verify CHECKSUMS.sha256.sig with your org signing key policy before launch.

Automated CLI verification mode:

flynn companion \
  --verify-release-bundle ./dist/companion-macos \
  --verify-signing-key ./keys/release-public.pem \
  --verify-signing-key-id team-k1 \
  --require-signature

Launch

./run-companion.sh

Optional handoff smoke test:

./run-companion.sh --handoff "status check"

Platform Notes

ios and macos default push provider to apns when --push-token is set.
android defaults push provider to fcm when --push-token is set.
For linux, windows, or unknown platforms, specify --push-provider explicitly when using --push-token.

Distribution Guidance

Treat companion.bootstrap.json as sensitive if it includes gateway tokens or push tokens.
Remove or rotate secrets before sharing bundles externally.
For signed releases, sign the bundle directory or tarball with your standard org release-signing process after checksum verification.

2.4 KiB Raw Blame History