• Assemble the deliverable:

  • Package the Tiles binary and the Python venvstack artifacts into one installer payload.

• Run the installer:

  • Copy the Tiles binary and Python artifacts into the correct locations on disk.

• Run postinstall scripts.

In early releases, the tarball was the only install path. It served us well, but it had clear limits.

• Because the release artifact is a gzip tarball, we cannot codesign, notarize, and staple the archive itself the way we can a full installer. We run those steps on the Tiles binary only, not on the entire .gz file.

• Installation relies on a curl-based script. That is workable for developers and rougher for everyone else.

• The flow leaves little room to tailor copy, branding, or steps in the installer UI.

We wanted a path that fits Apple's signing and notarization story and feels native on macOS. Installers ship as .dmg or .pkg bundles; we chose .pkg because it can run scripts, uses a familiar installer UI, and supports customization with simple HTML. What follows is how we build that .pkg for Tiles.

Install file structure

The layout matches the directory tree above. When we build the package, we point the tooling at this pkgroot directory as the install root. The installer copies that tree onto the destination volume and creates intermediate directories as needed.

For each release, we build a fresh Tiles binary into pkgroot/usr/local/bin and place the remaining updated artifacts under pkgroot/usr/local/share/tiles/.

The build script in the repo has the full sequence.

Code signing the Tiles binary

Code signing gives us:

• A signed Tiles binary that cannot be altered without invalidating the signature.

• A signature from a developer certificate that Apple trusts.

You need an Apple Developer account and two certificate types: DEVELOPER ID APPLICATION for the binary and DEVELOPER ID INSTALLER for the .pkg. The finished installer wraps the signed binary and the other artifacts in one compressed package.

For creating and exporting those certificates, the CodeVamping macOS pkg installer article covers the details.

# Signing the Tiles binary
codesign --force \
  --sign "$DEVELOPER_ID_APPLICATION"\
  --options runtime \
  --timestamp \
  --strict \
  "${CLI_BIN_PATH}/tiles"

The snippet signs the Tiles CLI. $DEVELOPER_ID_APPLICATION is an environment variable that holds the common name of the Developer ID Application certificate.

Scripts

Bash scripts can run before and after the payload is laid down. We keep preinstall and postinstall scripts in a directory and pass that path into pkgbuild.

The Tiles repo has those scripts; they handle cleanup and internal setup.

Building the Tiles package

With the signed Tiles binary and the rest of the install tree under pkgroot, we run:

pkgbuild --root pkgroot --scripts \
 pkg/scripts --identifier com.tilesprivacy.tiles --version "$VERSION" \
 pkg/tiles-unsigned.pkg

--root is pkgroot; --scripts points at the directory from the previous section.

Customizing the installer

Opening the unsigned package from the previous step shows Apple's default, minimal flow. We layer on welcome and conclusion screens, a logo, and other panels with an Apple distribution definition in XML. That file references HTML for the welcome, conclusion, and other supported steps. Our distribution_network.xml is the working example. Elements such as <welcome/> and <conclusion/> point at resources we keep alongside the definition and pass into the final productbuild invocation.

productbuild \
  --distribution pkg/distribution_network.xml \
  --resources pkg/resources \
  --package-path pkg/  \
  pkg/tiles-dist-unsigned.pkg

productbuild reads the unsigned package and writes a distributable installer with those customizations baked in.

Code signing the complete installer

productsign \
  --sign "$DEVELOPER_ID_INSTALLER" \
  pkg/tiles-dist-unsigned.pkg \
  pkg/tiles.pkg

That signs the .pkg itself. The Tiles binary is already signed; signing a macOS binary and signing an installer package are different operations.

The main difference is productsign instead of codesign, and the certificate we use is DEVELOPER ID INSTALLER instead of DEVELOPER ID APPLICATION.

Notarizing the installer

Notarization lets Apple scan the payload for malware. We upload the installer; when processing finishes, the service returns acceptance or rejection.

Submission looks like this:

xcrun notarytool submit pkg/tiles.pkg \
  --keychain-profile "tiles-notary-profile" \
  --wait

tiles-notary-profile is the keychain entry name so we do not pass Apple ID details on every run. Store the profile once with:

xcrun notarytool store-credentials \
  "tiles-notary-profile" \
  --apple-id "john.doe@gmail.com" \
  --team-id "X********4" \
  --password "****-****-****-****"

Stapling the installer

Stapling embeds the notarization ticket in the installer file so Gatekeeper needs fewer round trips to Apple when a user opens the package.

xcrun stapler staple pkg/tiles.pkg

What's next

We also ship a fully offline installer that bundles a gpt-oss model, so Tiles can be installed without an internet connection. We are working toward making Tiles itself portable, allowing users to carry their model and data and run it from a flash drive on any compatible system.

The installer requires Rosetta; on Apple Silicon Macs, it is not included by default and must be installed separately. Rosetta translates Intel binaries to run on Apple Silicon. There is a workaround for this, described in the linked GitHub issue.

We're thrilled to launch Tiles Public Alpha, our first public release of a privacy-first AI assistant. Tiles brings together local-first models, personalized experiences, and verifiable privacy, all running on your device, with your data staying yours. We believe identity and memory are two sides of the same coin, and Tiles makes that coin yours: your user-agent.

Our first alpha is a CLI assistant app for Apple Silicon devices, and a Tilekit SDK that lets developers customize local models and agent experiences within Tiles. We aim to evolve Modelfile in collaboration with the community, establishing it as the standard for model customization.

Philosophy

The project is defined by four interdependent design choices²:

1. Device-anchored identity with keyless ops: Clients are provisioned through the device keychain and cannot access the registry by identity alone³. Keyless operations are only enabled after an identity is verified and linked to the device key, allowing third-party agent access under user-defined policies⁴.
2. Immutable model builds: Every build is version-locked and reproducible, ensuring consistency and reliability across updates and platforms.
3. Content-hashed model layers: Models are stored and referenced by cryptographic hashes of their layers, guaranteeing integrity and enabling efficient deduplication and sharing.
4. Verifiable transparency and attestations: Every signing and build event is logged in an append-only transparency log, producing cryptographic attestations that can be independently verified. This ensures accountability, prevents hidden modifications, and provides an auditable history of model provenance across devices and registries.

Implementation

Tiles bundles a fine-tuned model to manage context and memories locally on-device with hyperlinked markdown files. Currently, we use mem-agent model (from Dria, based on qwen3-4B-thinking-2507), and are in the process of training our initial in-house memory models.

These models utilize a human-readable external memory stored as markdown, and learned policies (trained via reinforcement learning on synthetically generated data) to decide when to call Python functions that retrieve, update, or clarify memory, allowing the assistant to maintain and refine persistent knowledge across sessions.

Looking forward

We're building the next layer of private personalization: customizable memory, private sync, verifiable identity, and a more open model ecosystem.

• Memory extensions: Add support for LoRA-based memory extensions so individuals and organizations can bring their own data and shape the assistant's behavior and tone on top of the base memory model.
• Sync: Build a reliable, peer-to-peer sync layer using Iroh for private, device-to-device state sharing.
• Identity: Ship a portable identity system using AT Protocol DIDs, designed for device-anchored trust.
• MIR in Modelfile: Work with the Darkshapes team to support the MIR (Machine Intelligence Resource) naming scheme in our Modelfile implementation.
• Registry: Continue supporting Hugging Face, while designing a decentralized registry for versioned, composable model layers using the open-source xet-core client tech.
• Research roadmap: As part of our research on private software personalization infrastructure, we are investigating sparse memory finetuning, text diffusion models, Trusted Execution Environments (TEEs), and Per-Layer Embeddings (PLE) with offloading to flash storage.

We are seeking design partners for training workloads that align with our goal of ensuring a verifiable privacy perimeter. If you're interested, please reach out to us at hello@tiles.run.

References

1. Ollama Modelfile is the blueprint to create and share customized models using Ollama.
2. Decentralizability (Gordon Brander): Immutable data, universal IDs, user-controlled keys… and just using HTTP. I think this is probably minimum viable decentralizability.
3. Keybase's New Key Model
4. Sigstore: How It Works

The Python Problem

Right now, we have a polyglot architecture where the control pane and CLI are written in Rust, while local model inference runs through a Python server as a daemon. Ideally, when we ship Tiles, we should also ship the required artifacts needed to run Python on the user’s system.

Since Python servers cannot be compiled into a single standalone binary, the user’s system must have a Python runtime available. More importantly, it must be a deterministic Python runtime so that the server runs exactly on the version developers expect.

In earlier releases of Tiles (before 0.4.0), we packed the server files into the final release tarball. During installation, we extracted them to the user’s system, downloaded uv (a Python package manager), installed Python 3.13 if it was not already present, and then ran the server as a daemon.

This approach had several issues:

• Downloading development-related tools such as uv onto the user’s system
• Relying on uv at install time to manage dependencies and run the server
• Increased chances of failures due to dependency or runtime non-determinism
• Requiring internet access to download all of the above tools
• Lack of a fully deterministic runtime across operating systems

One of the long-term goals of Tiles is complete portability. The previous approach did not align with that vision.

Portable Runtimes

To address these issues, we decided to ship the runtime along with the release tarball. We are now using venvstacks by LM Studio to achieve this.

Venvstacks allows us to build a layered Python environment with three layers:

• Runtimes
  Defines the exact Python runtime version we need.
• Frameworks
  Specifies shared Python frameworks such as NumPy, MLX, and others.
• Applications
  Defines the actual server application and its specific dependencies.

Similar to Docker, each layer depends on the layer beneath it. A change in any layer requires rebuilding that layer and the ones above it.

All components within a layer share the layers beneath them. For example, every framework uses the same Python runtime defined in the runtimes layer. Likewise, if we have multiple servers in the applications layer and both depend on MLX, they will share the exact deterministic MLX dependency defined in frameworks, as well as the same Python runtime defined in runtimes.

We define everything inside a venvstacks.toml file. Here is the venvstacks.toml used in Tiles.

Because we pin dependency versions in the TOML file, we eliminate non-determinism.

Internally, venvstacks uses uv to manage dependencies. Once the TOML file is defined, we run:

venvstacks lock venvstacks.toml

This resolves dependencies and creates the necessary folders, lock files, and metadata for each layer.

Next:

venvstacks build venvstacks.toml

This builds the Python runtime and environments based on the lock files.

Finally:

venvstacks publish venvstacks.toml

This produces reproducible tarballs for each layer. These tarballs can be unpacked on external systems and run directly.

We bundle the venvstack runtime artifacts into the final installer using this bundler script. During installation, this installer script extracts the venvstack tarballs into a deterministic directory.

Our Rust CLI can then predictably start the Python server using:

stack_export_prod/app-server/bin/python -m server.main

What’s Next

We tested version 0.4.0 on clean macOS virtual machines to verify portability, and the approach worked well.

For now, we are focusing only on macOS. When we expand support to other operating systems, we will revisit this setup and adapt it as needed.

Packaging the runtime and dependencies increases the size of the final installer. We are exploring ways to reduce that footprint.

We also observed that changes in lock files can produce redundant application tarballs when running the publish command. More details are tracked in this issue.

Overall, we are satisfied with this approach for now.

Till then, keep on tiling.