Flow Mesh — Distribution Grid
How to get Flow Mesh into other people's hands.
Binary Facts
| Property | Value |
|---|---|
| Language | Go (pure, no CGO) |
| Binary size (stripped) | ~13 MB |
| Platforms | linux/darwin/windows × amd64/arm64 (6 targets) |
| Dependencies at runtime | None (SQLite embedded via modernc.org) — see Beads Dependency below |
| Linux release binary | Fully static (musl), no glibc floor — verified running on glibc 2.28 (2026-09-26) |
| Min Go version to build | 1.23+ (no post-1.21 language features used) |
| Config | config.yaml + env vars |
| Data | Single SQLite file (WAL mode) |
| Ports | 127.0.0.1:8300 (default, loopback only) |
Authentication
Built-in multi-user auth with bcrypt password hashing and HMAC-signed session cookies.
Environment Variables
| Variable | Required | Description |
|---|---|---|
FLOW_MESH_AUTH |
No | on / off — force auth state. Default: smart detection |
FLOW_MESH_USER |
No | Bootstrap username (upserted into DB on startup) |
FLOW_MESH_PASS |
No | Bootstrap password (upserted into DB on startup) |
Smart Activation (default behavior)
| Listen Address | Auth Active | Reason |
|---|---|---|
127.0.0.1:8300 |
No | Loopback only — safe |
localhost:8300 |
No | Loopback only — safe |
0.0.0.0:8300 |
Yes | Network-exposed |
Any + FLOW_MESH_AUTH=on |
Yes | Explicit override (use with CF tunnel) |
Credential Sources (priority order)
- Env vars:
FLOW_MESH_USER+FLOW_MESH_PASS→ upserts bcrypt hash into DB on every startup - DB kv table:
auth_user:<username>→ bcrypt hash (created via wizard or env vars) - First-run wizard: If no users exist,
/loginshows "Create Account" form
Session Cookies
- Format:
username|timestamp|HMAC-SHA256-signature - Signing key: 32-byte random, auto-generated on first run, stored in DB
kvtable (auth_hmac_secret) - TTL: 7 days
- Flags:
HttpOnly,SameSite=Lax,Path=/ - No server-side session state: validation is pure HMAC check (stateless)
Exempt Paths
| Path | Reason |
|---|---|
/login |
Login page itself |
/logout |
Cookie clear + redirect |
/api/health |
Health checks (monitoring, load balancers) |
/webhooks/* |
Asana webhook delivery (uses own auth) |
Per-Deployment Configuration
| Deployment | Auth Setup |
|---|---|
| Docker | environment: [FLOW_MESH_AUTH=on, FLOW_MESH_USER=admin, FLOW_MESH_PASS=...] |
| systemd | Environment="FLOW_MESH_AUTH=on" + Environment="FLOW_MESH_USER=..." |
| Tauri desktop | First-run wizard (loopback, auth optional) |
| Behind CF/nginx | FLOW_MESH_AUTH=on (exposed via tunnel) |
| Local dev | No config needed (loopback auto-disables auth) |
Multi-User Support
- Users stored as
auth_user:<username>in kv table - Add users via env vars (one at startup) or future admin UI
- Each session cookie identifies the user (
X-Auth-Userheader set for downstream) - User management API planned for Settings page
Invisible Dependency: Beads (bd)
Flow Mesh's "source" layer has a silent contract:
- Reading
.beads/directories works with no external tool — Flow Mesh scans the filesystem directly, polls for event changes, and ingests them into the ledger. - Writing beads (creating issues, closing tasks, adding comments) requires
bd— a separate Go binary that must be independently installed.
A new user can install Flow Mesh, connect Asana, connect Discord, discover repos... and the source layer is half-broken unless they also have bd. Nothing in the current setup wizard warns about this. The README doesn't list it as a prerequisite.
Options
| Approach | Pros | Cons |
|---|---|---|
Bundle bd in the mesh binary |
Single binary, zero extra installs | Couples release cycles; bd is its own project |
mesh bd subcommand |
Self-contained; users learn one tool | Not implemented. bd is a separate binary today; offering a pass-through is an option, not a feature |
| Document as prerequisite | Honest, simple | Two install steps; friction for new users |
| Make beads optional | Source provider works for git-only repos; Asana↔Discord sync still works without beads | Loses the local event layer; "beads" is in the product name |
| Auto-detect and prompt | Setup wizard checks which bd, shows install link if missing |
Polite but doesn't solve the underlying dependency |
| Provider declares deps | Clean architecture — git-beads provider says "needs bd ≥ v1.0", git-plain provider has no such requirement |
Requires hook/provider system (see docs/HOOKS.md) |
Recommendation
Short term: auto-detect + prompt in the setup wizard. The /setup page already checks Asana/Discord connectivity — add a bd check too. Show install instructions when missing.
Long term: provider declares deps. When the hook system exists, the git-beads source provider declares bd as a dependency. A git-plain provider works without it. The Tauri desktop app (see below) can bundle bd alongside mesh in the app bundle.
Impact on Distribution Channels
| Channel | Beads Impact |
|---|---|
| GitHub Releases | Document bd as optional prerequisite in release notes |
| Docker | Bundle bd in the container image (add to Dockerfile) |
| npm wrapper | Include bd binary alongside mesh in platform packages |
| Tauri app | Bundle in .app/Contents/Resources/ |
| Homebrew | Add depends_on "beads" or bundle |
Distribution Channels
Tier 1 — Do First
0. flowme.sh direct download (LIVE since 2026-09-26)
| Effort | Done — tarball served from WordPress uploads, 301 redirect in place |
| Reach | Any developer with a browser; linked from the site's Download CTAs and install terminal |
| Prerequisites | None for the visitor (repo stays private; no GitHub account needed) |
| User experience | curl + tar + run |
Live layout (verified 2026-11-01):
https://flowme.sh/mesh.tgz→ 301 →/wp-content/uploads/mesh.tgz(13.8 MB)- Tarball contains
flow-mesh/mesh-linux-amd64,flow-mesh/mesh-darwin-arm64,flow-mesh/checksums.txt, andREADME.txtwith quick-start + license activation - The binaries are the published release artifacts for 1.0.0, not a separate build:
mesh-linux-amd64printsflow-mesh 1.0.0and its digest matches the release tarball https://flowme.sh/install.shserves the installer described below- Theme source of record:
landing/wp-theme/flowmesh/(Gutenberg block theme, mobile-first, visually verified at 395 / 760 / 1024 / 1440 px)
User install (matches the on-site terminal):
curl -fsSL https://flowme.sh/install.sh | sh
mesh config init && mesh serve
# → http://localhost:8300 — setup wizard connects Asana + Discord
The previous on-site one-liner (curl -LO .../mesh.tgz && tar xzf mesh.tgz && ./mesh serve) never worked: the archive's binary lives under flow-mesh/, and ./mesh did not exist. The download now carries checksums.txt so a hand-extracted copy can be verified with sha256sum -c flow-mesh/checksums.txt.
The pre-1.0.0 tarball is preserved at mesh.tgz.rollback-20261101-dev in the same uploads directory; its binaries reported flow-mesh dev, which is why it was replaced.
Static rebuild recipe (still valid if a musl-only deployment is needed): CGO_ENABLED=1 CC=musl-gcc go build -ldflags "-linkmode external -extldflags -static" ./cmd/mesh
1. GitHub Releases (goreleaser)
| Effort | ~30 min |
| Reach | Any developer on any OS |
| Prerequisites | Tag a version, goreleaser installed or use GitHub Actions |
| User experience | curl + tar + run |
Prove the matrix before a tag exists. A tag is the one release step that cannot be quietly undone, so the six targets are built and recorded first:
./scripts/release-proof.sh # builds all six, writes deploy/release/release-proof.v1.json
./scripts/release-proof.sh --check # fails if the proof and VERSION/matrix disagree
Verified 2026-11-01 from canonical source at version 1.0.0: all six targets build, each carries the stamp, and the native linux/amd64 binary reports flow-mesh 1.0.0 when executed. Digests and sizes are recorded per target in the proof file, which also names what it did not establish — archive assembly, SBOM emission and checksum-file naming — because goreleaser is not installed on the build host. Those steps are configured, not exercised.
Setup:
# Tagging publishes to the canonical repository (private).
git tag v1.0.0
git push --tags
# .github/workflows/release.yml runs goreleaser on tag push.
# Local alternative, if goreleaser is installed:
goreleaser release --clean
User install:
# Linux amd64 (asset name template: flow-mesh_<version>_<os>_<arch>)
curl -Lo flow-mesh.tar.gz \
https://github.com/Startempire-Wire/flow-mesh/releases/latest/download/flow-mesh_1.0.0_linux_amd64.tar.gz
tar xzf flow-mesh.tar.gz
sudo mv mesh /usr/local/bin/
mesh config init
mesh serve
Install script — verbs, state, and verification
curl -fsSL https://flowme.sh/install.sh | sh # install (default verb)
curl -fsSL https://flowme.sh/install.sh | sh -s -- upgrade # newer release
curl -fsSL https://flowme.sh/install.sh | sh -s -- rollback # back to the previous one
curl -fsSL https://flowme.sh/install.sh | sh -s -- status # what is installed, from the manifest
curl -fsSL https://flowme.sh/install.sh | sh -s -- uninstall # remove the command and version store
Two channels, because the product surface and the source repository are different things. FLOW_MESH_CHANNEL=public (default) fetches the flowme.sh bundle, which carries the two platforms the site advertises. FLOW_MESH_CHANNEL=github resolves the published release through the API with GITHUB_TOKEN and covers the platforms the bundle omits (linux/arm64, darwin/amd64, windows/amd64, windows/arm64). A platform the chosen channel does not serve is named explicitly rather than downloaded and left to fail at exec time.
Every path verifies a digest. The public bundle carries checksums.txt inside the archive, so the list and the payload arrive together; the github channel fetches the release's published checksums.txt. An installer that runs an unverified download is a supply-chain hole, not a convenience.
Layout and rerun safety:
| Command | ${INSTALL_DIR}/mesh (default /usr/local/bin/mesh) — a symlink |
| Version store | ${FLOW_MESH_STATE_DIR:-~/.local/state/flow-mesh}/versions/<version>/mesh |
| Manifest | .../flow-mesh/install.json — version, previous, channel, asset, digest, paths, time |
| Data | platform data dir (~/.local/share/flow-mesh on Linux, ~/Library/Application Support/flow-mesh on macOS), FLOW_MESH_DATA_DIR to relocate |
| Config | ./config.yaml relative to where mesh runs, FLOW_MESH_CONFIG to relocate |
Versions are kept side by side and the command is a symlink into that store, so upgrade and rollback are pointer swaps rather than overwrites, and rollback is itself reversible (the manifest swaps version and previous). Rerunning the same version re-verifies the installed digest and changes nothing; if the installed binary no longer matches, it says so and points at upgrade instead of silently re-downloading. uninstall removes the command and the version store and names the data directory and config it deliberately left alone — an uninstall that deletes a database is a foot-gun, not a feature.
FLOW_MESH_BUNDLE_FILE=<path> stages a local bundle for offline installs; the digest check still runs, so it is not a bypass.
Proven by internal/e2e/installer_lifecycle_test.go, which drives the verbs: install, rerun-is-a-no-op, upgrade keeps both versions, rollback returns to the previous and records the swap, uninstall removes the command and store while naming what it preserved, a tampered bundle is refused with no command left on PATH, rollback with no history refuses and changes nothing, and an unknown verb is refused.
A guard test keeps install.sh's REPO equal to the release owner and name in .goreleaser.yaml, and keeps the asset name derived from version/os/arch, so the one-liner cannot start pointing somewhere the release never publishes.
Status (2026-11-01): published. Tag v1.0.0 (commit 812840e) is live with 14 assets; releases/latest resolves it; flowme.sh/mesh.tgz is rebuilt from those assets and verified end to end through the public installer.
This release could not be built by CI. Every Actions run on the Startempire-Wire organisation fails at workflow startup with BuildFailed and zero jobs, including plain master pushes, so a tag push publishes nothing. The assets were therefore assembled by scripts/release-build.sh from a clean checkout of the tag — the same six targets and archive shape .goreleaser.yaml declares, plus checksums.txt, per-binary module inventories, and release-artifacts.v1.json recording the commit and digests. It records goreleaser_used: false and states that SBOMs are Go module inventories rather than SPDX, because syft is not installed on the build host. The workflow itself is fixed and ready (container namespace, README URL); it will produce the same release once Actions runs again. That is a hosting/billing question for the owner, not a code defect.
2. Docker and Compose
| Effort | Done — Dockerfile + docker-compose.yml + .env.example |
| Reach | Anyone with Docker or Podman |
| Prerequisites | A container runtime; no account, because the Compose path builds the checkout |
| User experience | copy .env.example, set two secrets, docker compose up -d |
cp .env.example .env # set FM_PASS and FLOW_MESH_SECRET (openssl rand -hex 32)
docker compose up -d
docker compose ps # wait for (healthy)
curl -s localhost:8300/healthz
What the file guarantees, and why each line is there
| Property | How | Why it matters |
|---|---|---|
| Versioned | image: ghcr.io/startempire-wire/flow-mesh:${FLOW_MESH_VERSION:-1.0.0} |
a :latest tag deploys whatever happens to be latest on the day of the rerun |
| Stamped | the same value goes to build.args.VERSION → -X main.version |
a build context has no .git, so git describe labelled every image dev |
| Loopback by default | "${FLOW_MESH_BIND:-127.0.0.1}:${FLOW_MESH_PORT:-8300}:8300" |
publishing a service is a decision, not a default |
| No invented secrets | FLOW_MESH_PASS and FLOW_MESH_SECRET use ${VAR:?reason} |
the stack refuses to start rather than coming up with changeme on a reachable port |
| Encryptable credentials | FLOW_MESH_SECRET required |
without it the server can store no provider credential and reports every provider unconfigured |
| No invented providers | provider tokens pass through as ${VAR:-} |
an unset token stays unset and is reported as "not configured" |
| Real health probe | wget --spider 127.0.0.1:8300/healthz |
probing a path the router does not serve marks a dead container healthy |
| Durable data | named volume at /data, FLOW_MESH_DB=/data/flow-mesh.db |
a rerun must not lose the database |
| Hardened | runs as the image's non-root mesh user, no-new-privileges |
FLOW_MESH_LISTEN=0.0.0.0:8300 inside the container is correct and unrelated to exposure: that is the container's own interface, and the port mapping is what decides who can reach it.
Verified 2026-11-01 from a clean directory on the execution host (archive extract, no .env, no prior images for this project): build → docker compose up -d → Up (healthy) → mesh version prints flow-mesh 1.0.0 → /healthz returns {"status":"ok","encryption":true,"version":"1.0.0"} → listener is 127.0.0.1:8398 only → a second up -d converges to Running without recreating → removing FM_PASS refuses to start with the reason → down -v leaves nothing behind.
internal/e2e/compose_contract_test.go keeps those properties honest: it decodes the file and asserts the namespace, the pinned tag, the version stamp reaching the build, the loopback default, the required-secret form, that no provider token is fabricated, and that the probe path is a route the router actually serves.
The published image is not available yet. GHCR push happens in the Release workflow, which cannot run on this organisation (every Actions run fails at startup with zero jobs). Compose therefore builds the checkout locally, which is why the file keeps build: beside image:. Once Actions runs, docker compose up -d will pull the pinned image instead.
Tier 2 — High Impact, Medium Effort
3. npm Binary Wrapper
| Effort | ~2 hours |
| Reach | Widest — anyone with Node.js |
| Prerequisites | npm account, platform binary builds |
| User experience | npx flow-mesh serve or npm i -g flow-mesh |
Uses the esbuild/turbo pattern: platform-specific optional dependencies.
Package structure:
@flow-mesh/linux-x64/ → contains linux amd64 binary
@flow-mesh/linux-arm64/ → contains linux arm64 binary
@flow-mesh/darwin-x64/ → contains macOS amd64 binary
@flow-mesh/darwin-arm64/ → contains macOS arm64 binary (Apple Silicon)
@flow-mesh/win32-x64/ → contains windows amd64 .exe
flow-mesh/ → main package, picks correct platform
Main package.json:
{
"name": "flow-mesh",
"version": "0.1.0",
"bin": { "flow-mesh": "bin/flow-mesh", "mesh": "bin/flow-mesh" },
"optionalDependencies": {
"@flow-mesh/linux-x64": "0.1.0",
"@flow-mesh/linux-arm64": "0.1.0",
"@flow-mesh/darwin-x64": "0.1.0",
"@flow-mesh/darwin-arm64": "0.1.0",
"@flow-mesh/win32-x64": "0.1.0"
}
}
Launcher script (bin/flow-mesh):
#!/usr/bin/env node
const { execFileSync } = require("child_process");
const path = require("path");
const os = require("os");
const PLATFORMS = {
"linux-x64": "@flow-mesh/linux-x64",
"linux-arm64": "@flow-mesh/linux-arm64",
"darwin-x64": "@flow-mesh/darwin-x64",
"darwin-arm64": "@flow-mesh/darwin-arm64",
"win32-x64": "@flow-mesh/win32-x64",
};
const key = `${os.platform()}-${os.arch()}`;
const pkg = PLATFORMS[key];
if (!pkg) { console.error(`Unsupported platform: ${key}`); process.exit(1); }
const bin = require.resolve(`${pkg}/mesh${os.platform() === "win32" ? ".exe" : ""}`);
execFileSync(bin, process.argv.slice(2), { stdio: "inherit" });
Pros: Broadest reach, npx just works, agents already have Node.
Cons: 6 packages to maintain, npm publish on every release, ~13MB per platform package.
Automation: Add to goreleaser post-hooks or GitHub Actions release workflow.
Status: Not started. Requires npm org @flow-mesh.
4. Tauri Desktop + Mobile App
| Effort | ~1–2 weeks |
| Reach | macOS menubar users, iOS, Android |
| Prerequisites | GitHub Releases for the Go binary; Rust toolchain; Xcode (iOS); Android SDK |
| User experience | Native app — double-click install, menubar icon, zero terminal |
Tauri 2.0 (stable since Oct 2024) supports macOS, Linux, Windows, iOS, and Android from a single codebase. The frontend is a webview — Flow Mesh's existing htmx UI runs inside it unchanged.
Architecture:
┌──────────────────────────────────────────────────┐
│ Flow Mesh.app (Tauri 2.0) │
│ │
│ ┌────────────┐ ┌─────────────────────────────┐ │
│ │ Rust core │ │ Webview (system) │ │
│ │ │ │ │ │
│ │ • spawn Go │ │ Existing htmx dark UI │ │
│ │ binary │ │ pointed at 127.0.0.1:PORT │ │
│ │ • tray │ │ │ │
│ │ icon │ │ No changes needed — │ │
│ │ • menu │ │ same templates, same CSS, │ │
│ │ • auto- │ │ same htmx interactions │ │
│ │ start │ │ │ │
│ │ • notify │ └─────────────────────────────┘ │
│ └─────┬──────┘ │
│ │ spawns child process │
│ ┌─────▼──────┐ │
│ │ mesh serve │ ← Go binary bundled in app │
│ │ :0 (random)│ ← reports actual port to Rust │
│ │ + bd │ ← beads binary also bundled │
│ └────────────┘ │
└──────────────────────────────────────────────────┘
macOS Menubar:
┌──┐
Menu Bar │⬡ │ ← woven flow icon
└──┘
│
┌─────────────────────────────▼───────┐
│ Flow Mesh │
│ ● 3 meshes active │
│ ● 2 events pending │
│ ● Asana ✓ Discord ✓ Beads ✓ │
│ │
│ ┌───────────────────────────────┐ │
│ │ Open Dashboard ⌘D │ │
│ │ Pause All Sync ⌘P │ │
│ │ Force Sync Now ⌘S │ │
│ │ ─────────────────────────────│ │
│ │ Settings... ⌘, │ │
│ │ View Logs... │ │
│ │ ─────────────────────────────│ │
│ │ Quit ⌘Q │ │
│ └───────────────────────────────┘ │
└─────────────────────────────────────┘
What changes in Flow Mesh for Tauri:
| Area | Change | Why |
|---|---|---|
| Listen port | Support :0 (random port), print actual port to stdout |
Multiple instances, no port clash |
| Data dir | Respect FLOW_MESH_DATA_DIR → ~/Library/Application Support/Flow Mesh/ (macOS), %APPDATA%\Flow Mesh\ (Windows) |
Standard OS paths |
| Shutdown | Already done (graceful SIGTERM) | Tauri sends SIGTERM on quit |
| Health | /api/health already exists |
Tauri polls for tray icon status |
| UI | No changes — htmx UI works as-is in a webview | That's the whole point |
| Bundled bins | mesh + bd in app resources |
Solves the beads dependency |
Mobile (iOS + Android):
Tauri 2.0 compiles to native mobile apps from the same codebase. The webview renders the existing htmx UI. Key differences for mobile:
| Concern | Desktop | Mobile |
|---|---|---|
| Go binary | Bundled, runs as child process | Cross-compile to arm64, run as background service or embed via gomobile |
| SQLite | File on disk | Same — app sandbox storage |
| Notifications | Tray icon + OS notifications | Push notifications (Tauri plugin) |
| Background sync | Always running while app open | OS-managed background tasks (limited on iOS) |
| UI | Already mobile-first (375px+) | Works as-is — that's why we built mobile-first |
| Distribution | .dmg / .msi / .AppImage |
App Store / Google Play / TestFlight / APK sideload |
iOS specifics:
- Go binary cross-compiles to
darwin/arm64(same target as Apple Silicon Mac) - Can use
gomobileto produce.frameworkcallable from Swift, or run as embedded subprocess - Background App Refresh for sync (limited to ~30s per wake, but sufficient for polling)
- App Store distribution requires Apple Developer account ($99/yr)
Android specifics:
- Go binary cross-compiles to
linux/arm64(Android NDK) - Can use
gomobileto produce.aarcallable from Kotlin, or run as foreground service - Foreground service keeps sync alive (shows persistent notification)
- Google Play or direct APK distribution
Tauri project structure:
flow-mesh-app/
src-tauri/
src/main.rs # Rust: spawn mesh binary, tray, menu
tauri.conf.json # Window config, bundle settings
resources/
mesh # Go binary (per-platform)
bd # Beads binary (per-platform)
Cargo.toml
src/
index.html # Just an iframe/redirect to localhost:PORT
# Or: proxy through Tauri's asset protocol
package.json
Build matrix:
| Target | Build Command | Output |
|---|---|---|
| macOS (universal) | cargo tauri build --target universal-apple-darwin |
.dmg + .app |
| Windows | cargo tauri build --target x86_64-pc-windows-msvc |
.msi + .exe |
| Linux | cargo tauri build --target x86_64-unknown-linux-gnu |
.AppImage + .deb |
| iOS | cargo tauri ios build |
.ipa (TestFlight/App Store) |
| Android | cargo tauri android build |
.apk / .aab (Play Store) |
Size estimates:
| Component | Size |
|---|---|
| Tauri runtime (Rust + system webview) | ~2–4 MB |
mesh binary (stripped, compressed) |
~6 MB |
bd binary (stripped, compressed) |
~3 MB |
| Total app | ~11–13 MB |
Compared to Electron (~150 MB), this is tiny.
Distribution for Tauri builds:
| Channel | Method |
|---|---|
| macOS | .dmg on GitHub Releases + brew install --cask flow-mesh |
| Windows | .msi on GitHub Releases + winget manifest |
| Linux | .AppImage + .deb on GitHub Releases |
| iOS | TestFlight → App Store |
| Android | GitHub Releases .apk + Google Play |
Status: Not started. Requires Tauri project scaffold + Go cross-compilation CI.
5. go install (Public Repo)
| Effort | 5 min (flip repo visibility) |
| Reach | Go developers |
| Prerequisites | Make repo public |
| User experience | go install github.com/Startempire-Wire/flow-mesh/cmd/mesh@latest |
Decided (owner, 2026-09-26): repo stays private and closed-source — this channel is closed. Distribution runs through flowme.sh direct download (§0) and licensed binaries, which need no GitHub account and no GOPRIVATE.
Status: Closed. Reopen only on explicit owner direction.
Tier 3 — Polish
6. Homebrew Tap
| Effort | ~1 hour |
| Reach | macOS + Linux Homebrew users |
| Prerequisites | GitHub Releases (Tier 1) |
| User experience | brew install startempire-wire/tap/flow-mesh |
Setup:
# Create repo: github.com/Startempire-Wire/homebrew-tap
# Add formula:
Formula (Formula/flow-mesh.rb):
class FlowMesh < Formula
desc "Bidirectional Asana ⇄ Beads ⇄ Discord sync engine"
homepage "https://flowme.sh"
version "0.1.0"
on_macos do
on_arm do
url "https://github.com/Startempire-Wire/flow-mesh/releases/download/v0.1.0/flow-mesh_0.1.0_darwin_arm64.tar.gz"
sha256 "PLACEHOLDER"
end
on_intel do
url "https://github.com/Startempire-Wire/flow-mesh/releases/download/v0.1.0/flow-mesh_0.1.0_darwin_amd64.tar.gz"
sha256 "PLACEHOLDER"
end
end
on_linux do
on_arm do
url "https://github.com/Startempire-Wire/flow-mesh/releases/download/v0.1.0/flow-mesh_0.1.0_linux_arm64.tar.gz"
sha256 "PLACEHOLDER"
end
on_intel do
url "https://github.com/Startempire-Wire/flow-mesh/releases/download/v0.1.0/flow-mesh_0.1.0_linux_amd64.tar.gz"
sha256 "PLACEHOLDER"
end
end
def install
bin.install "mesh"
end
test do
assert_match "flow-mesh", shell_output("#{bin}/mesh version")
end
end
Can automate once the tap exists. goreleaser's brews block is currently commented out in .goreleaser.yaml: it pointed at Philoveracity/homebrew-tap, a repository under the redirecting owner that the canonical release cannot write to. Creating Startempire-Wire/homebrew-tap is a new remote repository and needs explicit owner authorization, so the block stays disabled and this channel stays honestly "not started" rather than publishing to the wrong owner. The intended configuration, for when the tap exists:
brews:
- repository:
owner: Startempire-Wire
name: homebrew-tap
homepage: https://flowme.sh
description: "Bidirectional Asana ⇄ Beads ⇄ Discord sync engine"
Status: Not started. Depends on Tier 1.
7. Install Script
| Effort | ~30 min |
| Reach | curl-pipe-sh crowd |
| Prerequisites | GitHub Releases (Tier 1) |
| User experience | curl -fsSL .../install.sh | sh |
Script auto-detects OS/arch, downloads correct binary, installs to /usr/local/bin.
Status: Not started. Depends on Tier 1.
CI/CD Pipeline
Everything above triggers from one action: push a git tag.
git tag v0.1.0 && git push --tags
│
▼
┌─────────────────────────────────┐
│ GitHub Actions Release Workflow │
├─────────────────────────────────┤
│ │
│ 1. goreleaser build │
│ → 6 binaries (tar.gz/zip) │
│ → GitHub Release + assets │
│ → checksums.txt │
│ │
│ 2. Docker build + push │
│ → ghcr.io/startempire-wire/ │
│ flow-mesh:v1.0.0 │
│ → ghcr.io/startempire-wire/ │
│ flow-mesh:latest │
│ │
│ 3. Homebrew tap update │
│ → auto-PR to homebrew-tap │
│ │
│ 4. npm publish (optional) │
│ → 5 platform packages │
│ → 1 main package │
│ │
│ 5. Tauri builds (separate CI) │
│ → .dmg (macOS universal) │
│ → .msi (Windows x64) │
│ → .AppImage/.deb (Linux) │
│ → .ipa (iOS TestFlight) │
│ → .apk (Android) │
│ │
└─────────────────────────────────┘
Workflow file needed: .github/workflows/release.yml
Recommended Rollout Order
Week 1: Tag v0.1.0 → GitHub Releases + Docker (GHCR)
↳ Covers: curl install, docker run, docker compose
↳ Effort: ~1 hour including CI workflow
Week 2: Homebrew tap + install script + npm wrapper
↳ Covers: brew install, curl | sh, npx flow-mesh serve
↳ Effort: ~3 hours
Week 3–4: Tauri desktop app (macOS menubar first)
↳ Covers: .dmg, menubar icon, zero-terminal experience
↳ Effort: ~1 week (scaffold + cross-compile CI + test)
Week 5: Tauri mobile (iOS + Android)
↳ Covers: TestFlight, APK, eventually App Store + Play Store
↳ Effort: ~1 week (gomobile integration + mobile-specific testing)
Ongoing: go install (when/if repo goes public)
Why Tauri Before npm
The Tauri app is higher priority than the npm wrapper because:
- Mac users are the primary audience — developers on MacBooks want a menubar app
- Mobile unlocks a new user class — check mesh status from your phone
- Solves the beads dependency — bundle
bdin the app, no extra install - One codebase → 5 platforms — macOS, Windows, Linux, iOS, Android
- npm wrapper serves developers who already have a terminal — they can use GitHub Releases just fine
Pre-Release Checklist
Week 1: Core Release
- [ ] Lower
go.modtogo 1.23(wider compatibility, no 1.25 features used) - [ ] Add
bdversion check to setup wizard (invisible dependency fix) - [ ] Add
mesh serve --port 0support (random port, print to stdout — needed for Tauri) - [ ] Add
FLOW_MESH_DATA_DIRenv var support (OS-appropriate paths) - [ ] Tag
v0.1.0 - [ ] Create
.github/workflows/release.yml - [ ] Test Docker build locally:
docker build -t flow-mesh .(includebdin image) - [ ] Test goreleaser dry-run:
goreleaser release --snapshot --clean - [x] Decide: public or private repo? — Decided 2026-09-26: private, closed-source per owner
- [ ] Write
install.shauto-detect script - [ ] Create
docker-compose.ymlexample in repo root
Week 2: Package Managers
- [ ] If npm: register
@flow-meshorg on npmjs.com - [ ] Create
Startempire-Wire/homebrew-taprepo - [ ] Add goreleaser Homebrew tap config
- [ ] Test
brew install startempire-wire/tap/flow-mesh
Week 3–4: Tauri Desktop
- [ ] Scaffold Tauri project (
flow-mesh-app/directory or separate repo) - [ ] Rust sidecar: spawn
mesh serve --port 0, capture port from stdout - [ ] Tray icon + menu (Open Dashboard, Pause, Force Sync, Quit)
- [ ] Health polling → tray icon color (green/amber/red)
- [ ] Bundle
mesh+bdbinaries in app resources - [ ] macOS:
.dmgbuild + test on Apple Silicon - [ ] macOS: auto-start on login (Login Items)
- [ ]
brew install --cask flow-meshformula - [ ] Windows:
.msibuild + test - [ ] Linux:
.AppImage+.debbuild + test
Week 5: Tauri Mobile
- [ ] Cross-compile Go to
darwin/arm64(iOS) andlinux/arm64(Android NDK) - [ ] Evaluate:
gomobileframework vs embedded subprocess - [ ] iOS: background sync strategy (Background App Refresh)
- [ ] Android: foreground service for persistent sync
- [ ] iOS: TestFlight build + internal testing
- [ ] Android: APK build + sideload testing
- [ ] Apple Developer account ($99/yr) if pursuing App Store
- [ ] Google Play Developer account ($25 one-time) if pursuing Play Store
Release rollback
A release is reversible at three layers, in increasing blast radius. Roll back only as far as the fault requires, and verify the installed version after each step.
1. Reinstall the previous version (default). The installer is version-pinned and leaves the data directory alone:
curl -fsSL https://flowme.sh/install.sh | VERSION=1.0.0 sh
mesh version
Binaries are replaced atomically per target, so an interrupted reinstall leaves either the old or the new binary, never a partial file. The database schema is forward-migrated; see layer 3 before downgrading across a schema change.
2. Restore the previous binary from a preserved copy. A deployment that keeps its own rollback copy (the reference deployment keeps the prior binary beside the service) can swap back without network access:
systemctl stop flow-mesh
cp /path/to/mesh.previous /usr/local/bin/mesh
systemctl start flow-mesh
curl -fsS http://127.0.0.1:8300/healthz
3. Restore data (only when the schema moved). Downgrading a binary against a newer schema is unsupported. Restore the database and configuration from the encrypted backup taken before the upgrade, using the isolated restore drill first so the restore itself is proven:
deploy/backup/restore-drill.sh --archive <backup> --key <passphrase-file> --parent /tmp/drill
The drill refuses protected production paths and reports production_mutated: false. Promote a drilled restore only after it reports database_integrity: ok and content_hashes: verified.
Order matters: verify assets before trusting a release, verify the installed version after installing, and verify the restore before replacing production.