mfabric.

Peers

Download the signed Windows installer or the manual zip on each helper device, verify the SHA-256 hash, run the installer or peer launcher, choose Helper / peer, paste the join link, and approve the peer on the host.

Windows PowerShell

Get-FileHash -Algorithm SHA256 .\mfabric_peer_setup_*.exe
Get-FileHash -Algorithm SHA256 .\mfabric_public_beta_peer_current.zip

Good manual-zip extract locations

~/mfabric_public_beta
~/Downloads/mfabric_public_beta
%USERPROFILE%\Downloads\mfabric_public_beta

Avoid

If you use the manual zip, do not run from inside a compressed-zip viewer. Do not extract into system folders such as /usr, /System, C:\Windows, or C:\Program Files.

macOS / Linux

python3 -m pip install -r requirements-agent.txt
python3 mfabric_peer_bootstrap.py --join-url PASTE_HOST_JOIN_LINK --detach

Tailscale range

Tailscale IPv4 uses 100.64.0.0/10. The broad CIDR is convenient but is also the carrier-grade NAT range, so exact /32 entries are safer. This version accepts numeric addresses, not MagicDNS names.

Cellular

Put the host gateway behind a private mesh tunnel or authenticated HTTPS endpoint. Start the gateway with exact-origin CORS and bearer-token auth, then enter that URL in the phone client.

Verified adapter row

The host package may show a model-specific verified row when that adapter has passed its own validation. Treat each model family separately.

Advanced host controls

If a private host build exposes an experimental path, it should document that path separately from this public manual.

Revoke

Use the host control panel when a device should no longer be trusted. Open the credentials table, find the peer, and choose Revoke.

Memory-sharing private experiment

The Qwen2/Qwen2.5 fixture can keep a bounded recent KV context on the model device and store older exact pages as authenticated encrypted blocks on approved storage helpers. A real model has not cleared both long-context generated-token quality and speed against exact execution, so this is not a promoted consumer route.

The consumer console deliberately provides no activation or availability controls for this lane. Ordinary chat stays on the exact local route. The adapter remains available only to its private evidence gate under an explicit experimental configuration.

Run 2Big2Fit across trusted computers

2Big2Fit assigns contiguous layer ranges of one dense Hugging Face model to trusted compute helpers. Each helper keeps only its assigned model layers and the K/V for the current driver session. Authenticated hidden-state frames move between stages; storage-only helpers cannot be selected.

1. Cache the same Hugging Face model snapshot on the host and every compute helper, then join and approve each helper with compute permission.
2. Set the same private 24-or-more-character MFABRIC_2BIG2FIT_STAGE_TOKEN environment value on the host and every selected helper. Do not paste it into the console or a command.
3. Open Run a model across trusted computers, select the model and approved compute helpers in stage order, accept the tensor-exposure disclosure, and press Set up.
4. Run each printed mfab stages start command on its named helper, then press Check stages.
5. After the authenticated fingerprint, dtype, ordering, and coverage checks pass, enter a bounded prompt and press Run across stages.

Peer does not show up

• An approved peer is counted immediately (the approved-helpers count goes up); its own card appears once its runtime reports presence. A missing card right after approval is normal.
• Confirm the peer window is still open.
• Confirm the join request was approved on the host.
• Check local firewall prompts for Python.
• Re-copy the join link and run the peer launcher again.

Peer shows up but does not work

• Some peers are storage-only.
• A peer may be low battery, active, offline, or not eligible for compute.
• The workload may require a specific host-side adapter.
• If fallback events appear, the host is recovering from a peer miss or unavailable worker/path.
• Keep the workload on the standard safe default unless the host operator explicitly enables an experimental path.

Transfer rate is zero

That is normal when no workload is moving data. Run a workload or block-transfer test to see activity.

Pooled memory looks small

MFabric displays the storage budget allocated to the fabric, not every byte of physical RAM on every peer. The context estimate is a planning tier, not a promise that every model can use that much context.

Connecting another computer

Adding a second machine takes three steps. The join link is the only path that adds a machine in this beta — there is no add-by-address box.

1. On this computer’s console, open + connect another computer (near the bottom of the page). It shows this machine’s join link and a ready-to-copy join command.
2. On the OTHER machine, from its extracted mfabric_public_beta folder, run the copied command: python3 mfabric_peer_bootstrap.py --join-url <this computer's join link> --detach
3. Back on this console, the machine appears under Waiting for approval — press Approve. The approved-helpers count updates immediately; the machine’s own card appears once its helper runtime starts reporting in.

Using the native runtime route for dense models

The native runtime route is a faster local execution path for dense Qwen2 and Qwen3 models with a hidden size up to 2048 (roughly 3B parameters and below). Models above that size use the standard path automatically.

This route ships in the source/package bundle when the public native runtime files are present. If your install does not include those files, or the optional runtime dependencies are unavailable, every model uses the standard path (you will see runtime_route: hf_generate).

1. Scan your local models using the Load a local model panel. Entries that cannot load are greyed out with the reason: not a chat model (speech/embedding), config only — weights not downloaded, or won't fit — needs ~X GB, GPU has Y GB.
2. Select a dense Qwen2 or Qwen3 model and press Load.
3. Send a chat prompt. When the model answers, the response details line shows a runtime_route field such as qwen2 or qwen3 for the native path, or hf_generate for the standard path.
4. You do not need to configure anything. The console picks the native path automatically when the model qualifies, unless you set MFABRIC_PUBLIC_DISABLE_NATIVE_RUNTIME=1 to force the standard path.
5. Larger models (hidden size above 2048, such as 7B+ dense Qwen) use the standard path automatically; the response details will show hf_generate for those.

Memory-sharing experiment boundary

The memory-sharing fixture can bound recent KV locally and store older exact pages as encrypted blocks on approved helpers. It remains a private experiment until a real-model row clears both quality and speed. Full boundaries are in the advanced-capability section above.

The consumer console does not offer a switch for this route. Exact local execution remains the supported route; private evidence runs use a separate explicit experimental configuration.

Running 2Big2Fit (split model)

2Big2Fit is an opt-in authenticated stage pipeline across trusted compute helpers. Full setup, trust boundaries, and CLI commands are in the 2Big2Fit section above.

1. Select a locally cached Hugging Face model and approved compute helpers in stage order.
2. Start the printed authenticated stage command on each helper.
3. Check topology, then run a bounded buffered prompt.

Understanding exact repeat routing

MFabric keeps a bounded host-local cache of the last 256 successful local answers. An identical prompt with the same loaded model and output-token limit can return the byte-identical answer without a second model call. New prompts, changed token limits, and newly loaded models run normally.

Understanding the streaming indicator and TTFT

The chat panel can stream tokens as they arrive rather than waiting for the whole answer. This makes responses feel faster even when total generation time is the same.

1. Send a prompt in the chat panel.
2. A streaming badge appears next to the response header only when tokens are arriving in real time. Supported local Hugging Face models use real model-produced text deltas rather than a simulated typing delay.
3. When an answer streams, a TTFT readout (time to first token, in milliseconds) shows how long the console waited before the first token appeared. A lower number means a faster response start.
4. Buffered delivery happens when the model or peer does not stream token-by-token, or when the whole answer arrives before the first render cycle. Nothing is wrong; only the on-screen typing effect differs.
5. Both modes produce the same answer. Streaming only changes when characters appear on screen.
6. While a local answer is running, click Stop to cancel its active generation request. Text already received stays visible.

Connecting a local OpenAI-compatible app

The host process that owns the loaded model also serves the API, so a second process cannot accidentally advertise a different or unloaded model.

1. Start the host and load a model in the console.
2. Set the app base URL to http://127.0.0.1:8788/v1, or use the actual console port shown at startup.
3. Call GET /v1/models to obtain the loaded model id.
4. Send chat requests to POST /v1/chat/completions, or text prompts to POST /v1/completions. Both support SSE with stream: true.
5. Loaded Hugging Face models also expose bounded contextual vectors at POST /v1/embeddings. GGUF embeddings fail closed in this build.

Local file tools support one list_files, read_file, or write_file call per request. The request must come from loopback, set mfabric_file_tool_consent: true, and stay inside a folder already approved in the console. Absolute paths are not returned.

Checking live device telemetry

The telemetry panel shows real-time GPU memory, CPU load, and health for every approved device in your fabric.

1. Open the host console in your browser.
2. Scroll to the Telemetry section (or click its link in the capabilities panel).
3. Each device card shows GPU memory used, CPU percent, and whether the device is currently online.
4. The small sparkline graph shows recent GPU memory use over time.
5. If no telemetry appears, the device may be offline or not yet approved.

Running a batch of prompts

The batch panel runs several prompts at once and returns one result list.

1. Open the host console and go to the Agent swarm or batch panel.
2. Type or paste your tasks, one per line, into the task input box.
3. Press Run. Each task is sent in parallel and tracked as a separate row.
4. When all tasks finish, each row shows the answer, the tier it used, and how long it took.
5. Press Clear to reset the list before the next batch.

Checking for a newer version

MFabric does not check for updates automatically. Use this step to check manually whenever you want.

1. Open the host console.
2. Click Check for updates in the header bar, or open the Check for a newer version capability panel and press Check for update.
3. The console fetches the public update manifest. No device info, model list, or local paths are sent.
4. If a newer build is available, the status line shows the version number and where to download it.
5. If you are already on the latest build, the status line confirms that.

Five steps to your first chat

1. Check the environment: mfab doctor
2. Start the host: mfab host start --detach
3. List local models: mfab models list
4. Load a model: mfab models load <model-ref>
5. Send a prompt: mfab chat "What does MFabric do?"

Quick start (from --help)

python mfab_cli.py doctor        check this machine is ready
python mfab_cli.py host start    start the console
                                 (Ctrl+C stops it; --detach = background)
python mfab_cli.py host open     open the console in your browser
python mfab_cli.py chat "hello"  talk to the loaded model

on another computer:
python mfab_cli.py helper join <join-url from the host console>

Available commands: doctor · host · helper · peers · models · chat · gateway · update · logs · config · experimental.

Stream tokens

mfab chat --stream "Summarize what a private fabric does"

Tokens appear as they arrive instead of waiting for the full answer.

Check for updates

mfab update

Fetches the public release manifest. No device info, model list, or local paths are sent.

Advertise a trusted overlay address

mfab config set trusted_networks <cidr[,cidr...]>
mfab config set advertise_host <numeric-ip>

Default-empty and numeric-only. Public CIDRs, malformed settings, redirects, and proxy-routed peer control traffic fail closed.