mesh-deck 0.1.0__tar.gz

mesh_deck-0.1.0/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to this project are recorded here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow
+[Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+Nothing yet.
+
+## [0.1.0] - 2026-10-26
+
+First public release, published on PyPI as `mesh-deck` (the command is `mesh`).
+
+### Added
+- `mesh gpu`: shows each GPU's memory and utilization and who is holding the memory.
+- Progress and completion messages when stopping services (`Ctrl+C` or `mesh down`).
+- `mesh logs -n all` to print a whole log.
+- `python -m mesh_cli` as an alternative to the `mesh` command.
+- Terminal UI: colour, tables, memory bars and a live start-up line (spinner and time) when output is an
+  interactive terminal. Piped output and `NO_COLOR` keep the plain text. Adds the `rich` dependency.
+- "Did you mean" hints for mistyped commands, service names, config fields and config file names.
+- `mesh completion bash|zsh|fish` prints a Tab-completion script; `mesh logs` completes service names.
+- `mesh up` prints a one-line plan summary when everything fits, and the full plan only when there is something
+  to read or with `--plan`.
+- Type information is shipped with the package (`py.typed`).
+
+### Fixed
+- A second Ctrl+C (or `mesh down`) while `mesh up` was stopping services no longer aborts the cleanup and leaves
+  services running.

mesh_deck-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,101 @@
+# Contributing to mesh-deck
+
+Thanks for helping. This project is small and early, so the most useful contributions are real-world data and
+bug reports. Please read [How it works](docs/how-it-works.md) first, especially "What it does not do", so you
+know what is in scope.
+
+## The most useful thing you can send: output from your GPU
+
+The planner has only been checked on two RTX 4090s. If you have a different GPU, driver or vLLM version,
+real output from it is worth more than code.
+
+1. Run these two commands, ideally with some services running:
+
+   ```bash
+   nvidia-smi --query-gpu=index,uuid,name,memory.total,memory.used,memory.free --format=csv
+   nvidia-smi --query-compute-apps=gpu_uuid,pid,process_name,used_memory --format=csv
+   ```
+
+   If you can, also run `nvidia-smi -q -x` (it lists graphics processes such as the desktop) and keep only the
+   `<gpu>` blocks with their `<uuid>` and `<processes>`.
+2. Replace the `uuid` values with dummy ones (for example `GPU-00000000-0000-0000-0000-000000000000`).
+3. Open a pull request that adds the output to `tests/fixtures/` and a test in `tests/test_gpu.py` or
+   `tests/test_planner.py` that parses it. If the planned memory is wrong for your card, say so in the pull
+   request. That is a bug we want to know about.
+
+## Reporting a bug
+
+Open an issue with:
+
+- `mesh --version`, your OS, GPU model(s), driver version, and the engine you run (for example vLLM and its version).
+- The command you ran and the full output.
+- Your `models.yaml` **with private paths and model names removed**.
+- The two `nvidia-smi` outputs above, from just before the failure if you can.
+
+For a service that fails to start, also include the last lines of its `logs/NAME.log`.
+
+## Development setup
+
+```bash
+git clone https://github.com/mrahmedromman/mesh-deck.git
+cd mesh-deck
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+Before opening a pull request, also run the style and type checks that CI runs:
+
+```bash
+ruff check src tests
+mypy
+```
+
+The tests need no GPU and no model. Runner tests start throwaway `http.server` processes, so they take a few
+seconds.
+
+### Layout
+
+| Path | What it holds |
+|---|---|
+| `src/mesh_cli/config.py` | `models.yaml` loading and validation |
+| `src/mesh_cli/gpu.py` | `nvidia-smi` output parsing |
+| `src/mesh_cli/holders.py` | working out who holds GPU memory (`mesh gpu`) |
+| `src/mesh_cli/planner.py` | the memory simulation |
+| `src/mesh_cli/runner.py` | starting, health-checking, logging and stopping services |
+| `src/mesh_cli/suggest.py` | "did you mean" hints |
+| `src/mesh_cli/completion.py` | bash, zsh and fish completion scripts, generated from the argument parser |
+| `src/mesh_cli/ui.py` | colour, tables, memory bars and the live start-up line (terminal only) |
+| `src/mesh_cli/cli.py` | the `mesh` command |
+| `tests/` | tests, with real `nvidia-smi` output in `tests/fixtures/` |
+| `examples/`, `docs/` | example configs and the documentation |
+
+## Pull requests
+
+- **Keep them small** and about one thing.
+- **Add or update a test** for any behaviour change. A bug fix should come with a test that fails without it.
+- **Run `pytest`, `ruff check src tests` and `mypy`** before opening the pull request.
+- **Add a line to `CHANGELOG.md`** under "Unreleased" for anything a user would notice.
+- **Update the docs** if you change a command, an option or a config field: `README.md` and the pages in `docs/`.
+- **Keep private details out.** Examples and fixtures must not contain your hostnames, home paths, model names
+  or GPU UUIDs. The examples use generic names (`llm`, `stt`, `tts`, `embed`) on purpose.
+- Follow the style of the surrounding code: type hints, short functions, comments only where the reason is not
+  obvious.
+
+## Scope
+
+mesh checks GPU memory, starts services in order and keeps their logs. It deliberately does not proxy requests,
+swap models on demand or replace a process manager. Tools such as llama-swap, LiteLLM and Docker Compose
+already do those well. If you are unsure whether an idea fits, open an issue to ask before writing code.
+
+Ideas that would fit well:
+
+- Support for AMD GPUs (a parser for `rocm-smi`) and other vendors.
+- Recognising Podman and Kubernetes containers in `mesh gpu`.
+- Checking that other engines (not only vLLM) are planned correctly.
+- Exporting a config for another tool, such as llama-swap.
+
+## License
+
+By contributing you agree that your contributions are licensed under the [MIT License](LICENSE).

mesh_deck-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) AhmedRomman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mesh_deck-0.1.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include CONTRIBUTING.md CHANGELOG.md SECURITY.md
+graft examples
+graft docs
+graft tests
+global-exclude __pycache__ *.py[cod] .DS_Store

mesh_deck-0.1.0/PKG-INFO

@@ -0,0 +1,238 @@
+Metadata-Version: 2.4
+Name: mesh-deck
+Version: 0.1.0
+Summary: Plan and start multi-service local AI stacks (vLLM, speech-to-text, embeddings) on shared GPUs without OOM surprises.
+Author: AhmedRomman
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/mrahmedromman/mesh-deck
+Project-URL: Documentation, https://github.com/mrahmedromman/mesh-deck/tree/main/docs
+Project-URL: Changelog, https://github.com/mrahmedromman/mesh-deck/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/mrahmedromman/mesh-deck/issues
+Project-URL: Source, https://github.com/mrahmedromman/mesh-deck
+Keywords: mesh-deck,vllm,gpu,llm,nvidia,cli,self-hosted,inference,vram,local-ai
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Environment :: GPU :: NVIDIA CUDA
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Classifier: Topic :: Software Development
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.5
+Requires-Dist: pyyaml>=6.0.1
+Requires-Dist: rich>=13
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: types-PyYAML; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/mrahmedromman/mesh-deck/main/docs/assets/logo-dark.svg">
+    <img alt="mesh-deck" src="https://raw.githubusercontent.com/mrahmedromman/mesh-deck/main/docs/assets/logo-light.svg" width="320">
+  </picture>
+</p>
+
+<p align="center"><b>Know your AI stack fits your GPUs before you start it.</b></p>
+
+<p align="center">
+  <img alt="license: MIT" src="https://img.shields.io/badge/license-MIT-blue">
+  <img alt="python: 3.10+" src="https://img.shields.io/badge/python-3.10%2B-blue">
+  <img alt="status: early" src="https://img.shields.io/badge/status-early-orange">
+</p>
+
+<p align="center">
+  <a href="#quickstart">Quickstart</a> ·
+  <a href="https://github.com/mrahmedromman/mesh-deck/blob/main/docs/commands.md">Commands</a> ·
+  <a href="https://github.com/mrahmedromman/mesh-deck/blob/main/docs/config.md">Config</a> ·
+  <a href="https://github.com/mrahmedromman/mesh-deck/blob/main/docs/how-it-works.md">How it works</a> ·
+  <a href="https://github.com/mrahmedromman/mesh-deck/blob/main/CONTRIBUTING.md">Contributing</a>
+</p>
+
+`mesh` plans and starts a stack of local AI services (vLLM, speech-to-text, embeddings, TTS) on shared GPUs,
+in the right order, with one log file per service.
+
+```
+$ mesh up models.yaml
+[1/4] starting llm on port 8001  (log: logs/llm.log)
+      llm is up  (memory it added: GPU 0: ~16260 MiB, GPU 1: ~16260 MiB)
+[2/4] starting stt on port 8004  (log: logs/stt.log)
+      stt is up  (memory it added: GPU 0: ~6436 MiB)
+[3/4] starting tts on port 8005  (log: logs/tts.log)
+      tts is up  (memory it added: GPU 1: ~2353 MiB)
+[4/4] starting embed on port 8003  (log: logs/embed.log)
+      embed is up  (memory it added: GPU 1: ~3059 MiB)
+All services are up. Press Ctrl+C to stop everything.
+```
+
+> **Early release.** Built and checked on one machine with two RTX 4090s. It reads `nvidia-smi`, so it needs an
+> NVIDIA GPU and a Unix-like system (tested on Linux). Reports from other GPUs are very welcome.
+
+## Why
+
+If you run several vLLM or Docker services on one machine, you have probably hit this: the second service
+crashes at startup with *"Free memory on device ... is less than desired GPU memory utilization"*. Each service
+measures free memory when it starts, and the first one already took its share. Working out fractions that fit,
+starting things in the right order, and finding which log holds the error is tedious to redo by hand.
+
+## Features
+
+- **Checks first.** Simulates GPU memory for your services in start order and tells you which will not fit,
+  with a suggested fraction.
+- **Starts in order.** Each service waits for the previous one's health check, so they never race for memory.
+- **Any runtime.** A service is a shell command: a venv, a conda environment or `docker run`.
+- **One log per service.** `mesh logs llm -f` follows one; `-n all` prints the whole file.
+- **Reports real memory.** After each start it prints how much GPU memory that service added.
+- **Says who holds the memory.** `mesh gpu` shows each GPU's memory and utilization and names the holder: one of
+  your services, a Docker container, the desktop, or another program. It prints this automatically when a start
+  fails for lack of memory.
+- **Clean shutdown.** One Ctrl+C (or `mesh down`) stops everything in reverse order, tells you as each service
+  stops, and ends with a completion message.
+- **Readable in a terminal.** Colour, tables, memory bars, and a live line while a model loads (a spinner and
+  the time so far). When output is piped or `NO_COLOR` is set, it prints plain text.
+- **Helpful errors and Tab completion.** A mistyped command, service name, config field or file gets a "did you
+  mean" hint, and `mesh completion bash|zsh|fish` adds Tab completion, including your service names.
+- **Just a YAML file.** No daemon, no proxy, nothing listening on a port.
+
+## Install
+
+Use a separate environment from the one that runs your models; `mesh` needs only `pydantic`, `pyyaml` and `rich`.
+
+```bash
+pipx install mesh-deck     # or: pip install mesh-deck
+```
+
+To run the latest unreleased code instead:
+
+```bash
+pipx install git+https://github.com/mrahmedromman/mesh-deck.git
+```
+
+## Quickstart
+
+1. Write a `models.yaml` (see [examples/](https://github.com/mrahmedromman/mesh-deck/tree/main/examples/) for complete ones):
+
+   ```yaml
+   services:
+     - name: chat
+       port: 8001
+       gpus: [0]
+       gpu_memory_utilization: 0.55
+       overhead_mib: 1500
+       command: |
+         source ~/venvs/vllm/bin/activate
+         exec vllm serve /path/to/chat-model --port 8001 --gpu-memory-utilization 0.55
+
+     - name: embeddings
+       port: 8003
+       gpus: [0]
+       gpu_memory_utilization: 0.15
+       overhead_mib: 500
+       command: |
+         source ~/venvs/vllm/bin/activate
+         exec vllm serve /path/to/embedding-model --port 8003 --gpu-memory-utilization 0.15
+   ```
+
+2. Check that it fits, without starting anything:
+
+   ```bash
+   mesh plan models.yaml
+   ```
+
+3. Start it:
+
+   ```bash
+   mesh up models.yaml
+   ```
+
+4. In other terminals, from the same directory:
+
+   ```bash
+   mesh status              # what is running, and whether it answers
+   mesh logs chat -f        # follow one service's log
+   mesh down                # stop everything (Ctrl+C in the `mesh up` terminal does the same)
+   ```
+
+If the plan says a service will not fit, `mesh up` refuses to start unless you add `--force`. Output looks
+like this (illustrative numbers):
+
+```
+2. embeddings   FAIL
+     GPU 0: needs 3612 MiB free but only 2100 MiB is free
+     try --gpu-memory-utilization 0.08 or less
+```
+
+The first time, run `mesh up` once and copy the printed "memory it added" numbers into `measured_mib`. The
+planner is most accurate with measured numbers. See [Config](https://github.com/mrahmedromman/mesh-deck/blob/main/docs/config.md#getting-real-numbers-for-measured_mib).
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `mesh plan CONFIG` | Simulates starting the services in order and reports which ones fit. |
+| `mesh up CONFIG` | Plans, starts each service in order, waits for its health check, and reports the memory it added. |
+| `mesh down` | Stops a stack started by `mesh up`. |
+| `mesh status` | Shows each service's state, process id, port and health. |
+| `mesh logs NAME [-n N\|all] [-f]` | Shows or follows a service's log. |
+| `mesh gpu` | Shows each GPU's memory and utilization, and who is holding the memory. |
+| `mesh completion SHELL` | Prints a Tab-completion script for `bash`, `zsh` or `fish`. |
+
+All options, `mesh logs` examples, exit codes and where files go: [docs/commands.md](https://github.com/mrahmedromman/mesh-deck/blob/main/docs/commands.md).
+
+## How it works
+
+The driver keeps back some GPU memory, and vLLM measures free memory when each service starts. `mesh` subtracts
+the reserved memory and anything other programs are using, then checks each service in order, reducing what is
+free as services start. On two RTX 4090s the planned free memory matched the real `nvidia-smi` numbers to within
+about 20 MiB once real footprints were entered. Details and limits: [docs/how-it-works.md](https://github.com/mrahmedromman/mesh-deck/blob/main/docs/how-it-works.md).
+
+## Compared with
+
+- **Docker Compose** can order containers with `depends_on` and healthchecks. It is the right tool if
+  everything is a container. `mesh` also handles plain commands (a venv or conda environment) and checks
+  GPU memory before starting.
+- **[llama-swap](https://github.com/mostlygeek/llama-swap)** swaps models on demand behind one endpoint.
+  `mesh` does not proxy requests or swap: it starts a fixed set of services that stay loaded.
+- **A shell script** works fine for one machine. `mesh` replaces the parts that are tedious to redo: working
+  out the fractions, waiting on health checks, separate logs, and a clean shutdown.
+
+## Security
+
+`command` and `stop` run through `bash` with your user's permissions, so a `models.yaml` is a script. Only run
+configs you trust. `mesh` itself sends nothing anywhere: it runs `nvidia-smi`, starts your commands, and checks
+`127.0.0.1` ports.
+
+## Limitations
+
+- NVIDIA GPUs and Unix-like systems only. Not tested on Windows, AMD or Intel GPUs.
+- No request proxy or single endpoint; each service keeps its own port.
+- It does not restart a service that crashes after startup; it prints a warning.
+- `mesh gpu` needs Linux and reports a snapshot only: no live view, no per-process utilization, no killing of
+  processes. It recognises Docker containers but not Podman or Kubernetes.
+- Estimates for services nobody has measured are rough.
+- Logs are overwritten on each `mesh up`, with no rotation.
+
+## Contributing
+
+Tests need no GPU: `pip install -e ".[dev]"` then `pytest`. The most useful contribution is real `nvidia-smi`
+output from a GPU other than an RTX 4090, added as a test fixture. Bug reports and ideas are welcome as issues.
+See [CONTRIBUTING.md](https://github.com/mrahmedromman/mesh-deck/blob/main/CONTRIBUTING.md) for the exact commands, what to include in a bug report, and what is in
+scope.
+
+## License
+
+[MIT](https://github.com/mrahmedromman/mesh-deck/blob/main/LICENSE)

mesh_deck-0.1.0/README.md

@@ -0,0 +1,196 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/mrahmedromman/mesh-deck/main/docs/assets/logo-dark.svg">
+    <img alt="mesh-deck" src="https://raw.githubusercontent.com/mrahmedromman/mesh-deck/main/docs/assets/logo-light.svg" width="320">
+  </picture>
+</p>
+
+<p align="center"><b>Know your AI stack fits your GPUs before you start it.</b></p>
+
+<p align="center">
+  <img alt="license: MIT" src="https://img.shields.io/badge/license-MIT-blue">
+  <img alt="python: 3.10+" src="https://img.shields.io/badge/python-3.10%2B-blue">
+  <img alt="status: early" src="https://img.shields.io/badge/status-early-orange">
+</p>
+
+<p align="center">
+  <a href="#quickstart">Quickstart</a> ·
+  <a href="https://github.com/mrahmedromman/mesh-deck/blob/main/docs/commands.md">Commands</a> ·
+  <a href="https://github.com/mrahmedromman/mesh-deck/blob/main/docs/config.md">Config</a> ·
+  <a href="https://github.com/mrahmedromman/mesh-deck/blob/main/docs/how-it-works.md">How it works</a> ·
+  <a href="https://github.com/mrahmedromman/mesh-deck/blob/main/CONTRIBUTING.md">Contributing</a>
+</p>
+
+`mesh` plans and starts a stack of local AI services (vLLM, speech-to-text, embeddings, TTS) on shared GPUs,
+in the right order, with one log file per service.
+
+```
+$ mesh up models.yaml
+[1/4] starting llm on port 8001  (log: logs/llm.log)
+      llm is up  (memory it added: GPU 0: ~16260 MiB, GPU 1: ~16260 MiB)
+[2/4] starting stt on port 8004  (log: logs/stt.log)
+      stt is up  (memory it added: GPU 0: ~6436 MiB)
+[3/4] starting tts on port 8005  (log: logs/tts.log)
+      tts is up  (memory it added: GPU 1: ~2353 MiB)
+[4/4] starting embed on port 8003  (log: logs/embed.log)
+      embed is up  (memory it added: GPU 1: ~3059 MiB)
+All services are up. Press Ctrl+C to stop everything.
+```
+
+> **Early release.** Built and checked on one machine with two RTX 4090s. It reads `nvidia-smi`, so it needs an
+> NVIDIA GPU and a Unix-like system (tested on Linux). Reports from other GPUs are very welcome.
+
+## Why
+
+If you run several vLLM or Docker services on one machine, you have probably hit this: the second service
+crashes at startup with *"Free memory on device ... is less than desired GPU memory utilization"*. Each service
+measures free memory when it starts, and the first one already took its share. Working out fractions that fit,
+starting things in the right order, and finding which log holds the error is tedious to redo by hand.
+
+## Features
+
+- **Checks first.** Simulates GPU memory for your services in start order and tells you which will not fit,
+  with a suggested fraction.
+- **Starts in order.** Each service waits for the previous one's health check, so they never race for memory.
+- **Any runtime.** A service is a shell command: a venv, a conda environment or `docker run`.
+- **One log per service.** `mesh logs llm -f` follows one; `-n all` prints the whole file.
+- **Reports real memory.** After each start it prints how much GPU memory that service added.
+- **Says who holds the memory.** `mesh gpu` shows each GPU's memory and utilization and names the holder: one of
+  your services, a Docker container, the desktop, or another program. It prints this automatically when a start
+  fails for lack of memory.
+- **Clean shutdown.** One Ctrl+C (or `mesh down`) stops everything in reverse order, tells you as each service
+  stops, and ends with a completion message.
+- **Readable in a terminal.** Colour, tables, memory bars, and a live line while a model loads (a spinner and
+  the time so far). When output is piped or `NO_COLOR` is set, it prints plain text.
+- **Helpful errors and Tab completion.** A mistyped command, service name, config field or file gets a "did you
+  mean" hint, and `mesh completion bash|zsh|fish` adds Tab completion, including your service names.
+- **Just a YAML file.** No daemon, no proxy, nothing listening on a port.
+
+## Install
+
+Use a separate environment from the one that runs your models; `mesh` needs only `pydantic`, `pyyaml` and `rich`.
+
+```bash
+pipx install mesh-deck     # or: pip install mesh-deck
+```
+
+To run the latest unreleased code instead:
+
+```bash
+pipx install git+https://github.com/mrahmedromman/mesh-deck.git
+```
+
+## Quickstart
+
+1. Write a `models.yaml` (see [examples/](https://github.com/mrahmedromman/mesh-deck/tree/main/examples/) for complete ones):
+
+   ```yaml
+   services:
+     - name: chat
+       port: 8001
+       gpus: [0]
+       gpu_memory_utilization: 0.55
+       overhead_mib: 1500
+       command: |
+         source ~/venvs/vllm/bin/activate
+         exec vllm serve /path/to/chat-model --port 8001 --gpu-memory-utilization 0.55
+
+     - name: embeddings
+       port: 8003
+       gpus: [0]
+       gpu_memory_utilization: 0.15
+       overhead_mib: 500
+       command: |
+         source ~/venvs/vllm/bin/activate
+         exec vllm serve /path/to/embedding-model --port 8003 --gpu-memory-utilization 0.15
+   ```
+
+2. Check that it fits, without starting anything:
+
+   ```bash
+   mesh plan models.yaml
+   ```
+
+3. Start it:
+
+   ```bash
+   mesh up models.yaml
+   ```
+
+4. In other terminals, from the same directory:
+
+   ```bash
+   mesh status              # what is running, and whether it answers
+   mesh logs chat -f        # follow one service's log
+   mesh down                # stop everything (Ctrl+C in the `mesh up` terminal does the same)
+   ```
+
+If the plan says a service will not fit, `mesh up` refuses to start unless you add `--force`. Output looks
+like this (illustrative numbers):
+
+```
+2. embeddings   FAIL
+     GPU 0: needs 3612 MiB free but only 2100 MiB is free
+     try --gpu-memory-utilization 0.08 or less
+```
+
+The first time, run `mesh up` once and copy the printed "memory it added" numbers into `measured_mib`. The
+planner is most accurate with measured numbers. See [Config](https://github.com/mrahmedromman/mesh-deck/blob/main/docs/config.md#getting-real-numbers-for-measured_mib).
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `mesh plan CONFIG` | Simulates starting the services in order and reports which ones fit. |
+| `mesh up CONFIG` | Plans, starts each service in order, waits for its health check, and reports the memory it added. |
+| `mesh down` | Stops a stack started by `mesh up`. |
+| `mesh status` | Shows each service's state, process id, port and health. |
+| `mesh logs NAME [-n N\|all] [-f]` | Shows or follows a service's log. |
+| `mesh gpu` | Shows each GPU's memory and utilization, and who is holding the memory. |
+| `mesh completion SHELL` | Prints a Tab-completion script for `bash`, `zsh` or `fish`. |
+
+All options, `mesh logs` examples, exit codes and where files go: [docs/commands.md](https://github.com/mrahmedromman/mesh-deck/blob/main/docs/commands.md).
+
+## How it works
+
+The driver keeps back some GPU memory, and vLLM measures free memory when each service starts. `mesh` subtracts
+the reserved memory and anything other programs are using, then checks each service in order, reducing what is
+free as services start. On two RTX 4090s the planned free memory matched the real `nvidia-smi` numbers to within
+about 20 MiB once real footprints were entered. Details and limits: [docs/how-it-works.md](https://github.com/mrahmedromman/mesh-deck/blob/main/docs/how-it-works.md).
+
+## Compared with
+
+- **Docker Compose** can order containers with `depends_on` and healthchecks. It is the right tool if
+  everything is a container. `mesh` also handles plain commands (a venv or conda environment) and checks
+  GPU memory before starting.
+- **[llama-swap](https://github.com/mostlygeek/llama-swap)** swaps models on demand behind one endpoint.
+  `mesh` does not proxy requests or swap: it starts a fixed set of services that stay loaded.
+- **A shell script** works fine for one machine. `mesh` replaces the parts that are tedious to redo: working
+  out the fractions, waiting on health checks, separate logs, and a clean shutdown.
+
+## Security
+
+`command` and `stop` run through `bash` with your user's permissions, so a `models.yaml` is a script. Only run
+configs you trust. `mesh` itself sends nothing anywhere: it runs `nvidia-smi`, starts your commands, and checks
+`127.0.0.1` ports.
+
+## Limitations
+
+- NVIDIA GPUs and Unix-like systems only. Not tested on Windows, AMD or Intel GPUs.
+- No request proxy or single endpoint; each service keeps its own port.
+- It does not restart a service that crashes after startup; it prints a warning.
+- `mesh gpu` needs Linux and reports a snapshot only: no live view, no per-process utilization, no killing of
+  processes. It recognises Docker containers but not Podman or Kubernetes.
+- Estimates for services nobody has measured are rough.
+- Logs are overwritten on each `mesh up`, with no rotation.
+
+## Contributing
+
+Tests need no GPU: `pip install -e ".[dev]"` then `pytest`. The most useful contribution is real `nvidia-smi`
+output from a GPU other than an RTX 4090, added as a test fixture. Bug reports and ideas are welcome as issues.
+See [CONTRIBUTING.md](https://github.com/mrahmedromman/mesh-deck/blob/main/CONTRIBUTING.md) for the exact commands, what to include in a bug report, and what is in
+scope.
+
+## License
+
+[MIT](https://github.com/mrahmedromman/mesh-deck/blob/main/LICENSE)

mesh_deck-0.1.0/SECURITY.md

@@ -0,0 +1,20 @@
+# Security policy
+
+## Reporting a vulnerability
+
+Please do not open a public issue for a security problem. Use GitHub's private reporting instead: open the
+repository's **Security** tab and choose **Report a vulnerability**.
+
+Include the `mesh --version`, what you did, and what you expected. You can expect a reply within a week.
+
+## What counts
+
+`mesh` runs the `command` and `stop` lines of a `models.yaml` through `bash` with your user's permissions, by design.
+A config file is a script, so running a config you do not trust is not a vulnerability in `mesh`.
+
+In scope: a way to make `mesh` run something that is not in the config, write outside the log directory, or signal
+processes that do not belong to the stack.
+
+## Supported versions
+
+Only the latest release receives fixes while the project is in alpha.

mesh_deck-0.1.0/docs/assets/logo-dark.svg

@@ -0,0 +1,14 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="340" height="96" viewBox="0 0 340 96" role="img" aria-label="mesh-deck">
+  <title>mesh-deck</title>
+  <!-- Two GPUs as tall outlines. Coloured blocks are services sharing the memory; the empty top is free memory. -->
+  <rect x="8" y="8" width="32" height="80" rx="6" fill="none" stroke="#d1d5db" stroke-width="3"/>
+  <rect x="12" y="50" width="24" height="34" rx="3" fill="#60a5fa"/>
+  <rect x="12" y="28" width="24" height="20" rx="3" fill="#2dd4bf"/>
+
+  <rect x="48" y="8" width="32" height="80" rx="6" fill="none" stroke="#d1d5db" stroke-width="3"/>
+  <rect x="52" y="50" width="24" height="34" rx="3" fill="#60a5fa"/>
+  <rect x="52" y="36" width="24" height="12" rx="3" fill="#fbbf24"/>
+  <rect x="52" y="22" width="24" height="12" rx="3" fill="#a78bfa"/>
+
+  <text x="100" y="62" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, 'Liberation Mono', monospace" font-size="40" font-weight="700" fill="#f9fafb">mesh-deck</text>
+</svg>

mesh_deck-0.1.0/docs/assets/logo-light.svg

@@ -0,0 +1,14 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="340" height="96" viewBox="0 0 340 96" role="img" aria-label="mesh-deck">
+  <title>mesh-deck</title>
+  <!-- Two GPUs as tall outlines. Coloured blocks are services sharing the memory; the empty top is free memory. -->
+  <rect x="8" y="8" width="32" height="80" rx="6" fill="none" stroke="#374151" stroke-width="3"/>
+  <rect x="12" y="50" width="24" height="34" rx="3" fill="#3b82f6"/>
+  <rect x="12" y="28" width="24" height="20" rx="3" fill="#14b8a6"/>
+
+  <rect x="48" y="8" width="32" height="80" rx="6" fill="none" stroke="#374151" stroke-width="3"/>
+  <rect x="52" y="50" width="24" height="34" rx="3" fill="#3b82f6"/>
+  <rect x="52" y="36" width="24" height="12" rx="3" fill="#f59e0b"/>
+  <rect x="52" y="22" width="24" height="12" rx="3" fill="#8b5cf6"/>
+
+  <text x="100" y="62" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, 'Liberation Mono', monospace" font-size="40" font-weight="700" fill="#111827">mesh-deck</text>
+</svg>