MLX Knife is designed to run locally on your Apple Silicon Mac. It prioritizes user privacy and security by keeping all model execution local.

Important distinction: MLX Knife integrates upstream libraries (mlx-lm, mlx-vlm, mlx-audio, transformers) whose behavior is outside our direct control. This document describes what mlx-knife itself does; upstream libraries may behave differently.

• ✅ Runs models locally on your device
• ✅ Downloads models only from HuggingFace (via pull, clone)
• ✅ Uploads only when you explicitly run push (opt-in, requires credentials)
• ✅ API server binds to localhost by default
• ✅ No telemetry or usage tracking
• ✅ No automatic updates or phone-home features

• ❌ No model outputs are logged or transmitted
• ❌ No user tracking or analytics
• ❌ mlx-knife code does not initiate network requests during run, server, or show

MLX Knife uses external libraries to load and run models. These libraries may download additional files when a model is first used - this is outside mlx-knife's control.

What this means:

• Downloading a model with pull does not guarantee fully offline use
• Some models may need additional downloads when first run
• We recommend models from mlx-community/* but cannot guarantee third-party behavior

For offline environments: Test each model while online before relying on offline use. Use mlxk clone to create a local workspace for better isolation.

If you discover a security vulnerability in MLX Knife, please help us address it responsibly:

• ❌ Open a public GitHub issue
• ❌ Post about it on social media
• ❌ Exploit it maliciously

1. Email: Send details to broke@gmx.eu
2. Or: Create a private security advisory on GitHub
3. Include:
   • Affected version(s)
   • Steps to reproduce
   • Potential impact
   • Suggested fix (if any)

We will acknowledge receipt within 48 hours and work on a fix.

• Source: Models are downloaded from HuggingFace only
• Verification: HuggingFace provides checksums for file integrity
• Risk: Malicious models could theoretically exist on HuggingFace
• Mitigation: Only download models from trusted organizations (e.g., mlx-community)

# Safe (localhost only):
mlxk server --port 8000

# CAUTION (network accessible):
mlxk server --host 0.0.0.0 --port 8000

WARNING: When using --host 0.0.0.0:

• The API becomes accessible from your network
• No built-in authentication or rate limiting
• Anyone on your network can use your models
• Could potentially be exposed to the internet (check firewall!)

Recommendations for network access:

• Use a reverse proxy with authentication (nginx, Caddy)
• Implement firewall rules
• Never expose directly to the internet
• Consider VPN-only access

• Memory: Large models can consume significant RAM/GPU memory
• CPU/GPU: Model execution can be resource-intensive
• Disk: Models are cached locally (can be multiple GB each)

• Cache Location: ~/.cache/huggingface/hub or $HF_HOME
• Permissions: Standard user permissions apply
• Cleanup: Use mlxk rm <model> to safely remove models; avoid manual deletion in the user cache

• Separate contexts: use an isolated test cache for automated tests; keep the user cache for manual/production work
• HF_HOME: set explicitly for user work if needed; tests should not override user HF_HOME by default
• Safe operations: reads (list, health, show) are always safe; coordinate writes (pull, rm) in maintenance windows
• Test safeguards: the test suite places a sentinel in the test cache and enforces deletion guards to prevent accidental user-cache modification

The 2.0 alpha introduces an alpha upload capability. Treat it as opt‑in, with explicit user control.

• Upload‑only: pushes a specified local folder to a Hugging Face model repo via huggingface_hub.upload_folder.
• Requires HF_TOKEN; in alpha, --private is required to reduce accidental exposure.
• Default branch is main (overridable with --branch). No manifests or content validation yet.
• Honors default ignore patterns and merges project .hfignore when present (e.g., excludes .git/, .venv/, __pycache__/, .DS_Store).

• Only files under the path you provide are considered; push does not scan your global caches or home directory.
• No prompts, logs, or runtime telemetry are uploaded.
• No background activity: nothing is sent unless you invoke mlxk2 push.

• Preflight without network: --check-only analyzes the local folder for obvious issues (e.g., missing shards, LFS pointers).
• Plan without committing: --dry-run lists prospective adds/deletes vs remote (no upload performed).
• Use restricted tokens and test repos when validating; prefer --private and organization/user repos you control.

• Risk: Accidental upload of sensitive files included in the folder.
  • Mitigate with a minimal, dedicated workspace, .hfignore, and --check-only/--dry-run before pushing.
• Risk: Pushing incomplete or corrupted weights.
  • Mitigate by reviewing workspace_health from --check-only and model card requirements before uploading.

You are responsible for complying with Hugging Face Hub policies and applicable laws (e.g., copyright/licensing) for any uploaded content. Review all content before uploading and ensure you have appropriate rights to distribute the models and associated files.

• Network egress targets only Hugging Face over HTTPS; no third‑party endpoints.
• In --json mode, hub logs may be captured in output for diagnostics; they are not transmitted elsewhere by MLX Knife.

1. Download models only from trusted sources (prefer mlx-community/*)
2. Keep the API server local unless you need network access
3. Monitor disk usage - models can be large
4. Review model cards on HuggingFace before downloading
5. Keep Python dependencies updated: pip install --upgrade mlx-knife

1. Never commit secrets (API keys, tokens)
2. Validate all inputs in new features
3. Use secure defaults (localhost binding, etc.)
4. Document security implications of new features
5. Test for resource exhaustion (memory, disk)

We provide security updates for these versions:

• HuggingFace Security
• Apple Platform Security
• Python Security

Remember: Security is everyone's responsibility. If something doesn't feel right, please report it! 🦫