• Bundle the installer,

  • Package the tiles binary and the python venvstack artifacts into a single file.

• Run the installer

  • extract the Tiles binary and the Python artifacts to their appropriate directory.

• Run the postinstall scripts.

Tarball was the only way one could install Tiles in the first few versions, but it had few shortcomings.

• Since its a gzip file, we can't codesign, notarize and staple. We have to do the mentioned steps to the binary only instead of the whole gzip.

• Users have to use a curl script to install it, which is fine for developers but not a good UX for non-developers.

• From a UX point-of-view not much customization is possible during the installation.

So we wanted to try another approach for installing Tiles. Macos has native installers in form of .dmg and .pkg. We chose pkg because it allows us to run scripts, has good installer UX with customization ability simple html. The rest of the piece focuses on building a macos pkg installer for Tiles.

TODO: Add a pic of pkg installer

Install file structure

We have a folder with directories as the above image. Then we can instruct while building pkg to use this pkgroot folder as the "root" folder. So during installation, installer will just copy the folders as it is to the destination location (creating if directory doesn't exist).

So every time we bundle the app, we just build the new tiles binary and move it to pkgroot/usr/local/bin and rest of the updated artifacts under pkgroot/usr/locals/share/tiles/

For more info check the script.

Code signing the tiles binary

Code signing makes sure that,

• The installer can't be tampered

• The installer is signed by a developer that Apple trusts.

So for code signing the prerequisites are an Apple Developer account and two certificates namely DEVELOPER ID APPLICATION (for singing binary) and DEVELOPER ID INSTALLER (for signing the pkg installer itself). Remember the final installer pkg has binary (which will be individually signed) and other artificats as a single compressed file.

For more details on mentioned certificates and how to create/export them, this article explain them in depth.

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

This how we sign the tiles binary where $DEVELOPER_ID_APPLICATION is an env variable for the name of the DEVELOPER ID APPLICATION certificate.

Scripts

We can have bash scripts that run before and after the installation. For that we need to add the scripts such as preinstall and postinstall under a directory which then we will point while building the pkg.

See how we do in Tiles here, we do it for cleaning up and running some internal scripts.

Building the tiles package

As of now we have a signed tiles binary and other install artifacts all under the pkgroot directory, now we can build a pkg out of it via

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

Here we use the scripts pkgroot directory as the value for --root and also use our the scripts folder mentioned in above section.

Customizing the installer

When we open the pkg we created in the previous section, we can see it is bare minimum and filled with defaults. We can infact add intro page, conclusion page, logo etc via something called distribution which we express in XML files. In a distribution xml file we can add html files for intro, conclusion and other customizable components which are supported by the distribution standard. Here's how the tiles's distribution xml looks like. The customizable xml components like <welcome/> <conclusion/> etc are called resources which we keep under its own directory and pass it when we build the final pkg with the distribution.

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

So in productbuild we pass the pkg we created before. And thus we get a final installer with all the customization and the installer in it.

Code signing the complete pkg installer

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

This is how we codesign a pkg. Remeber before we signed a binary and the commands for signing a binary and an installer are different.

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

We notarize to make sure that the app is malware safe and this verification is done by Apple. For that we need to upload our installer to Apple, and once its verified by Apple it returns the status as valid or invalid.

Here's how we do this,

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

The tiles-notary-profile is the name of the credential we store in keychain, so that every time we need to pass all the details. Below is the command to store a credential for notarization

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

Stapling the installer

Stapling the installer basically attaches the notarizing proof to the installer itself, it will reduce the roundtrip notarizing check to Apple from the Gatekeeper security feature in macos.

xcrun stapler staple pkg/tiles.pkg

What's next

We do have a fully offline installer where the installer includes a gpt-oss model, so that tiles work fully offline and can be used a portable installer which we can carry in an usb. But in newer Apple Silcion based M devices we need to download rosetta as apple stop shipping it by default. Rosetta is used to convert intel based instructions to Apple silicon.

More regarding this is added in this 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.