In Tiles, all chat sessions are completely local and stored encrypted on your device. So when we want to share those local conversations with the outside world, we should preserve the same ethos.

There are two ways to share sessions in Tiles. The first is to sync chats end to end encrypted, peer to peer, across your own devices, as described here. That approach provides the strongest privacy and the most granular control, and deserves its own blog post.

But what if you simply want to share your research, ideas, or musings as a regular web link that anyone can open, even if they don't have Tiles installed, similar to ChatGPT's Shared Links, while still preserving data ownership? And what if other applications could build on those publicly shared conversations for entirely new use cases?

This is where AT Protocol comes into the picture.

Reaching for the Atmosphere

AT Protocol, also abbreviated as ATproto, is a decentralized social networking protocol that lets users publish and distribute self-authenticated data. That one-line description doesn't do it justice, so we highly recommend Dan Abramov's excellent explanation of it here.

For our use case of sharing chat sessions, ATproto provides two important guarantees: a permanent identity and the ability to move your data anywhere without breaking existing shared links. Even if Tiles were to stop existing, your shared sessions would remain accessible, and anyone could build another application to display them. The data, its format, and the protocol are all open, much like Markdown.

Tiles doesn't own your shared sessions. They live in your PDS (Personal Data Server in the ATproto ecosystem), and you're free to move to another PDS whenever you want. When you share a session from Tiles using ATproto, the data is published to your PDS, not stored on Tiles' infrastructure. You can host your own PDS or choose one operated by someone you trust.

This separation of applications from identity and data is one of ATproto's core ideas. If you stop using one microblogging app and switch to another that also speaks ATproto, you don't lose your identity, your followers, or your posts. Your identity, social graph, and data move with you across applications, forming what the ATproto community calls the Atmosphere.

Sharing sessions with Tiles

To share a session from Tiles, you first need an ATproto account. The easiest way to get started is by creating a Bluesky account. Every ATproto account is associated with a PDS (Personal Data Server), which is where your data is hosted.

For example, you can create a Bluesky account and use Bluesky's PDS. There are, of course, other PDS providers as well, such as Northsky and Eurosky. The important point is that you can move your account to a different PDS later if you choose. For example, you can migrate from Bluesky's PDS to Northsky's without changing your ATproto handle or your underlying identity, both of which remain the same.

Once you have an ATproto account, you can sign in to it from Tiles using your ATproto handle, as described here. After that, you can open the Tiles CLI (with a web UI coming soon) and share either the current conversation or any existing session using the /share command.

Tiles publishes the session to your ATproto PDS and returns a public link that anyone can access. For more details, see the documentation.

What about private sessions?

Sometimes we want to share a session only with specific people rather than making it public to everyone. One limitation of ATproto today is that records stored in a PDS are public by design, enabling data portability, transparency, and interoperability. There is ongoing work to support permissioned data, but that is not available yet.

To preserve the privacy of sensitive Tiles sessions, Tiles supports private sharing by encrypting the session locally before it is uploaded to the PDS. The encrypted data is stored in your PDS, while the encryption key is placed in the URL fragment (#...). Since URL fragments are never sent to the server, decryption happens entirely in the recipient's browser. This means your PDS stores only encrypted data, and only someone with the complete link can decrypt and view the session.

Here's an example of a private shared session. If you inspect the URL, you'll notice that the encoded encryption key (TmqE5ZwyWaCl/6wCI5R0AsCWwlg2GZ5D.vyLaXFpy6dnB6G9jbHr8aOIxg5hBNeA+KB0v0DQrUkE=) is included as a URL fragment after the #. You can also verify that the corresponding data stored in the PDS is encrypted by inspecting it here.

Because the encryption key never becomes part of the data stored in the PDS, the session remains encrypted while publicly hosted. Only someone with the complete URL can decrypt and view it, since decryption happens entirely in the browser. Under the hood, Tiles uses ChaCha20-Poly1305 for authenticated encryption.

Interoperable sessions

We mentioned earlier that sessions shared through Tiles can outlive Tiles itself. One reason is that the underlying data lives in a user-controlled PDS. But that alone isn't enough. If the data is stored in a proprietary format that requires reverse engineering to use outside of Tiles, then the only thing you've gained is the ability to export a data dump. Credible exit requires more than that.

As mentioned earlier, ATproto already makes it possible to move from one social application to another without losing your identity, social graph, or data. The same principle should apply to AI conversations.

It's similar to how a Markdown file can be edited in Notepad and then opened in VS Code without any conversion. It would be even more powerful if we had that level of interoperability for everything, from social posts to LLM chat sessions.

In fact, this already exists for posts on ATproto. I can create a post in Mu, then open and edit that same post in Bluesky while using the same ATproto account, the same identity, and the same underlying data storage. If I ever decide I no longer like Bluesky's interface, or simply prefer another client, I can switch to Mu without worrying about losing my followers or my content.

It would be exciting to bring that same interoperability to LLM chat sessions. Imagine publishing a local conversation from Tiles and opening it in a different chat viewer. Or imagine publishing a conversation created in ChatGPT, importing it into Tiles, continuing the conversation locally, publishing the updated session, and then opening it again in another compatible application. Just like a text file, the conversation would no longer be tied to a single app.

ATproto enables this kind of interoperability through Lexicons. A Lexicon is essentially a JSON schema, with a few ATproto-specific extensions, that defines the structure of a particular type of data so it can be understood consistently across the network.

As a first step toward interoperable AI conversations, Tiles defines a Lexicon for LLM chat sessions called run.tiles.chat.sessionSnapshot.

{
  "id": "run.tiles.chat.sessionSnapshot",
  "$type": "com.atproto.lexicon.schema",
  "lexicon": 1,
  "defs": {
    "main": {
      "key": "tid",
      "type": "record",
      "record": {
        "required": ["name", "sessionId", "createdAt", "turns"],
        "properties": {
          "name": { "type": "string" },
          "sessionId": { "type": "string" },
          "createdAt": { "type": "string", "format": "datetime" },
          "turns": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "model": { "type": "string" },
                "messages": {
                  "type": "array",
                  "items": { "ref": "#message" }
                }
              }
            }
          }
        }
      }
    },
    "message": {
      "type": "object",
      "required": ["role", "content"]
    },
    "contentItem": {
      "type": "object",
      "required": ["type"]
    }
  }
}

All sessions published through Tiles use this Lexicon. In that sense, the Tiles session viewer acts as a free viewer for any session published in this format. You don't even need Tiles to create the data. Any application can publish a session directly to a user's PDS using the ATproto APIs, and the Tiles viewer can render it.

This opens up some interesting possibilities. Under the hood, Tiles uses Pi as its agent harness, and Pi is also used by several other assistants, including OpenClaw. Imagine if there were a standard Lexicon for Pi sessions. The level of interoperability would be remarkable. Conversations could move seamlessly between applications built on the same underlying session format.

For example, if you tagged a friend in a Tiles chat session, that mention wouldn't be lost when the conversation was opened in another ATproto-compatible AI assistant application. The conversation, its metadata, and its social context could all travel together.

We'll continue experimenting with ATproto as we build more features in Tiles. ATproto aligns closely with the principles we care about: collaboration, credible exit, and user agency. We believe conversations should be portable, interoperable, and ultimately owned by the people who create them.

That's the future we're building toward, so you can truly own your sessions.

As AI becomes central to how we work and communicate, I believe we are seeing a new form of technological feudalism, where a handful of platforms control the models, identities, data, and distribution channels people depend on. Local-first AI offers an alternative, but many tools still lack the identity, sync, and collaboration features people expect.

Thank you, Adam, for the introduction, and thank you to the Local-First Conference team for organizing this event.

Hi everyone, I’m Ankesh. Usually I go by feynon on the internet.

I was here in the audience last year, and it genuinely changed the direction of my work, so it’s an honor to be back as a speaker.

Today, I want to talk about reclaiming control of our digital lives in the age of AI.

I think that starts by running AI locally, on our own devices.

And it continues by building on open protocols instead of closed platforms.

Together, those two ideas let us own our data, our identity, and how our AI works.

I love ChatGPT, and I’ve been using its products since they launched.

What keeps me coming back isn't just the models. It's the consistency of the user experience and the continuity that memory provides across its product surfaces.

It feels less like using a chatbot and more like using an app that knows me.

It started feeling more like a relationship.

And that made me ask a different question: what kind of relationship do I actually have with these systems?

That's when I realized the relationship had become one-sided.

The more ChatGPT learned about me, the more power it held over my digital life.

If I stop paying the rent, part of my digital memory disappears with it.

And because I don’t fully trust who can access what I share, I can’t always express myself freely.

I love using AI.

I just don't love depending on something I don't own or control.

I needed healthier boundaries.

I want to keep the same convenience without depending on blind trust.

I want my identity and memory to stay with me across every app I use, with trust that I can verify computationally.

I still want the relationship. I just want it to be on my terms.

That naturally led me to one question.

Can we actually build AI like this today?

I think we finally can, with the technology we have available today.

Three things have changed.

First, the frontier AI is no longer locked behind proprietary APIs.

For many practical workloads, frontier-level capabilities are already available in open-weight models such as GLM 5.2, as shown in this chart by Artificial Analysis.

The second change is the amount of compute we now have in consumer devices.

Technologies like UltraFusion combine two Apple Silicon Max chips into a single Ultra chip, enabling medium-class local models to run on device.

It’s not just about running frontier models on expensive on-device setups.

As frontier open-weight models improve, techniques like distillation rapidly transfer those gains to smaller local models.

Small models are delivering significantly more intelligence per watt.

We’re also finding smarter ways to run larger models at the edge.

Apple’s upcoming Siri in iOS 27 is powered by Foundation Model 3, a distilled version of Gemini, and runs a 20B Mixture-of-Experts model directly on the iPhone.

It loads expert weights from fast flash storage instead of keeping the entire model in memory, and by loading them once per prompt rather than once per token, it largely compensates for the higher latency of flash storage.

The third change is the growing adoption of open protocols like ATproto and ActivityPub among others.

Bluesky, built on ATproto, has grown to over 45 million users, with a thriving developer ecosystem building user-owned applications.

We now have the models.

We now have the compute.

And we now have the protocols.

The technology is finally here.

But products haven’t caught up yet.

Today’s local AI tools are technically excellent.

They’re built around private, personal use, and local AI is naturally great for that.

But privacy doesn’t mean I don’t want to collaborate.

I still want to share, work together, and move between my own devices, just on my own terms.

Most local AI products simply don’t support that.

And when they do, they still depend on platforms.

Collaboration features usually require a centralized login, like “Sign in with Google.”

So instead of owning my identity, I’m still relying on someone else’s platform.

I just traded one platform dependency for another, even with supposedly private local AI tools.

So I started thinking about what my dream local AI tool would look like.

Everything on this slide comes down to one idea.

I wanted all the polish of modern AI products, but working for me instead of the platform.

And that means polished on-device models, peer-to-peer sync, user-owned identity, shared links, and developer tools that make local AI feel just as seamless as the cloud.

And it's not just my dream, it's a shared one.

This post, shared earlier today by Eileen, describes a similar vision of an open, local setup.

That led me to build Tiles, a local-first private AI assistant.

Today it’s in alpha with a CLI-only experience.

Tiles is built to make ownership the default, without compromising on convenience.

The architecture follows one simple principle.

Keep ownership on the device. Use the network only where it adds value.

The app, models, and your data live on your local devices.

The cloud is only used for collaboration. The ATproto PDS powers social features, while end-to-end encrypted peer-to-peer sync is done with Iroh relays.

The technical architecture is split across three layers: Rust handles the core systems, Python powers inference, and TypeScript runs the agent runtime, which embeds Pi as a Bun binary. If you’d like to explore any particular module, I’d be happy to discuss it in more detail after the talk.

Next, here’s what that looks like across Tiles’ various features.

Tiles includes gpt-oss-20b by default. It uses the Modelfile format, a plain-text blueprint for building and customizing local AI models.

Plugins let users extend Tiles with reusable workflows by installing SKILL.md files.

Tiles securely connects to local models running on remote machines over a peer-to-peer network, giving you access to your ambient AI compute wherever you are.

That same peer-to-peer foundation enables encrypted chat synchronization across linked devices, using locally generated DIDs and UCANs for zero-trust identity and authorization.

Finally, chat sessions can be shared through public or private links and published as ATproto Lexicon records.

Now, with that overview, let’s move on to a demo I recorded yesterday after being delighted by Tristan’s demo of Caldir CLI.

This recorded demo shows Caldir running as a Tiles plugin with remote inference.

I’ll ask it to find events, then create an event. Finally, I’ll share the chat and show the saved ATProto PDS record as a Tiles lexicon.

What impressed me is that this speed was possible locally because of caldir’s simple, plaintext-first design, combined with the vertical integration we’ve built into Tiles across the inference stack.

The three of us have been working full-time on maintaining Tiles for the past six months.

I’m grateful for the guidance of Boris Mann, Dietrich Ayala, and Gordon Brander on this project.

Tiles is really a product of the local-first community, and many of the technologies we use in Tiles came directly from the work of people in this room.

User & Agents has been an incredible community partner where many of these ideas took shape.

Darkshapes, our design partner, designed the Tiles logo and helped turn our ideas into the visual identity of Tiles.

Special thanks to Dietrich and Luke, my co-founders at User & Agents.

Thank you to Boris, Xi Zhang, Hugo, and everyone who sponsored Tiles, shared advice, or helped along the way. I genuinely wouldn’t be standing here today without you.

If you’re interested in sponsoring Tiles, providing funding, or exploring collaboration opportunities, please come talk to me afterwards.

To recap: I love ChatGPT, but I don’t want to compromise on convenience or control. Local AI and open protocols let us keep the convenience while making our data, identity, and memory portable—and truly ours.

I’d love for you to try Tiles on Mac or Linux and tell me what you think.

If you’d like to contribute or chat about local-first AI, please come find me afterwards.

Thank you.

As a local AI assistant, Tiles embeds Pi agent for agent harness. Since the REPL is written in Rust and Pi is in TypeScript, we embed the Pi Bun binary and use it via Pi's RPC mode, spawn a headless Pi binary as a child process, and communicate with it via standard streams (stdin/stdout/stderr) in JSON format. The user input to the model and the streamed output from the model come and go through Pi. It sits between the REPL and the inference system.

As with any LLM inference interface, Tiles REPL must stop the output streaming from the model as soon as the user presses Ctrl-C and the REPL should return to prompt state, ideally like this.

But in the versions before v0.4.11, although the streaming ends and REPL returns to prompt state, on the next user input we were greeted with a broken pipe error like Err value: Os { code: 32, kind: BrokenPipe, message: "Broken pipe" }. Because of this, users had to restart the REPL to continue. More details are in this issue.

The broken pipes

As mentioned, we spawn the Pi process as a child process and communicate through its stdin and stdout. For this reason the streams are connected via pipes rather than the child inheriting the parent's streams (which is the default behavior). If the child inherited the parent's streams, communication would be messy and processes would have to filter what they need from the shared stream, which would introduce race conditions.

When piped, the parent can write to the child's stdin; the child writes to its own stdout, which the parent can then read, giving a clear separation of concerns. This is how we explicitly set the streams to be piped in Rust.

let pi_process =
    Command::new(pi_exec_path)
        .arg("--mode")
        .arg("rpc")
        // default is Stdio::inherit
        .stdin(Stdio::piped())
        .stdout(Stdio::piped())
        .spawn()
        .expect("failed to run Pi");

So when we press Ctrl-C, the SIGINT (signal interrupt) event is propagated to the child processes, and if they don't handle it then the default behavior is to exit. To monitor this, we can use the following commands on Unix systems.

ps -o pid,ppid,pgid,sid,command | grep tiles

88068 65985 88608 target/debug/tiles

Here the processId is 7011, the parent's processId is 65985 (system root is parent), and the process's groupId is 7011. To inspect the children, we can use:

// where 88068 is pid for tiles

pstree -p 88068

\-+= 88068 tiles target/debug/tiles
  |--= 88098 tiles target/debug/tiles daemon
  \--= 88099 tiles /Users/tiles/tiles/.tiles_dev/tiles/pi/pi --mode rpc

We can see the Pi process is running as a child of Tiles with PID 88099.

We can use lsof to further monitor their relationship as follows:

➜ lsof -p 88099 // Pi's PID (child)
COMMAND   PID  USER   FD     TYPE             DEVICE   SIZE/OFF   NODE NAME
pi      88099 tiles    0     PIPE 0xd5c96c81e3aec5c2      16384   ->0xa95f7f46dfb5efe6
pi      88099 tiles    1     PIPE 0x745d3d0e7a7709aa      16384   ->0x27aceab27161a82

➜ lsof -p 88429 // Tile's PID (parent)
COMMAND   PID  USER   FD     TYPE             DEVICE   SIZE/OFF   NODE NAME
tiles   88068 tiles   16     PIPE 0xa95f7f46dfb5efe6      16384   ->0xd5c96c81e3aec5c2
tiles   88068 tiles   17     PIPE  0x27aceab27161a82      16384   ->0x745d3d0e7a7709aa

Here we can see Pi's stdin (FD=0) is connected to Tiles stdout (FD=16) and vice versa.

So when we press Ctrl-C to stop a streaming response, the signal propagates to the Pi process and Pi exits. When we try a new user prompt next time in the REPL, unbeknownst to the REPL that such a process does not exist, it still tries to write to Pi's non-existent stdin, which gives us a broken pipe, aka a broken connection.

Letting them go

Since by default a child process is in the same process group (pgid) as the parent, the SIGINT event is propagated to all the processes in the group. One way is to remove the child from the same group as the parent. This means they still have a parent-child relationship, but the parent is no longer in direct control of the children. On Unix we can use setsid for this to create a new session and set the current process as the leader of it.

But to do that in Rust is an unsafe operation (where we lose safety assurance from the compiler), as setsid is only available in the nightly version as of now, so we need to call it via C FFI. So setsid is achieved via other libraries such as libc, nix, etc., of course colored by the unsafe keyword.

let pi_process = unsafe {
    Command::new(pi_exec_path)
        .arg("--mode")
        .arg("rpc")
        .stdin(Stdio::piped())
        .stdout(Stdio::piped())
        // runs the below closure before executing the
        // command function, here we run setsid for the
        // spawned process.
        .pre_exec(|| {
            if libc::setsid() == -1 {
                return Err(std::io::Error::last_os_error());
            }
            Ok(())
        })
        .spawn()
        .expect("failed to run Pi")
};

This resolves our broken pipe issue, as the SIGINT is never reaching the Pi process. But now we have another issue on hand: the model streaming is non-stoppable via Ctrl-C, and the REPL is completely unresponsive during the entire time we are streaming the output from Pi's stdout. It's no longer respecting SIGINT.

Controlling the Control-C

Thanks to a serendipitous moment while surfing the rustyline repo, which we use for building a nice UX for our REPL, we found that the version we were using (v17) had a bug which masks the SIGINT event. So we upgraded to the latest version, and now we are receiving SIGINT while the model is streaming, but the SIGINT exits the program altogether instead of stopping the stream and returning to the user prompt.

This is in fact expected, as normally programs should handle SIGINT themselves if they want to do cleanups, graceful shutdowns, etc. So we use the ctrlc library to handle SIGINT, which uses a dedicated thread for handling the event.

let is_running = Arc::new(AtomicBool::new(true));
let is_running_ref = is_running.clone();
ctrlc::set_handler(move || {
    is_running_ref.store(false, std::sync::atomic::Ordering::SeqCst);
})
....
....
while is_running.load(std::sync::atomic::Ordering::SeqCst) {
 // loop breaks when SIGINT is fired and above handler toggles
 // is_running to false
}

But again, for some reason we are back to square one where the REPL is non-responsive to Ctrl-C when it's streaming the output.

Turns out the way we read from Pi's stdout is a synchronous, blocking operation. So we tried converting all the functions related to this to async using the corresponding async functions provided by tokio (an async runtime library for Rust). For example, the core operation here is using a buffered reader to read from Pi's stdout efficiently, so we replace the BufReader from the std library with the async BufReader provided by the Tokio runtime.

Tokio uses co-operative scheduling to switch between its tasks, so when we use an async function, it will yield frequently instead of blocking throughout the process.

Once we refactored the codebase to be async, we started getting SIGINT events in the handler we set using the ctrlc library before, and the program no longer exits either. Now all we have to do is abort the Pi session by sending an abort event to Pi and do the cleanup from our side.

while let Some(line) = reader.next_line().await? {
   if !is_running.load(std::sync::atomic::Ordering::SeqCst) {
      info!("Ctrlc detected, aborting Pi ops");
      let end_payload = json!({
          "type": "abort",
       });
       // sending abort event to Pi
       send_to_pi(pi_stdin, end_payload).await?;
       // toggling is_running back to true, once we handled
       // the ctrl-c
       is_running.store(true, std::sync::atomic::Ordering::SeqCst);
       continue;
}

For more details on the sync-async conversion, see the PR diff.

Unexpected entry of SIGPIPE

The interesting thing now is that when we exit the main REPL program, the Pi process also exits, which shouldn't be the case as both are now in different process groups, right? Could this be related to the pipes getting closed on one end?

Although this is fine for us, as we don't want the Pi process to be a background daemon and go rogue, it's important to understand what's happening under the hood, as we also have a Tiles daemon process (which is a background headless Tiles HTTP server) that is still alive even after the main REPL program closes, as it's supposed to be (this was also spawned in a different process group).

// where 88068 is pid for tiles

pstree -p 88068

\-+= 88068 tiles target/debug/tiles
  |--= 88098 tiles target/debug/tiles daemon
  \--= 88099 tiles /Users/tiles/tiles/.tiles_dev/tiles/pi/pi --mode rpc

PID=88098 is our daemon.

Why the dual behavior for the same action? For that we can live-debug the Pi program using lldb (LLVM debugger) to see what happens when the parent exits. We will attach the Pi process to lldb, add a breakpoint for SIGPIPE, then step through to see if Pi is handling SIGPIPE or not. The actions we take are commented with numbered index.

// (1) Starting lldb for the Pi process
➜ sudo lldb -p 88099

No entry for terminal type "xterm-ghostty";
using dumb terminal settings.
// (2) Attaching Pi PID to the debugger
(lldb) process attach --pid 88099

Process 88099 stopped
Target 0: (pi) stopped.
Executable binary set to "/Users/tiles/tiles/.tiles_dev/tiles/pi/pi".
Architecture set to: arm64-apple-macosx-.
No entry for terminal type "xterm-ghostty";
using dumb terminal settings.

// (3) Adding a breakpoint for SIGPIPE and notify us
(lldb) break set -n write
Breakpoint 1: 19 locations.
(lldb) process handle SIGPIPE --pass false --stop true --notify true
NAME         PASS   STOP   NOTIFY
===========  =====  =====  ======
SIGPIPE      false  true   true

// (4) Resuming the debugger
(lldb) process continue

// At this point we exit the Tiles repl and debugger pauses
// Pi
Process 88099 resuming
Process 88099 stopped
// (5) At this point, Tiles repl already exit, and now we
// remove the SIGPIPE breakpoint
(lldb) process handle SIGPIPE --pass true --stop false --notify true

NAME         PASS   STOP   NOTIFY
===========  =====  =====  ======
SIGPIPE      true   false  true

// (6) and continue the Pi program after removing the breakpoint
(lldb) process continue
// We can see that Pi program exits as soon as it
// receives SIGPIPE
Process 88099 resuming
Process 88099 exited with status = 0 (0x00000000)

As seen in the lldb logs, the program exits as soon as it receives SIGPIPE, so Pi doesn't have a handler for SIGPIPE, which causes it to exit.

Conclusion

Debugging a seemingly trivial terminal UI issue led us into a rabbit hole of standard streams, pipes, Unix processes, and their dynamic behavior on system signals with respect to their parent, and finally to the problems caused by blocking I/O in a UI and how async Rust can fix it.

• 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 OpenAI's gpt-oss 20B 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.

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.