Local-first private AI assistant. Powered by on device models and ATProto.
Local-first private AI assistant. Powered by on device models and ATProto.
For sensitive knowledge work, from client strategy to research you cannot put in the cloud: run models locally, sync with P2P encrypted sync, and share via ATProto while your data and identity stay private.
Screenshots
Reviews
(0)
—Be the first to review this product.
Updates
Controlling the Ctrl-CThe REPL UI issue
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.
<picture>
<source srcset="/repl_flow_dark.png" media="(prefers-color-scheme: dark)" />
<img src="/repl_flow.png" alt="Tiles REPL request and response flow" />
</picture>
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.
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.
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:
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:
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.
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.
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.
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).
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.
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.
Jun 8, 2026
Ship it upWe ship Tiles as a tar.gz tarball and as a native macOS .pkg. Either format follows the same broad steps.
- 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.
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:
--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 reads the unsigned package and writes a distributable installer with those customizations baked in.
Code signing the complete installer
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:
tiles-notary-profile is the keychain entry name so we do not pass Apple ID details on every run. Store the profile once with:
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.
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.
Apr 5, 2026
Move Along, PythonWe have been working on Tiles. Tiles is a local-first private AI assistant that runs on-device models with encrypted P2P sync, keeps your data and identity yours, and supports sharing chats with ATProto. To ensure its Python model server starts predictably on any machine, the runtime and dependencies must be deterministic and portable. This post walks through how we achieve that with layered venvstacks.
The Python Problem
Right now, we have a polyglot architecture where the control plane 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.
How venvstacks is used in Tiles
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:
These commands resolve dependencies, create the necessary folders, lock files, and metadata for each layer, build the Python runtime and environments based on the lock files, and produce reproducible tarballs that 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:
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.
Feb 17, 2026
