Marmot
Protocol
Development Kit
Documentation
Apps
Awesome
Releases
Community
GitHub
Donate
Contact
Protocol
Development Kit
Documentation
Apps
Awesome
Releases
Community
GitHub
Donate
Contact
  • Start here

    • Documentation
  • Integration guides

    • Native apps · MarmotKit
    • Rust application runtime
    • C and native hosts
    • Bots and agents
    • Terminal and scripts
    • TypeScript quickstart
    • TypeScript storage
    • TypeScript networking
  • Reference

    • MarmotKit distribution
    • MarmotKit API
    • C API
    • Architecture
    • Upgrade guide

MarmotKit distribution

MDK 0.17.0View source on GitHub

This guide follows the latest stable release. Use the documentation at your installed version’s tag when working with an older release.

MarmotKit Binary Distribution

MarmotKit releases publish generated Swift/Kotlin APIs with matching native libraries as immutable GitHub Release assets. Apple consumers use a binary-target XCFramework ZIP, generated Swift, and a separate SDK privacy manifest. Android consumers unpack the Kotlin and JNI bundle into their app build.

The shared Apple Swift asset includes MDK's nextCancellable() subscription adapters. Remove any host-owned copy of CancellablePresentedChatList.swift when adopting this asset, or Swift will reject the duplicate methods. The existing Swift asset hash covers the generated bindings and adapters together; there is no extra support-file download.

Experimental device-group host test builds are separate from these published release/snapshot assets. Use the explicit build flag and experimental constructor, retain matching native and generated inputs, and take artifacts only from output-dev-device-groups/. Ordinary release automation and constructors do not opt in; never add policy-test timing overrides to a host artifact.

Apple privacy migration

Migration required for releases built with this change. Apple XCFrameworks now contain raw static-library slices, not resource-bearing frameworks. Updating only the binary URL loses SDK privacy delivery. Keep the remote SwiftPM binary target, but update all three matching release inputs and the wrapper's resource declaration together:

  • MarmotKitFFI-<identifier>.xcframework.zip for iOS, or MarmotKitFFI-macos-<identifier>.xcframework.zip for macOS.
  • MarmotKit-<identifier>.swift, shared by both platforms.
  • PrivacyInfo-ios-<identifier>.xcprivacy or PrivacyInfo-macos-<identifier>.xcprivacy, for that platform's build.

Download from the same exact release/snapshot tag. Verify the privacy asset with its sibling .sha256 using shasum -a 256 -c <filename>.sha256, and verify Swift/binary hashes against the platform manifest. SwiftPM also checks the binary ZIP against its .swiftpm-checksum. The platform privacy files are separately named so each build's feature selection and provenance remain explicit; their contents match when their privacy-relevant features match.

Place the Swift binding and the privacy asset in the existing Swift wrapper target, renaming them to MarmotKit.swift and PrivacyInfo.xcprivacy. Preserve the SDK declaration separately from the host application's own privacy manifest. The wrapper target must declare:

.target(
    name: "MarmotKit",
    dependencies: ["MarmotKitFFI"],
    resources: [.copy("PrivacyInfo.xcprivacy")],
    linkerSettings: [
        .linkedFramework("Security", .when(platforms: [.macOS])),
        .linkedFramework("SystemConfiguration", .when(platforms: [.macOS]))
    ]
)

Assign that wrapper's product to each consuming app and notification extension. Do not add an extra host-compiled copy of the generated Swift. SwiftPM delivers the target's manifest in a resource bundle; Rust remains statically linked into each executable. No additional complete-package ZIP or new Rust binary is published. Existing provenance bundle ZIPs include all three inputs plus manifest.json, but are not themselves binary-target archives.

Platform manifests identify this layout with distribution: static-library-and-privacy-v1 and hash the privacy asset alongside Swift, the ZIP and each static library. Keep all inputs on one identifier; automate their synchronization. Consumers of 0.10.0 and earlier retain the old framework layout. No published release is modified. Direct Xcode consumers must provide and validate an equivalent SDK resource bundle or use the Swift wrapper.

Release CI builds a simulator consumer and archives iOS app/notification-extension and macOS consumers from the released ZIP, matching Swift and privacy assets. It checks resource content in each consumer, unchanged static linkage, real Rust references, executable/dSYM UUIDs, and absence of the empty framework stub. The fixture uses a local binary target after checking the downloaded ZIP's hash; existing remote SwiftPM link checks still exercise the URL and checksum path. Signed export, Organizer privacy report and App Store Connect upload remain separate host checks. Rust source-level debug information is unchanged and belongs in the crash-symbol PR.

Consumer migration tracking records downstream adoption and host release evidence. See the privacy audit and adoption guide for outstanding privacy questions.

iOS

The iOS binary asset carries no platform token in its name, for backward compatibility with URLs consumers already pin. macOS assets are explicitly prefixed -macos-; an unprefixed MarmotKitFFI-<identifier> asset is always iOS.

Exact URLs

Formal release marmotkit-v<version>:

https://github.com/marmot-protocol/mdk/releases/download/marmotkit-v<version>/MarmotKitFFI-<version>.xcframework.zip
https://github.com/marmot-protocol/mdk/releases/download/marmotkit-v<version>/MarmotKit-<version>.swift
https://github.com/marmot-protocol/mdk/releases/download/marmotkit-v<version>/PrivacyInfo-ios-<version>.xcprivacy
https://github.com/marmot-protocol/mdk/releases/download/marmotkit-v<version>/PrivacyInfo-ios-<version>.xcprivacy.sha256

Snapshot for a full 40-character commit SHA <sha> reachable from master:

https://github.com/marmot-protocol/mdk/releases/download/marmotkit-snapshot-<sha>/MarmotKitFFI-snapshot-<sha>.xcframework.zip
https://github.com/marmot-protocol/mdk/releases/download/marmotkit-snapshot-<sha>/MarmotKit-snapshot-<sha>.swift
https://github.com/marmot-protocol/mdk/releases/download/marmotkit-snapshot-<sha>/PrivacyInfo-ios-snapshot-<sha>.xcprivacy
https://github.com/marmot-protocol/mdk/releases/download/marmotkit-snapshot-<sha>/PrivacyInfo-ios-snapshot-<sha>.xcprivacy.sha256

A nightly <X.Y.Z>-nightly.<YYYYMMDD> uses the same names under the marmotkit-v<X.Y.Z>-nightly.<YYYYMMDD> tag; see Nightlies.

These URLs always contain an exact tag or snapshot identifier. Do not use a latest URL for SwiftPM artifacts.

SwiftPM

Follow the privacy migration as well as this binary declaration; the binary alone does not carry the SDK privacy resource.

Download the sibling .swiftpm-checksum asset or read the swiftpm record in marmotkit-ios-<identifier>.checksums.txt, then declare:

.binaryTarget(
    name: "MarmotKitFFI",
    url: "<exact URL above>",
    checksum: "<contents of .swiftpm-checksum>"
)

The consuming Swift package must declare iOS 18.0 or newer. The labeled records in checksums.txt are intended for inspection and provenance; they are not shasum -c input. Use the sibling .sha256 files for ordinary SHA-256 verification.

Add the matching MarmotKit-<identifier>.swift file to a Swift source target that depends on MarmotKitFFI. Update the binary URL, checksum, generated Swift source, and platform privacy file together. Mixing source and binary identifiers can compile against the wrong UniFFI ABI and is unsupported.

For manual verification, compare the ZIP with its .sha256 asset. The separately published marmotkit-ios-<identifier>.manifest.json records the full MDK source SHA, workspace version, Cargo.lock SHA-256, toolchain versions, enabled features, iOS targets and deployment target, effective Rust release profile, and hashes of the binary and generated Swift artifacts. rust_release_profile.lto follows Cargo's boolean-or-string representation: JSON false for the historical untuned control, and the string "thin" for current production. Codegen units remain an integer. Host and Apple artifacts keep strip as "none"; Android JNI builds apply symbols only on those target invocations. Apple builders also pass -C embed-bitcode=no and sanitize leftover Mach-O __LLVM / __bitcode sections so packaged archives stay native; that is not recorded as a strip change. The complete marmotkit-ios-<identifier>.zip retains the XCFramework, matching Swift source, PrivacyInfo.xcprivacy, and the same manifest for consumers that prefer a single provenance bundle.

macOS

macOS artifacts are Apple Silicon only: the XCFramework carries a single macos-arm64 slice built for aarch64-apple-darwin. There is no Intel or universal build.

Exact URLs

Formal release marmotkit-v<version>:

https://github.com/marmot-protocol/mdk/releases/download/marmotkit-v<version>/MarmotKitFFI-macos-<version>.xcframework.zip
https://github.com/marmot-protocol/mdk/releases/download/marmotkit-v<version>/PrivacyInfo-macos-<version>.xcprivacy
https://github.com/marmot-protocol/mdk/releases/download/marmotkit-v<version>/PrivacyInfo-macos-<version>.xcprivacy.sha256

Snapshot for a full 40-character commit SHA <sha> reachable from master:

https://github.com/marmot-protocol/mdk/releases/download/marmotkit-snapshot-<sha>/MarmotKitFFI-macos-snapshot-<sha>.xcframework.zip
https://github.com/marmot-protocol/mdk/releases/download/marmotkit-snapshot-<sha>/PrivacyInfo-macos-snapshot-<sha>.xcprivacy
https://github.com/marmot-protocol/mdk/releases/download/marmotkit-snapshot-<sha>/PrivacyInfo-macos-snapshot-<sha>.xcprivacy.sha256

SwiftPM

Follow the privacy migration as well as this binary declaration; the binary alone does not carry the SDK privacy resource.

Download the sibling .swiftpm-checksum asset or read the swiftpm record in marmotkit-macos-<identifier>.checksums.txt, then declare:

.binaryTarget(
    name: "MarmotKitFFI",
    url: "<exact URL above>",
    checksum: "<contents of .swiftpm-checksum>"
)

The consuming Swift package must declare macOS 15.0 or newer, and the target that wraps the binary links Security and SystemConfiguration.

Generated Swift is shared with iOS

There is no MarmotKit-macos-<identifier>.swift asset, and looking for one is the common mistake. The generated Swift binding is platform-independent and published exactly once per release, by the iOS job, as MarmotKit-<identifier>.swift. Use that same file for a macOS consumer, from the same release identifier as the macOS binary. marmotkit-macos-<identifier>.manifest.json records its SHA-256 so a macOS consumer can verify it without consulting the iOS manifest, and publishing fails if the two jobs ever generate different Swift from one source SHA.

For the same reason, marmotkit-macos-<identifier>.checksums.txt carries a sha256 line for MarmotKit-<identifier>.swift even though that file is not a macOS release asset — the line lets a macOS consumer verify the shared Swift from the macOS checksums file alone. A verifier that walks that file expecting every named entry to exist among the macOS assets must skip this one.

For manual verification, compare the ZIP with its .sha256 asset. The separately published marmotkit-macos-<identifier>.manifest.json records the full MDK source SHA, workspace version, Cargo.lock SHA-256, toolchain versions, enabled features, macOS targets and deployment target, effective Rust release profile, and hashes of the binary and shared generated Swift artifacts. rust_release_profile.lto is Cargo's boolean-or-string value (false or "thin"); codegen units remain an integer. Apple builders pass -C embed-bitcode=no and sanitize leftover Mach-O __LLVM / __bitcode sections; that is not a strip change. The complete marmotkit-macos-<identifier>.zip retains the XCFramework, matching Swift source, PrivacyInfo.xcprivacy, and the same manifest for consumers that prefer a single provenance bundle.

Android

Android bundles contain generated Kotlin, the required Android initialization helpers, and JNI libraries for arm64-v8a, armeabi-v7a, x86, and x86_64.

Exact URLs

Formal release marmotkit-v<version>:

https://github.com/marmot-protocol/mdk/releases/download/marmotkit-v<version>/marmotkit-android-<version>.zip
https://github.com/marmot-protocol/mdk/releases/download/marmotkit-v<version>/marmotkit-android-<version>.zip.sha256

Snapshot for a full 40-character commit SHA <sha> reachable from master:

https://github.com/marmot-protocol/mdk/releases/download/marmotkit-snapshot-<sha>/marmotkit-android-snapshot-<sha>.zip
https://github.com/marmot-protocol/mdk/releases/download/marmotkit-snapshot-<sha>/marmotkit-android-snapshot-<sha>.zip.sha256

The archive has a marmotkit-android-<identifier> root containing:

  • kotlin/dev/ipf/marmotkit/marmot_uniffi.kt
  • kotlin/dev/ipf/marmotkit/MarmotAndroid.kt
  • kotlin/io/crates/keyring/Keyring.kt
  • jniLibs/<abi>/libmarmot_uniffi.so for each supported ABI
  • android-elf.json
  • manifest.json

arm64-v8a and x86_64 libraries are linked so every ELF PT_LOAD segment is aligned to at least 16 KB. The linker flags are extra arguments on the final library build, so configured Cargo rustflags remain in effect. armeabi-v7a and x86 stay on the NDK default page size. The four ABIs and the Kotlin API are unchanged. android-elf.json is a schema-1 report of the packaged bytes: each jniLibs/<abi>/libmarmot_uniffi.so entry has the library's lowercase SHA-256, ELF class, machine, and ordered PT_LOAD alignments. Compare those hashes with the files you stage. ZIP alignment of an app bundle does not repair a library whose load segments are still 4 KB.

Verify the archive against its sibling .sha256 before extracting it. Update the generated Kotlin helpers and all JNI ABI libraries together; mixing identifiers can cross an incompatible UniFFI ABI. The manifest records both the exact packaged source SHA and the workflow builder SHA. Its ordered contents contract lists the generated UniFFI Kotlin source and JNI libraries; the two required hand-written initialization helpers remain validated archive payloads but do not change that existing consumer-facing API contract. elf_validation names android-elf.json without adding that report to contents. Exact-head candidate packages from the release-profile workflow include the same report beside manifest.txt and the build provenance. Publishing a new formal or snapshot artifact, and adopting it in an Android app, remains a separate release step.

Nightlies

Each day's nightly publishes the iOS, macOS and Android assets above under a dated pre-release, for example marmotkit-v0.14.0-nightly.20261020 with MarmotKitFFI-0.14.0-nightly.20261020.xcframework.zip and marmotkit-android-0.14.0-nightly.20261020.zip. The identifier works exactly like a formal version: keep the binary, Swift, privacy and Android inputs on one identifier and verify the same checksums. The manifests record the nightly as release_identifier, master's X.Y.Z-dev as the workspace version, and the exact source SHA.

Use nightlies only for testing. Pin a formal marmotkit-v<version> release for anything you ship. Nightlies are deleted after 30 days, so a nightly pin stops resolving, and going back to an older nightly is not supported. To find the newest nightly, read latest.json on the nightly-meta branch:

https://raw.githubusercontent.com/marmot-protocol/mdk/nightly-meta/latest.json

It lists every asset's URL and SHA-256 for MarmotKit, Marmot C and WN Agent. See nightly builds for naming, publication and retention.

Publishing

Pushing a formal marmotkit-v* tag publishes iOS, macOS, and Android bindings. To publish an untagged snapshot, run the MarmotKit Bindings workflow with a full SHA on master. Its immutable release tag is derived from that SHA. Snapshots publish the iOS, macOS, and Android bindings from the same source SHA.

Set the dispatch input build_only=true to build and validate workflow artifacts without publishing. This also permits testing the workflow on a development branch. Publishing retains the master workflow/source-ancestry restrictions. See parallel builds and rehearsals for phase boundaries, concurrency limits and evidence scope.

Publishing first uploads and verifies every asset on a draft, then publishes it under repository-enforced immutable releases. A retry discards only an incomplete draft. Publishing fails if a public release already exists, and snapshot publishing also fails if its derived tag already exists. Assets and snapshot tags are never replaced or moved; a changed build requires a new formal version or a new source SHA.

Each platform manifest records both the packaged source SHA and the workflow builder SHA. Snapshot dispatches must use the workflow from master, so an older reachable source commit cannot substitute its own packaging logic. The builder SHA also owns the canonical Rust release profile and compiled-in public endpoint defaults. Source-coupled inputs—including the Cargo workspace, UniFFI configuration, and Kotlin support files—come from the packaged source SHA so the generated API and JNI libraries remain a matched set.

Apple privacy resources

Apple exporters publish raw static libraries and the reviewed SDK manifest as separate matching release inputs. The consuming Swift wrapper owns the privacy resource. See the privacy audit and adoption guide for declarations, archive validation and unresolved release questions.

Next
MarmotKit API
Protocol
Development Kit
Documentation
Apps
Awesome
Releases
Community
GitHub
Donate
Contact
©2025–2026 Internet Privacy Foundation. All rights reserved.
Marmot