Build-artifacts

.github/workflows/rust.yml

@@ -16,10 +16,12 @@ jobs:
 
     steps:
     - uses: actions/checkout@v4
-    - uses: dtolnay/rust-toolchain@master
+
+    - name: Install Rust toolchain
+      uses: dtolnay/[email protected]
       with:
-        toolchain: 1.90.0
         components: rustfmt, clippy
+
     - name: Cache cargo
       uses: actions/cache@v4
       with:
@@ -37,3 +39,18 @@ jobs:
 
     - name: Run check
       run: just check
+
+    - name: Install ISO tooling
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y xorriso
+
+    - name: Build installer ISO
+      run: ./scripts/make_iso.sh
+
+    - name: Upload installer ISO artifact
+      uses: actions/upload-artifact@v4
+      with:
+        name: tiles-installer-iso
+        path: dist/*.iso
+        if-no-files-found: error

.gitignore

@@ -1,2 +1,3 @@
 /target
 .tiles_dev
+dist/

Cargo.toml

@@ -3,6 +3,10 @@ name = "tiles"
 version = "0.1.0"
 edition = "2024"
 
+[[bin]]
+name = "Tiles"
+path = "src/main.rs"
+
 [dependencies]
 clap = { version = "4.5.48", features = ["derive"] }
 nom = "8"
@@ -11,3 +15,4 @@ serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"
 anyhow = "1.0"
 tokio = { version = "1" , features = ["macros", "rt-multi-thread"]}
+chrono = "0.4"

README.md

@@ -1,6 +1,40 @@
 # Tilekit
 Modelfile-based SDK that lets developers to lets developers customize local models and agent experiences within [Tiles](https://www.tiles.run/).
 
+## Quick Start
+
+### Installation
+
+Download and run the installer for your platform from the [releases page](https://github.com/tilesprivacy/tilekit/releases).
+
+On macOS, double-click `Tiles.app` from the mounted ISO to start installation.
+
+### Basic Usage
+
+```bash
+# Start a model (runs in background)
+Tiles run memgpt
+
+# List running models
+Tiles ls
+
+# Stop a model
+Tiles stop memgpt
+
+# View help
+Tiles --help
+```
+
+### Recommended Setup
+
+**For the best experience with Tiles, we recommend:**
+
+- **[Tailscale](https://tailscale.com)** - Access your Tiles instance securely from anywhere, on any device
+- **[Amphetamine](https://amphetamine.en.softonic.com/mac)** (macOS) - Keep your Mac awake when running models
+- **[rsync](https://rsync.samba.org/)** - Sync your memory and data across devices
+
+These tools ensure your models stay accessible, responsive, and synced 24/7.
+
 ## Dev setup
 
 - Clone the repo
@@ -15,6 +49,94 @@ Modelfile-based SDK that lets developers to lets developers customize local mode
 - Go to root and run `just serve` in another terminal to run the server
 - Run the rust cli using cargo as usual
 
+### Directory Structure
+
+Tiles uses a single `~/.tiles/` directory for all data, making it portable and environment-agnostic:
+
+```
+~/.tiles/
+├── registry/           # Model definitions
+│   ├── memgpt/
+│   │   └── Modelfile
+│   └── other-model/
+│       └── Modelfile
+├── memory/            # AI memory storage
+├── server/            # Python server (production only)
+├── server.pid         # Server process ID
+└── models.json        # Running models state
+```
+
+Models are organized in the `registry/` folder. Each model has its own folder with a `Modelfile` inside.
+
+To run a model:
+```bash
+cargo run run memgpt  # Runs the model defined in ~/.tiles/registry/memgpt/Modelfile
+```
+
+The folder name becomes the model name that you use with the CLI.
+
+### Running Models
+
+Models run in the background and persist after the CLI exits:
+
+```bash
+# Start a model (runs in background)
+cargo run run memgpt         # Dev
+Tiles run memgpt            # Production
+
+# List running models
+cargo run ls                 # Dev
+Tiles ls                    # Production
+
+# Stop a specific model
+cargo run stop memgpt        # Dev
+Tiles stop memgpt           # Production
+```
+
+**How it works:**
+1. When you start a model with `Tiles run`, it loads into the server and runs in the background
+2. The CLI exits immediately - your model keeps running
+3. On macOS (production), Tiles Agent keeps a dock icon visible while models are active
+4. Use `Tiles ls` anytime to see what's running
+5. When you stop the last model, the server and agent shut down automatically
+
+**Production Features (macOS):**
+- Tiles Agent.app appears in dock while models are running
+- Models persist even if you close Terminal
+- Access via `Tiles` command from anywhere
+
+When you stop the last running model, the server automatically stops as well.
+
+### Server Management
+
+**The server starts automatically** when you run a model and stops when no models are running.
+
+**Manual server control (if needed):**
+```bash
+# Start server manually
+cargo run start              # Dev
+tiles start                 # Production
+
+# Stop server manually (only if no models running)
+cargo run stop --server      # Dev
+tiles stop --server         # Production
+```
+
+**Both development and production builds:**
+- Use the same `~/.tiles/` directory structure (environment-agnostic)
+- Server starts automatically on first model run
+- Models run in background and persist after CLI exits
+- Use `Tiles ls` to see running models
+- Use `Tiles stop <model>` to stop individual models
+- Server auto-starts and auto-stops based on running models
+
+**Note:** Development builds use the local `server/` directory for the Python server, while production installs it to `~/.tiles/server/`.
+
+### Packaging installers
+
+- `just bundle` creates a tarball that includes the CLI binary and Python server.
+- `just iso` wraps the bundle and installer script into an ISO that can be flashed with tools like Balena Etcher.
+
 ## License
 
 This project is dual-licensed under MIT and Apache 2.0 terms: