Metadata-Version: 2.4
Name: mfabric-consumer-public-beta
Version: 0.2.0
Summary: Accountless private AI fabric for trusted local and owned-device execution.
Author: Sfiniti AI Inc
License-Expression: AGPL-3.0-only
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: LICENSING.md
Requires-Dist: cryptography>=42
Requires-Dist: psutil>=5.9
Requires-Dist: zeroconf>=0.132
Provides-Extra: hf
Requires-Dist: torch>=2.1; extra == "hf"
Requires-Dist: transformers>=4.40; extra == "hf"
Requires-Dist: huggingface-hub>=0.23; extra == "hf"
Provides-Extra: gguf
Requires-Dist: llama-cpp-python>=0.2; extra == "gguf"
Provides-Extra: semantic
Requires-Dist: sentence-transformers>=2.5; extra == "semantic"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: playwright>=1.45; extra == "dev"
Requires-Dist: numpy>=1.24; extra == "dev"
Dynamic: license-file

# MFabric Consumer (early beta)

Run a local AI model on one computer you own and use it from another Windows,
Linux or Mac computer on your trusted home or office network. No MFabric
account, no cloud service, no VPN.

- **Host**: the computer you type on. It runs a small console and decides which
  other computers may help.
- **Helper**: a computer with a model (and ideally a GPU). It serves the model
  only after you approve it on the host, and stops when you revoke it.

Every answer comes with a signed receipt saying which approved computer ran it.

This is an early beta for trusted local networks. Read "Security boundary"
below before you use it.

## Requirements

- Python 3.11 or newer on each computer.
- Both computers on the same Wi-Fi or Ethernet network (not a guest network
  that isolates devices).
- On the helper: a GGUF model file (for example from Hugging Face) and disk
  space for the llama.cpp runtime (about 10 MB on macOS, up to about 600 MB for
  NVIDIA CUDA builds).

## Install (both computers)

MFabric is not on PyPI yet. Install from this source tree:

```bash
python -m venv .venv
. .venv/bin/activate              # Windows PowerShell: .venv\Scripts\Activate.ps1
python -m pip install .
mfab doctor
```

## 1. Start the host

```bash
mfab host start --detach
```

It prints a **join link** such as `http://<host address>:8935/join?invite=...`
and keeps running in the background until `mfab host stop`. If the computer
has several network adapters, pick the one both computers share:
`mfab host start --detach --advertise-host <this computer's LAN address>`.

## 2. Prepare the helper

Install the official llama.cpp server for this computer. MFabric picks the
right build (CUDA on NVIDIA, Metal on Apple silicon, CPU otherwise) from the
official ggml-org GitHub releases and checks each file's published SHA-256:

```bash
mfab helper install-llama-server
```

Download a GGUF model yourself into your `Downloads` folder. MFabric never
downloads models on its own. A small one to start with:
`qwen2.5-1.5b-instruct-q4_k_m.gguf` from the `Qwen/Qwen2.5-1.5B-Instruct-GGUF`
repository on Hugging Face.

Put a private gateway key in a file that only you can read (any random string
of 16 or more characters). The host needs the same key later.

## 3. Join the helper and approve it

On the helper:

macOS / Linux:

```bash
mfab setup --role helper --allow-peer-compute \
  --model qwen2.5-1.5b-instruct-q4_k_m.gguf \
  --gateway-key-file <your key file> \
  --join-url "<join link from the host>"
```

Windows (PowerShell, one line):

```powershell
mfab setup --role helper --allow-peer-compute --model qwen2.5-1.5b-instruct-q4_k_m.gguf --gateway-key-file <your key file> --join-url "<join link from the host>"
```

The helper loads the model, then prints a **pairing phrase**. Open the host
console (`mfab host open`), check that the phrase matches, and approve the
helper. Keep the helper terminal open while it serves.

The helper then checks that the host can reach it. If a firewall blocks it,
the helper prints the exact fix for its operating system.

## 4. Connect and chat (on the host)

```bash
mfab peers list
mfab peers connect <helper peer id> --key-file <your key file>
mfab chat --peer <helper peer id> "Why keep a model on one computer and use it from another?"
```

Approvals survive a host restart: after `mfab host stop` and `mfab host start --detach`,
`mfab chat --peer <id> "..."` works again without reconnecting.

## 5. Revoke and stop

```bash
mfab peers revoke <helper peer id>     # the helper is refused from now on
mfab host stop
```

Stop the helper with Ctrl+C in its terminal. To use it again after revoking,
join and approve it again.

## Operating-system notes

**Windows helper.** Windows Firewall blocks inbound connections by default. Add
`--allow-firewall-rule` to the helper's `mfab setup` command to create a narrow
rule for its ports (Windows asks for administrator approval), or follow the
command the helper prints.

**macOS.** macOS blocks apps from reaching computers on your local network
until you allow them. When macOS asks whether Terminal (or your editor) may
find devices on your local network, choose Allow. If you missed it: System
Settings > Privacy & Security > Local Network, turn on your terminal app. Also
stop the Mac sleeping while it serves: `caffeinate -dimsu` in a separate
terminal, or turn off automatic sleep in System Settings.

**Linux.** If `ufw` or `firewalld` is active, allow the helper's gateway port
(8788 by default) from your local network only.

## Security boundary

- Remote model traffic between host and helper uses **HTTP on your local
  network**. The gateway key and pairing signatures control who may use a
  helper, but they do not encrypt prompts or answers in transit. Use this only
  on a network you trust. Do not expose these ports to the Internet or forward
  them on your router.
- Revoking a helper stops new requests routed by the host. The helper's own
  gateway key is separate; change it if you revoke a helper you no longer trust.
- MFabric does not combine several computers' GPU memory into one model, and it
  does not make models faster than the llama.cpp runtime it uses.

## Updates

This source beta does not update itself. To update, get the newer source and
run `python -m pip install .` again. `mfab update` reports that no signed update
channel is configured for this build.

## License

AGPL-3.0-only; a commercial license is also available. See `LICENSE` and
`LICENSING.md`.

Copyright (c) 2026 Sfiniti AI Inc.
