Peer-to-peer sync has two steps. **Link** devices first (consent): one device creates a token, the other accepts it. Then **sync** chats between linked peers. Online and same-local-network offline linking use the same commands; Iroh handles transport, and mDNS can discover peers without internet. ### Link devices (tiles link) tiles link create # Start a link toward a peer and print a token tiles link add # Accept the token on the other device tiles link list-peers # List linked peers by DID and nickname tiles link revoke # Unlink a peer Run tiles link create on one device, using the other device's DID, and share the printed token out of band. On the other device, run tiles link add . Online tokens are **UCAN**s (for example, ucan:eyJ...YzQ); on the same local network without internet, the token is an **eight-character alphanumeric code**. **tiles link revoke **: Unlinks a peer; their future sync requests are ignored. ### Sync chats (tiles sync) After devices are linked, one device listens while the other starts sync toward the listener's DID. tiles sync # Listen for a sync request tiles sync # Start sync with a linked peer Run tiles sync on the receiving device. On the other device, run tiles sync (get the DID from tiles link list-peers). When a sync run finishes, both devices should show a notification.

### Remote inference (tiles remote) Share inference from one of your devices to another over Iroh. This is useful when a remote machine has the model or GPU you want, while your primary machine keeps the interactive Tiles session. # Remote machine tiles server start # Starts the inference server in background tiles remote share # Generates an Iroh ticket # Device using remote inference tiles --remote # Uses remote machine inference **tiles server start** starts the inference server on the remote machine before sharing it. **tiles remote share** starts sharing the remote machine's inference endpoint and prints an Iroh ticket. **tiles --remote ** runs on the device intending to use remote inference, while inference happens on the remote machine. tiles remote status # Check remote inference sharing status tiles remote unshare # Stop sharing remote inference ## System ### App updates (tiles update) Update Tiles to the latest version. tiles update # Check for and install app updates ### Health (tiles health) Check the status of dependencies. tiles health ### Inference server (tiles server) Configure the inference server. tiles server start # Start the inference server tiles server stop # Stop the inference server tiles server daemon true # Keep inference running after the REPL exits tiles server daemon false # Stop inference when the REPL exits (default) **tiles server daemon [FLAG]** configures whether inference runs in the background. FLAG is true or false. When true, closing the REPL does not stop inference. The setting is stored under [inference] daemon in config.toml. ### Daemon (tiles daemon) Configure daemon behavior. tiles daemon start # Start the daemon (auto-starts when you run tiles) tiles daemon start 1729 # Start the daemon on a custom port tiles daemon stop # Stop the daemon ## Slash commands Slash commands give you fast, keyboard-first control over Tiles in interactive chat. Type /? or /help in the prompt to open available commands and quickly run actions like checking session state, resuming prior sessions, and sharing chats without leaving the terminal. Use /bye to exit the chat session. ### Session Commands #### /status Show the current session state. #### /sessions List available sessions in local storage. #### /resume Resume a specific session by ID. ### Sharing Commands These commands require an active ATproto login. See ATproto (tiles at) (#atproto-tiles-at). #### /share (via ATproto) Create a shareable link for the current session. #### /share (via ATproto) Create a shareable link for a specific session. Example shared session link: chat.tiles.run/YXQ6Ly9k...ZTJr (https://chat.tiles.run/YXQ6Ly9kaWQ6cGxjOnZreGY2aTY1a2VoZmY2a2p3cjNjaDJ2eC9ydW4udGlsZXMuc2Vzc2lvbi8zbW9vYmNjeXNnZTJr). ### Using Skills Agent Plugins can include skills under skills/. Tiles can also use available skills automatically during a conversation when appropriate. #### /skills List available skills from installed plugins. #### @ Run a skill directly with @ followed by your request (for example, @my-skill Deploy the site). ## Uninstall Tiles Use tiles uninstall to uninstall Tiles from the system. tiles uninstall By default, it keeps the user data folder, downloaded models, and config.toml, so chats, memory, databases, logs, local settings, and model files remain for a later reinstall. For a complete cleanup, pass --all: tiles uninstall --all ================================================================================ ## Book: Models (https://www.tiles.run/book/models) # Models Tiles is designed for everyday productivity tasks. It combines a carefully tested model, inference parameters, and agent harness, so users do not have to manage model selection, tuning, or scaffolding themselves. Tiles uses Google’s Gemma logo

gemma4-12b (https://ai.google.dev/gemma/docs) as the default model for everyday tasks. We use Unsloth’s Dynamic 2.0 GGUF (https://huggingface.co/unsloth/gemma-4-12b-it-GGUF) release of Gemma 4 12B and enable first-party Multi-Token Prediction (MTP) (https://unsloth.ai/docs/models/mtp) speculative decoding out of the box, reducing decoding latency while preserving the target model’s output quality. Tiles uses llama.cpp (https://github.com/ggml-org/llama.cpp) for local inference across supported platforms, with a common inference stack built around GGUF models. Tiles targets everyday personal machines with at least 16 GB of system memory for real productivity tasks. ================================================================================ ## Book: Open source (https://www.tiles.run/book/opensource) # Open source Tiles is fully open source and built on open-source software. In some cases, we maintain forks to ship features the way we want or fix blocking bugs. We intend to upstream these changes whenever possible. ## Forks we maintain | Fork | Upstream | Description | Link | | --- | --- | --- | --- | | tilesprivacy/tiles-pi | earendil-works/pi (https://github.com/earendil-works/pi) | Pi fork for Tiles. | tiles-pi (https://github.com/tilesprivacy/tiles-pi) | | tilesprivacy/dialog-db | dialog-db/dialog-db (https://github.com/dialog-db/dialog-db) | Embeddable database for local-first software. | dialog-db (https://github.com/tilesprivacy/dialog-db) | ## Upstream dependencies Tiles utilizes the following open-source software. We are thankful to the developers and maintainers of these libraries! | Library/Resource | Description | License | Link | | --- | --- | --- | --- | | ggml-org/llama.cpp | Inference engine for running large language models locally on Linux. | MIT | llama.cpp (https://github.com/ggml-org/llama.cpp) | | earendil-works/pi | AI agent toolkit with a unified LLM API, agent loop, TUI, and coding-agent CLI. | MIT | pi (https://github.com/earendil-works/pi) | | n0-computer/iroh | Modular peer-to-peer networking stack in Rust for distributed apps. | Apache-2.0 | iroh (https://github.com/n0-computer/iroh) | | sqlcipher/sqlcipher | Standalone SQLite fork with AES-256 encryption and other database security features. | BSD-3-Clause | SQLCipher (https://github.com/sqlcipher/sqlcipher) | | rusqlite/rusqlite | Ergonomic bindings to SQLite for Rust. | MIT | rusqlite (https://github.com/rusqlite/rusqlite) | | ucan-wg/rs-ucan | Rust implementation of UCAN. | Apache-2.0 | rs-ucan (https://github.com/ucan-wg/rs-ucan) | | huggingface/hf-hub | Rust client for the Hugging Face Hub. | Apache-2.0 | hf-hub (https://github.com/huggingface/hf-hub) | | mozilla-ai/openresponses-python | Python SDK for the OpenResponses specification. | Apache-2.0 | openresponses-python (https://github.com/mozilla-ai/openresponses-python) | | openresponses/openresponses | Open specification for multi-provider, interoperable LLM interfaces. | Apache-2.0 | OpenResponses (https://github.com/openresponses/openresponses) | | unsloth/gemma-4 | Unsloth's builds of Google's Gemma 4 open model family for local inference. | Gemma | gemma-4 (https://huggingface.co/collections/unsloth/gemma-4) | | lmstudio-ai/venvstacks | Virtual environment stacks for Python. | MIT | venvstacks (https://github.com/lmstudio-ai/venvstacks) | This list is still a work in progress and will be updated as we continue to add more features and dependencies to Tiles. ================================================================================ ## Book: Overview (https://www.tiles.run/book/overview) # Overview We make two things: Tiles, our consumer product, a local-first AI assistant; and Tilekit, the SDK for developers to build on the infrastructure behind Tiles. **Status: Alpha** Tiles is currently alpha-quality software. It is usable for everyday tasks, though you may encounter bugs and performance issues. Tilekit, the developer SDK, is experimental, not a current priority, and intended for exploratory use, not production.

## What makes Tiles different Tiles is built around a narrow bet: one well-integrated model at a time, optimized for credible local inference on Apple Silicon while balancing privacy, capability, and everyday usability.

{SHOW_REMOTE_LINK ? ( ) : null}

Capability	Tiles	Ollama	LM Studio	Jan	Osaurus
Decentralized Identity	Supported	- Not supported	- Not supported	- Not supported	Supported
Encryption	Supported	- Not supported	Partially supported	- Not supported	Supported
Sync	Supported	- Not supported	- Not supported	- Not supported	- Not supported
On-device models	Supported	Supported	Supported	Supported	Supported
Cloud models	- Not supported	Supported	Supported	Supported	Supported
In-house models	- Not supported	- Not supported	- Not supported	Supported	Supported
Agent Harness	Supported	Supported	Supported	- Not supported	Supported
Memory	- Not supported	- Not supported	- Not supported	- Not supported	Supported
Plugins	Supported	Supported	Supported	Supported	Supported
Sandbox	- Not supported	- Not supported	- Not supported	- Not supported	Supported
Remote Link	Supported	- Not supported	Supported	- Not supported	Supported
Shared Links	Supported	- Not supported	- Not supported	- Not supported	- Not supported
Developer SDK	Supported	Supported	Supported	- Not supported	Supported
Offline Installer	Supported	- Not supported	- Not supported	- Not supported	- Not supported
Cross platform	Supported	Supported	Supported	Supported	- Not supported
Open source	Supported	Partially supported	Partially supported	Supported	Supported

Supported Partially supported - Not supported

## Appendix ### Technical Architecture

Technical architecture of Tiles.

### Shared Links View this public shared chat example at chat.tiles.run/YXQ6Ly9k...ZTJr (https://chat.tiles.run/YXQ6Ly9kaWQ6cGxjOnZreGY2aTY1a2VoZmY2a2p3cjNjaDJ2eC9ydW4udGlsZXMuc2Vzc2lvbi8zbW9vYmNjeXNnZTJr), or this private shared chat example at chat.tiles.run/YXQ6Ly9k...DTBVLJ (https://chat.tiles.run/YXQ6Ly9kaWQ6cGxjOnZreGY2aTY1a2VoZmY2a2p3cjNjaDJ2eC9ydW4udGlsZXMuc2Vzc2lvbi8zbXBvcWd0d3p5ZzJ6#kUU4azu7HkPh7eqq5TQ8/YnAKHsBLIri.9wFnPDTBVLJDrOOkhidewMzYzZS8QAPkeQW7ozlYGVU=). Tiles supports public and private shared chat links. Public links resolve to a chat record on the user's ATproto personal data server (PDS). Private links store an encrypted transcript on the user's PDS; the decryption key is appended to the share URL and is not sent to the server. In both cases, Tiles does not store a copy of the shared conversation on our servers. ## Frequently asked questions

Short answers drawn from our security documentation (/book/security). For full context and limits, read that page.

Tiles is currently alpha-quality software. It is usable for everyday tasks, though you may encounter bugs and performance issues. Tilekit, the developer SDK, is experimental, not a current priority, and intended for exploratory use, not production. Tiles is designed so the default experience runs on-device. The local server binds to localhost, which limits exposed network surface during normal use. Configuration and application data live in standard local directories, and you can change the user data path when needed. No. Application state is persisted locally with encryption at rest. The Rust build uses SQLCipher-enabled SQLite, and database connections use a passkey from secure storage. That raises the bar against casual inspection of copied files, though it does not remove all local risk. Public identity is separated from private keys. Device and account identity use did:key identifiers from Ed25519 keys. Private keys and database passkeys are stored in the operating system's secure credential store, not in plaintext app configuration files. Peer-to-peer linking is user-mediated, not automatic. One device shows a ticket or local code; the other enters it and explicitly accepts or rejects. In release builds, endpoints derive from your stored secret key, and peer identity is checked against the delivered public key. Sync includes defensive controls, including a maximum size cap for downloaded deltas before they are applied. Sync uses Iroh (https://www.iroh.computer/) for device-to-device networking. When a direct path is not practical, Iroh's public relays can help establish the connection; we list that relay use on our sub-processors page. The product does not currently bundle obvious analytics SDKs such as Sentry, PostHog, Segment, Mixpanel, or similar telemetry. There is still local logging: the Python server may log request metadata and bodies to files under the Tiles data directory, so prompt content can appear in local logs unless logging changes. Updates can check GitHub releases and install via the hosted installer script, which depends on release and hosting integrity rather than a stronger built-in end-user verification workflow. Dependencies are pinned and reviewed. The macOS package is code signed, notarized, and stapled. Bundled dependencies are self-contained so normal installation and use do not require live package downloads from the internet. Use the published security policy and private disclosure path. Researchers can use GitHub Security Advisories or email security@tiles.run (mailto:security@tiles.run), with expectations for acknowledgement, triage, and coordinated disclosure. See SECURITY.md (https://github.com/tilesprivacy/tiles/blob/main/SECURITY.md). ================================================================================ ## Book: Research (https://www.tiles.run/book/research) # Research ================================================================================ ## Book: Security (https://www.tiles.run/book/security) # Security Tiles is designed around a local-first model. The goal is simple: keep personal context, identity, and memory under user control by default. Tiles is still in alpha. Some parts of the system are already stable enough to describe clearly, while others are still being hardened. Personal assistant trust model: this guidance assumes one trusted operator boundary per device or gateway. Tiles is not a hostile multi-tenant boundary for adversarial users sharing one agent or gateway. If you need mixed-trust operation, split trust boundaries with separate gateways, credentials, OS users, or hosts. Inference runtime hardening with Stage-2 hypervisor memory isolation and hardware-backed attestation is on our roadmap, enabling multi-tenant use cases out of the box. ## Local-First Architecture The default experience runs on-device. The local server binds to localhost, and app data lives in standard local directories with support for a custom user data path. ## Local Data Protection Tiles encrypts local SQLite databases at rest. The Rust application uses SQLCipher-enabled SQLite, and database connections are opened with a passkey retrieved from secure storage. That does not remove all local risk, but it does raise the bar against casual inspection of copied database files. ## Identity and Secret Storage Device and account identity are based on did:key identifiers derived from Ed25519 keys. Private keys and database passkeys are stored in the operating system credential store rather than in app-managed plaintext configuration. ## Peer Linking and Sync Tiles includes peer-to-peer device linking and chat sync. Linking is user-mediated: one device presents a ticket or local code, and the other side explicitly accepts or rejects it. Sync is limited to linked peers and bounded by a maximum downloaded delta size before processing. ### Iroh Relay and Sync Transport Tiles sync uses Iroh endpoints, gossip topics, and blob tickets. In normal online operation, alpha builds rely on public Iroh relay infrastructure. On local networks, Tiles can fall back to mDNS for nearby discovery. The long-term plan is to move online relay infrastructure under direct Tiles control. ## Memory and Restricted Code Execution Tiles currently includes a memory-agent flow that can execute generated Python against a designated memory path. That path has file-operation restrictions and basic size limits, but it is not a hardened sandbox and should not be described as strong isolation. This part of the system is transitional and not the long-term model for agent execution. ## Logging and Operational Boundaries Tiles does not currently ship obvious built-in product analytics SDKs such as Sentry, PostHog, Segment, or Mixpanel. At the same time, the local Python server writes logs inside the Tiles data directory, and those logs may include request metadata, prompts, and request bodies. ## Updates and Supply Chain Trust Tiles checks GitHub releases for updates and can install updates through a hosted installer script. That is convenient, but it is also a trust boundary. The current updater depends on the integrity of the Tiles release process and installer hosting rather than on a stronger built-in end-user verification flow. Dependencies are pinned and reviewed before they are added. The macOS installer is code signed, notarized, and stapled. Tiles is also packaged with self-contained dependencies so normal installation does not depend on live package downloads. ## Vulnerability Disclosure We publish a security policy and private disclosure path for vulnerabilities. Reports should go through GitHub Security Advisories or security@tiles.run (mailto:security@tiles.run). See SECURITY.md (https://github.com/tilesprivacy/tiles/blob/main/SECURITY.md). ## Current Strengths - Local-first execution model with a localhost-bound application server - Encrypted local databases for persisted account and chat data - OS-backed secret storage for identity keys and database passkeys - Device identity based on cryptographic keys instead of a required centralized account - Explicit user approval during peer linking - Defensive bounds on synced payload size - Published vulnerability disclosure process ## Current Limits - Local server logs may include prompt and request content - Agents are not sandboxed today - The memory execution environment is restricted, but not strongly isolated - Offline pairing codes are still an evolving part of the linking model - The update path is convenient, but remains a privileged remote installation flow - Some transport-level guarantees depend on upstream networking components and are not yet explained in dedicated project documentation ## Summary Tiles already implements several concrete privacy and security controls: local-first operation, encrypted local persistence, OS-backed secret handling, and explicit peer-to-peer linking. At the same time, the project still has meaningful trust boundaries and hardening work ahead. Tiles should not be described as trustless. It should be described as software that keeps more sensitive state local by default and makes key security decisions more visible to the user. ================================================================================ ## Book: Tilekit (https://www.tiles.run/book/tilekit) # Tilekit Tilekit provides REST APIs for integrating Tiles into local clients and custom UIs. The endpoints run in the Tiles daemon under /v1/tilekit/ and cover inference server controls, the Pi agent, sessions, accounts, and ATproto. # REST API [#rest-api] Use the Tiles daemon’s local REST API to integrate sessions, inference, and accounts into your client. Expand an endpoint to see its request fields, curl example, and response details. **Base URL** http://127.0.0.1:1729/v1/tilekit Run the Tiles daemon first. For chat, start the inference server, create a session, then send a prompt with the returned session ID. The endpoints below follow the current daemon source; availability depends on your installed Tiles version. **Responses** JSON success responses use {"status":"success","data":...}. Application errors use {"status":"failed","reason":"..."} with an HTTP error status. Malformed requests may be rejected before reaching a handler. The prompt endpoint returns an SSE stream. ## Server Manage the local inference server. Source (https://github.com/tilesprivacy/tiles/blob/canary/tiles/src/daemon/server.rs).

Start the inference server in the background. **Request body:** None. **Example request** curl -X GET "http://127.0.0.1:1729/v1/tilekit/server/start" **Response** Returns a status message in data.message.

Stop the inference server. **Request body:** None. **Example request** curl -X GET "http://127.0.0.1:1729/v1/tilekit/server/stop" **Response** Returns a status message in data.message.

Check whether the inference server is responding. **Request body:** None. **Example request** curl -X GET "http://127.0.0.1:1729/v1/tilekit/server/ping" **Response** Returns the health-check message in data.message.

## Agent Work directly with the Pi agent. Create a session before sending prompts. Source (https://github.com/tilesprivacy/tiles/blob/canary/tiles/src/daemon/agent.rs).

Start the Pi agent if it is not already running. **Request body:** None. **Example request** curl -X GET "http://127.0.0.1:1729/v1/tilekit/agent/start" **Response** Returns data.message indicating whether the agent started or was already running.

Read the running agent’s current state. **Request body:** None. **Example request** curl -X GET "http://127.0.0.1:1729/v1/tilekit/agent/state" **Response** Returns the Pi agent state in data. An agent must already be running.

Send a message to the running agent. The response streams Server-Sent Events (SSE). **JSON body** | Field | Type | Required | Description | | --- | --- | --- | --- | | message | string | Required | Prompt to send to the agent. | | session_id | string | Optional | Session ID used to record the turn for sharing. | **Example request** curl -N -X POST "http://127.0.0.1:1729/v1/tilekit/agent/prompt" \ -H 'Content-Type: application/json' \ -d '{ "message": "Hello!", "session_id": "YOUR_SESSION_ID" }' **Response** Returns text/event-stream, rather than the JSON success envelope. curl -N displays events without buffering. Omitting session_id runs the turn without recording a session snapshot.

End the current agent session gracefully. **Request body:** None. **Example request** curl -X GET "http://127.0.0.1:1729/v1/tilekit/agent/end_session" **Response** Returns a confirmation in data.message.

Restart the agent using its current configuration. **Request body:** None. **Example request** curl -X GET "http://127.0.0.1:1729/v1/tilekit/agent/reload" **Response** Returns a confirmation in data.message.

## Session Create sessions and work with locally stored chats. Source (https://github.com/tilesprivacy/tiles/blob/canary/tiles/src/daemon/session.rs).

Create a new session, starting the Pi agent if needed. Start the inference server before sending prompts. **Request body:** None. **Example request** curl -X POST "http://127.0.0.1:1729/v1/tilekit/session/new" **Response** Returns the session ID in data.id. Pass this value as session_id when sending a prompt.

List sessions stored in the local chat database. **Request body:** None. **Example request** curl -X GET "http://127.0.0.1:1729/v1/tilekit/session/list" **Response** Returns the stored sessions in data.

Fetch the stored chats for a session. **Path parameter** session_id · string · required. Replace YOUR_SESSION_ID in the example with the session ID. **Request body:** None. **Example request** curl -X GET "http://127.0.0.1:1729/v1/tilekit/session/YOUR_SESSION_ID/chats" **Response** Returns the session chat data in data.

Save a message to the local chat database. The user ID must identify an existing local user. **JSON body** | Field | Type | Required | Description | | --- | --- | --- | --- | | text | string | Required | Message content. | | session_id | string | Required | Session to save the message in. | | role | string | Required | One of system, user, assistant, developer, or toolResult. | | user_id | string | Required | Existing local user ID. | | model_used | string | Required | Model associated with the message. | | parent_chat_id | string | Optional | Parent message ID. | **Example request** curl -X POST "http://127.0.0.1:1729/v1/tilekit/session/chat" \ -H 'Content-Type: application/json' \ -d '{ "text": "Hello!", "session_id": "YOUR_SESSION_ID", "role": "user", "user_id": "YOUR_USER_ID", "model_used": "YOUR_MODEL" }' **Response** Returns the saved chat in data. A user message can create a stored session when that session does not yet exist.

## Account Create and inspect the local Tiles account. Source (https://github.com/tilesprivacy/tiles/blob/canary/tiles/src/daemon/account.rs).

Create a local account for onboarding. **JSON body** | Field | Type | Required | Description | | --- | --- | --- | --- | | nickname | string | Required | Display nickname for the account. | **Example request** curl -X POST "http://127.0.0.1:1729/v1/tilekit/account/create" \ -H 'Content-Type: application/json' \ -d '{ "nickname": "alice" }' **Response** Returns the account result in data.

Read the current local account details. **Request body:** None. **Example request** curl -X GET "http://127.0.0.1:1729/v1/tilekit/account/status" **Response** Returns the local account in data. Returns 404 when no local account exists.

## ATproto Connect an ATproto account and publish session snapshots. Source (https://github.com/tilesprivacy/tiles/blob/canary/tiles/src/daemon/atproto.rs).

Begin ATproto login for the supplied handle. **JSON body** | Field | Type | Required | Description | | --- | --- | --- | --- | | user_handle | string | Required | ATproto account handle. | **Example request** curl -X POST "http://127.0.0.1:1729/v1/tilekit/atproto/login" \ -H 'Content-Type: application/json' \ -d '{ "user_handle": "alice.bsky.social" }' **Response** Returns the login result in data after the login flow completes.

Log out of the connected ATproto account. **Request body:** None. **Example request** curl -X POST "http://127.0.0.1:1729/v1/tilekit/atproto/logout" **Response** Returns the logout result in data.

Read the connected ATproto account. **Request body:** None. **Example request** curl -X GET "http://127.0.0.1:1729/v1/tilekit/atproto/status" **Response** Returns data.handle and data.did. Returns 404 when not logged in.

Publish a stored session to the connected account’s PDS and return a share link. This writes a record each time it is called. **Path parameter** session_id · string · required. Replace YOUR_SESSION_ID in the example with the session ID. **JSON body** | Field | Type | Required | Description | | --- | --- | --- | --- | | is_private | boolean | Optional | Defaults to false. Use true to encrypt the shared session. | **Example request** curl -X POST "http://127.0.0.1:1729/v1/tilekit/atproto/share-session/YOUR_SESSION_ID" \ -H 'Content-Type: application/json' \ -d '{ "is_private": true }' **Response** Returns data.url and data.is_private. Requires an ATproto login and an existing stored session.

## Source and tooling Open docs/apis in **Bruno**, select the Tilekit collection, and use its dev environment. It sets tilekit_base_url to the local base URL above. - Bruno collection and runnable requests (https://github.com/tilesprivacy/tiles/tree/canary/docs/apis/tilekit%20apis) - Daemon route definitions and handlers (https://github.com/tilesprivacy/tiles/tree/canary/tiles/src/daemon) - API design overview (https://github.com/tilesprivacy/tiles/blob/canary/docs/adr/tilekit.md) The daemon route definitions are authoritative. The design overview includes planned endpoints and older names, including /server/load-model, /agent/stop, /session/resume, /session/search, and /account/set-nickname, which are not registered in the current daemon. HTTP endpoints live in the daemon. # Modelfile Reference [#modelfile-reference] A Modelfile is a text-based blueprint for a model’s configuration, parameters, templates, and system prompt. Tiles supports a format inspired by Ollama-style instructions. The separate tilekit Rust crate exports the Modelfile parser, implemented in tilekit/src/modelfile.rs (https://github.com/tilesprivacy/tiles/blob/main/tilekit/src/modelfile.rs) using the nom parser combinator library. It parses a text-based configuration format for defining model configurations, parameters, templates, and system prompts. This page describes **what is parsed**, **what is validated**, and **what is actually used at runtime today**. ## Quick Start Minimal working Modelfile: FROM mlx-community/gpt-oss-20b-MXFP4-Q4 SYSTEM You are a concise assistant. FROM is required. Most other fields are optional. ## Supported Instructions Tiles currently parses these top-level instructions (case-insensitive): - FROM (required, exactly one) - PARAMETER (repeatable) - TEMPLATE (at most one) - SYSTEM (latest value wins) - ADAPTER (at most one) - LICENSE (at most one) - MESSAGE (repeatable) - # comments If FROM is missing, parsing fails. ## FROM FROM is parsed as a string, but runtime behavior is intentionally narrower right now. ### What works today - Hugging Face-style **model repo identifiers**, for example: - mlx-community/gpt-oss-20b-MXFP4-Q4 - mlx-community/Qwen3.5-4B-MLX-4bit ### Important nuance - Any GGUF file hosted on Hugging Face is supported through FROM. - Local file paths are not supported yet. In short: FROM supports Hugging Face model repositories, including any GGUF file hosted on Hugging Face. Local paths are not yet supported. ## SYSTEM SYSTEM sets the system/developer instruction prompt used in chat requests. - If multiple SYSTEM lines exist, the latest one replaces earlier ones. - If omitted, Tiles falls back to the default Modelfile prompt for the selected mode. This is one of the two Modelfile fields that materially affects runtime behavior today (FROM and SYSTEM). ## PARAMETER PARAMETER is parsed and validated against an allowlist. Supported keys: - num_ctx (int) - repeat_last_n (int) - repeat_penalty (float) - temperature (float) - seed (int) - stop (string) - num_predict (int) - top_k (int) - top_p (float) - min_p (float) Notes: - Unknown parameter names fail validation. - Type mismatches fail validation. - Parameters are currently parsed/stored but not fully applied in the runtime request payload yet. ## MESSAGE MESSAGE supports role + content pairs. Accepted roles: - system - user - assistant Notes: - Messages are validated and stored. - Current runtime conversation assembly does not directly consume modelfile.messages yet. ## TEMPLATE, ADAPTER, LICENSE These instructions are parsed and validated with single-value semantics: - TEMPLATE: at most one - ADAPTER: at most one - LICENSE: at most one Current status: - They are represented in the parsed Modelfile structure. - They are not currently wired into the main model execution path. ## Comments Lines beginning with # are accepted and preserved in serialized Modelfile output. ## Current Runtime Behavior In the current implementation, the Modelfile fields that directly influence execution are: 1. FROM (Hugging Face model repository identifier, including repositories containing GGUF files) 2. SYSTEM (prompt override/fallback behavior) Other parsed fields are available at parse/validation level and can be considered forward-compatible surface for future runtime expansion. ## Example FROM mlx-community/gpt-oss-20b-MXFP4-Q4 SYSTEM """ You are Tiles assistant. Keep answers practical and concise. """ PARAMETER temperature 0.2 PARAMETER num_ctx 4096 The example above is valid. Today, FROM and SYSTEM drive behavior directly; parameter validation still applies. ================================================================================ ## Community initiatives archive IndiaFOSS 2026 giveaway: Tiles Privacy and Sol PBC (https://solpbc.org/) ran an IndiaFOSS 2026 giveaway for OSDC members. Ten selected applicants received conference tickets and swag, and five also received a $100 travel grant. Poster: https://www.tiles.run/indiafoss-2026-giveaway.png Archived form: https://www.tiles.run/indiafoss-2026-giveaway Source page: https://www.tiles.run/book/community#community-initiatives ================================================================================ ## Book: Resources (https://www.tiles.run/book/resources) A living index of resources (articles, papers, talks, videos, and tools) that inform and inspire the Tiles team's work. The list can also be viewed on Semble: https://semble.so/profile/tiles.run/collections/3mkplxagc4i2q Total links: 92. Links marked as highlighted are team picks (shown with a sparkle on the page). Category: Motivations - Mitigating Geopolitical Risks with Local-First Software and atproto, Martin Kleppmann (highlighted): https://www.infoq.com/presentations/cloud-computing-technological-sovereignty-multi-cloud/ - This is Cuba's Netflix, Hulu, and Spotify – all without the internet (highlighted): https://www.youtube.com/watch?v=fTTno8D-b2E - Cuba's Underground Gaming Network: https://www.youtube.com/watch?v=lEplzHraw3c - Weathering Software Winter (highlighted): https://www.youtube.com/watch?v=9TJuOwy4aGA&t=968s - The Memory Walled Garden (highlighted): https://asimovaddendum.substack.com/p/the-memory-walled-garden - The Resonant Computing Manifesto (highlighted): https://resonantcomputing.org - Why Tech Needs Personalization (highlighted): https://om.co/2025/10/29/why-tech-needs-personalization/ - File over app (highlighted): https://stephango.com/file-over-app - Local-First Software: Taking Back Control of Our Data | a mini-doc (highlighted): https://www.youtube.com/watch?v=10d8HxS4y_g - On an Atmosphere OS, Scott (highlighted): https://scott.leaflet.pub/3mry5dbjdg22a Category: Links / LLMs - Agent Skills | Chainguard (highlighted): https://www.chainguard.dev/agent-skills - Code Mode: give agents an entire API in 1,000 tokens (highlighted): https://blog.cloudflare.com/code-mode-mcp/ - Comparative Analysis of Retrieval Systems in the Real World: https://arxiv.org/pdf/2405.02048 - The Bitter Lesson of LLM Extensions: https://www.sawyerhood.com/blog/llm-extension - Jan-nano Technical Report (highlighted): https://arxiv.org/abs/2506.22760 - Minions: the rise of small, on-device LMs: https://hazyresearch.stanford.edu/blog/2025-02-24-minions - The Bitter Lesson is coming for Tokenization (highlighted): https://lucalp.dev/bitter-lesson-tokenization-and-blt/ - Transformer²: Self-Adaptive LLMs: https://sakana.ai/transformer-squared/ - Mixture-of-Depths: Dynamically allocating compute in transformer-based language models: https://arxiv.org/abs/2404.02258 - Small Language Models are the Future of Agentic AI, NVIDIA Research (highlighted): https://arxiv.org/abs/2506.02153 - LLM in a flash: Efficient Large Language Model Inference with Limited Memory: https://arxiv.org/abs/2312.11514 - Kinetics: Rethinking Test-Time Scaling Laws: https://openreview.net/attachment?id=qxnJrm47Ag&name=pdf - Enhancing Reasoning Capabilities of Small Language Models with Blueprints and Prompt Template Search: https://openreview.net/attachment?id=LsNstclw8Z&name=pdf - FedVLM: Scalable Personalized Vision-Language Models through Federated Learning: https://arxiv.org/abs/2507.17088 - Model Merging in LLMs, MLLMs, and Beyond: Methods, Theories, Applications and Opportunities (highlighted): https://arxiv.org/abs/2408.07666 - Your LLM Knows the Future: Uncovering Its Multi-Token Prediction Potential: https://arxiv.org/abs/2507.11851 - Cephalo: Multi-Modal Vision-Language Models for Bio-Inspired Materials Analysis and Design: https://arxiv.org/abs/2405.19076 - The GPU-Poor LLM Gladiator Arena: https://huggingface.co/spaces/k-mktr/gpu-poor-llm-arena - The State of Open Models (highlighted): https://youtu.be/FUcilE5Gx_0?si=9aP_NAzTKi8qw78n - The State of On-Device LLMs (highlighted): https://app.getcontrast.io/register/sota-the-state-of-llms - r/LocalLLaMA (highlighted): https://www.reddit.com/r/LocalLLaMA/ - LLMs on a Budget (highlighted): https://benjaminmarie.gumroad.com/l/llms-on-a-budget - An Analogy for Understanding Transformers (highlighted): https://www.lesswrong.com/posts/euam65XjigaCJQkcN/an-analogy-for-understanding-transformers - Neural networks, 3Blue1Brown (highlighted): https://www.youtube.com/playlist?list=PLZHQObOWTQDNU6R1_67000Dx_ZCJB-3pi - Personalized Machine Learning (highlighted): https://cseweb.ucsd.edu/~jmcauley/pml/ Category: Links / Inference - Introducing the unified multi-modal `MLX` engine architecture in LM Studio (highlighted): https://lmstudio.ai/blog/unified-mlx-engine - Pie:Programmable LLM Serving (highlighted): https://pie-project.org/ - Serve Programs, Not Prompts (highlighted): https://ingim.org/papers/gim2025serve.pdf - Pie: A Programmable Serving System for Emerging LLM Applications (highlighted): https://ingim.org/papers/gim2025pie.pdf - Intelligence Per Watt: A Study of Local Intelligence Efficiency (highlighted): https://hazyresearch.stanford.edu/blog/2025-11-11-ipw - NVIDIA eGPU on macOS: RTX 3090 & 5090 Benchmarks | lucebox (highlighted): https://www.lucebox.com/blog/egpu-myth - Equivariance Encryption for Private LLM Inference (highlighted): https://davide221.github.io/articles/equivariance-encryption.html - The Power of Efficiency: Edge AI's Role in Sustainable Generative AI Adoption (highlighted): https://creativestrategies.com/research/gen-ai-edge-testing/ - WhisperKit: On-device Real-time ASR with Billion-Scale Transformers, Argmax: https://openreview.net/attachment?id=6lC3MPFbVg&name=pdf - Towards Feasible Private Distributed LLM Inference, Dria: https://dria.co/research/towards-feasible-private-distributed-llm-inference - InferenceMAX™: Open Source Inference Benchmarking: https://newsletter.semianalysis.com/p/inferencemax-open-source-inference - Reference implementation of the Transformer architecture optimized for Apple Neural Engine: https://github.com/apple/ml-ane-transformers - Understanding AI/LLM Quantisation Through Interactive Visualisations (highlighted): https://smcleod.net/2024/07/understanding-ai/llm-quantisation-through-interactive-visualisations/ - The Kaitchup Index: A Leaderboard for Quantized LLMs (highlighted): https://kaitchup.substack.com/p/the-kaitchup-index - GGUF Quantization Docs (Unofficial): https://github.com/iuliaturc/gguf-docs - Reverse-engineering GGUF | Post-Training Quantization: https://www.youtube.com/watch?v=vW30o4U9BFE - Choosing a GGUF Model: K-Quants, I-Quants, and Legacy Formats: https://kaitchup.substack.com/p/choosing-a-gguf-model-k-quants-i Category: Links / Training - The Continual Learning Problem, Jessy Lin (highlighted): https://jessylin.com/2025/10/20/continual-learning/ - Defining Continual Learning (highlighted): https://x.com/carnot_cyclist/status/2041479655035679163 - Xet is on the Hub (highlighted): https://huggingface.co/blog/xet-on-the-hub - Ellora: Enhancing LLMs with LoRA: https://github.com/codelion/ellora_ - LoRA Without Regret (highlighted): https://thinkingmachines.ai/blog/lora/ - Pretraining with hierarchical memories: separating long-tail and common knowledge, Apple (highlighted): https://www.arxiv.org/abs/2510.02375 - LoRA Learns Less and Forgets Less: https://arxiv.org/abs/2405.09673 - Text-to-LoRA: Hypernetworks that adapt LLMs for specific benchmark tasks using only textual task description as the input, Sakana AI (highlighted): https://arxiv.org/abs/2506.06105 - Introducing FlexOlmo: a new paradigm for language model training and data collaboration, Allen AI: https://allenai.org/blog/flexolmo - Towards Large-scale Training on Apple Silicon, Exo Labs (highlighted): https://openreview.net/pdf?id=TJjP8d5bms - LoFT: Low-Rank Adaptation That Behaves Like Full Fine-Tuning: https://arxiv.org/pdf/2505.21289 - AirLLM: Diffusion Policy-based Adaptive LoRA for Remote Fine-Tuning of LLM over the Air: https://arxiv.org/abs/2507.11515 - How to Scale Your Model: https://jax-ml.github.io/scaling-book/ - RFT, DPO, SFT: Fine-tuning with OpenAI: Ilan Bigio, OpenAI: https://www.youtube.com/watch?v=JfaLQqfXqPA - Hand-picked selection of articles on AI fundamentals/concepts that cover the entire process of building neural nets to training them to evaluating results. (highlighted): https://aman.ai/primers/ai/ Category: Links / Memory - mem-agent: Equipping LLM Agents with Memory Using RL (highlighted): https://dria.co/research/mem-agent:-equipping-llm-agents-with-memory-using-rl - Memory Layers at Scale, Meta FAIR (highlighted): https://arxiv.org/abs/2412.09764 - On the Way to LLM Personalization: Learning to Remember User Conversations, Apple Machine Learning Research: https://machinelearning.apple.com/research/on-the-way - Memory OS of AI Agent: https://arxiv.org/abs/2506.06326 - Titans + MIRAS: Helping AI have long-term memory, Google Research: https://research.google/blog/titans-miras-helping-ai-have-long-term-memory/ - How memory augmentation can improve large language models, IBM Research: https://research.ibm.com/blog/memory-augmented-LLMs - On the Way to LLM Personalization: Learning to Remember User Conversations: https://arxiv.org/abs/2411.13405 - ChatGPT Memory and the Bitter Lesson (highlighted): https://www.shloked.com/writing/chatgpt-memory-bitter-lesson - Anthropic's Opinionated Memory Bet: https://shloked.com/writing/claude-memory-tool - Benchmarking Honcho: https://blog.plasticlabs.ai/research/Benchmarking-Honcho - Git Based Memory Storage for Conversational AI Agent: https://github.com/Growth-Kinetics/DiffMem Category: Links / Security - A Preliminary Report On Edge-Verified Machine Learning (evML) (highlighted): https://github.com/exo-explore/evML/blob/main/A_Preliminary_Report_On_evML.pdf - A Preliminary Report On Edge-Verified Machine Learning, Exo Labs: https://github.com/exo-explore/evML/blob/main/A_Preliminary_Report_On_evML.pdf - Defeating Prompt Injections by Design, Google Deepmind (highlighted): https://arxiv.org/abs/2503.18813 - dstack - Open Source Confidential Computing | Phala (highlighted): https://phala.com/dstack - Intent-Based Architecture and Their Risks (highlighted): https://www.paradigm.xyz/2023/06/intents - Mind the Trust Gap: Fast, Private Local-to-Cloud LLM Chat: https://hazyresearch.stanford.edu/blog/2025-05-12-security - MCP Colors: Systematically deal with prompt injection risk: https://timkellogg.me/blog/2025/11/03/colors - New physical attacks are quickly diluting secure enclave defenses from Nvidia, AMD, and Intel: https://arstechnica.com/security/2025/10/new-physical-attacks-are-quickly-diluting-secure-enclave-defenses-from-nvidia-amd-and-intel/ - User-Agent header, MDN (highlighted): https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/User-Agent Category: Links / Miscellaneous - PortableApps.com: https://en.wikipedia.org/wiki/PortableApps.com - Mosh: the mobile shell: https://mosh.org - Self-driving infrastructure (highlighted): https://vercel.com/blog/self-driving-infrastructure - OpenPoke: Recreating Poke's Architecture (highlighted): https://www.shloked.com/writing/openpoke - What happened to custom ROMs?: https://www.youtube.com/watch?v=HImV4rSps48 ================================================================================ ## Additional URLs - Privacy: https://www.tiles.run/privacy - Terms: https://www.tiles.run/terms - Refund Policy: https://www.tiles.run/refund-policy - Tiles Pro includes a 7-day money-back guarantee on the initial subscription payment. - Research: https://www.tiles.run/book/research - About and sponsorship: https://www.tiles.run/about - Help: https://www.tiles.run/help - Press Kit: https://www.tiles.run/press-kit - Brand: https://www.tiles.run/brand - Releases: https://www.tiles.run/releases - Sub-processors: https://www.tiles.run/sub-processors - RSS: https://www.tiles.run/api/rss ================================================================================