0.3.0: client configuration, address management, relays, and file exchange

[lundog]

Turns the bridge from a bare Websocket endpoint into a fully configurable SimpleX client, driven from the StartOS UI, and bundles simplex-chat v6.5.5.

Targets master on start-sdk 1.5.3. Pinned to start-sdk 1.5.3, which installs and runs on my StartOS (0.4.0-beta.9) — verified on hardware. (I first rebased this onto next/2.0.5, but I couldn't get a 2.0.x build to start on my box: init completes but the service never reaches main. Still working out why — details in the linked startup report. I'll rebase this forward onto the 2.0 line once that's sorted.) The file-exchange layout intentionally uses a single /data mount (no neutral /simplex re-mount) — see File exchange below.

Image

• lundog/simplex-websocket-bridge:6.5.5-2 (was simplex-chat v6.5.4): bundles v6.5.5, raises the websocat message ceiling (default 16 MiB), adds optional received-files retention. License declared MIT AND AGPL-3.0-only (bundled simplex-chat is AGPL-3.0).
• Fixes a connect-time bug: websocat's 64 KiB default split large SimpleX events (e.g. a new-contact event, ~77 KB) into two frames, breaking JSON parsing (Unterminated string … at position 65536).

Configuration

All client settings live in client-settings.json (read on start; can be set before first start). Configure Client action (replaces Configure Bot Profile):

• Display name, full name, profile picture, peer type, auto-accept contact requests, business mode, welcome message, message relays, received-file cleanup.
• Profile picture accepts an image URL (http/https, fetched with timeout + size cap), a data URL, or raw base64 → center-cropped square and shrunk to a ≤12 KB JPEG (jimp) to fit SimpleX's avatar limit.
• Application model: profile/address and relay changes apply live over the Websocket (no restart); only a received-file-retention change restarts (it's a container/janitor env). Reads are non-reactive so saving settings doesn't restart the service mid-edit.
• Hands-off mode (manageProfile, default on): a "SimpleX Profile" union offers Managed by StartOS vs Managed by my application. When app-managed, the bridge makes no Websocket writes (start-time sync skipped) and applies relays + cleanup via container env, so a non-OpenClaw app can own the profile, address, and runtime server changes itself. Env relays are set-once (--server persists in the DB), so reverting to public is then the app's responsibility.

Message relays

Public / self-hosted SimpleX Server / custom SMP+XFTP, applied over the client's operator-servers API (/_servers GET → mutate → SET), not the container --server flag.

• simplex-chat persists relay config in its DB and only uses presets when none are set, so the flag stuck and dropping it never reverted to public. The round-trip enables presets / disables+replaces custom per protocol, so switching (including back to public) is authoritative. Applied on every (re)start and live on change.
• Local declares an optional dependency on the simplex package and auto-pulls its SMP/XFTP addresses from that package's service interfaces (preference: clearnet domain → clearnet IP → Tor → .local).

Addresses & lifecycle

• View SimpleX Address / Reset SimpleX Address (Danger Zone, no stop) for the long-lived reusable address; Create SimpleX Invitation still covers one-time links.
• Reset Client (was Reset Profile) — expanded warning incl. the OpenClaw reused-contact-id caveat.

Reliability

• Start-time settings sync waits for the Websocket to actually answer (waitForBotReady) before syncing, fixing an ECONNREFUSED race against websocat's bind.

File exchange (consumer packages)

Single /data mount; consumers use mountDependency on subpaths (optional dependency, opt-in):

• Inbound — name-only: mount .simplex/files read-only at any path; resolve reported filenames against it.
• Outbound — mount .simplex/outbound read-write at any path; pass the bridge path (/data/.simplex/outbound/<name>), translating the prefix. The openclaw-simplex plugin does this via connection.outboundFolder + connection.outboundFolderOnClient. No shared/verbatim mountpoint needed.
• DB and keys stay private; consumers never mount .simplex/ or the whole volume.

Version / migration

0.3.0:0; no data migration (client-settings.json is created on demand, store.json/keys unchanged).

Testing

Installed against a live StartOS and verified:

• Live display-name change and avatar-from-URL applied with no restart.
• Relays: invitations and addresses used the expected server in public / custom / local; switching back to public reset to presets reliably.
• View SimpleX Address / Reset SimpleX Address and Reset Client behaved as documented.
• Connections: iOS client connected via invitation QR; the previously-splitting large connect event now parses cleanly.
• File exchange (end-to-end): a companion openclaw-startos change mounts the bridge's .simplex/files (ro) and .simplex/outbound (rw) into OpenClaw; with the openclaw-simplex plugin installed (via CLI for now — StartOS auto-install is a later step), inbound and outbound files transferred through OpenClaw over the shared volume.

[lundog]

Changes completed for #3 and #4

[lundog]

Update: I've retargeted this PR to master and pinned start-sdk 1.5.3.

Earlier I rebased this branch onto next (start-sdk 2.0.5) so it would ride the SDK 2.0 transition. But I couldn't get a 2.0.x build to start on my StartOS (0.4.0-beta.9) — init runs to completion but the service never proceeds to main. I reproduced it on a clean install and with the unmodified next branch, so it doesn't seem specific to this package, but I haven't figured out the cause yet. (Details in the linked startup report.)

So for now this PR targets master at start-sdk 1.5.3, which installs and runs on my box — verified on hardware.

What changed:

• It's a single clean commit on top of master at start-sdk 1.5.3 — no 2.0 migration and none of next's commits.
• Local-relay auto-pull reads the simplex package's exported SMP/XFTP addresses via the 1.5.3 sdk.serviceInterface API.
• The file-exchange layout keeps the single /data mount (drops the neutral /simplex re-mount): consumers mount the .simplex/{files,outbound} subpaths at any path and translate outbound paths on their side (openclaw-simplex does this via connection.outboundFolder + connection.outboundFolderOnClient). This is the intended breaking change vs the two-mount approach — happy to discuss if you'd prefer to keep the second mount.

Happy to rebase this forward onto the 2.0 line once I've sorted out the startup issue.