m-gpux 1.0.13

Professional CLI toolkit for Modal GPU workflows, account management, and billing visibility

🚀 m-gpux

A professional CLI toolkit for Modal power users. Need fast GPU access, multi-profile account control, and simple cost visibility? Look no further.

---

✨ Highlights

• 🧠 LLM API Server — Deploy any HuggingFace model as an OpenAI-compatible endpoint with API key auth.
• ⚡ Interactive GPU Hub — Spin up Jupyter, execute scripts, and establish web shell sessions instantly.
• 👥 Multi-Account Management — Seamlessly manage multiple profiles in one unified command namespace.
• 💸 Unified Cost Visibility — Inspect billing per profile or get a comprehensive view across all configured accounts.
• 🎨 Friendly Terminal UX — Enjoy rich tables, intuitive prompts, and interactive guided flows right in your terminal.

📖 Table of Contents

• Installation
• Quick Start
• Core Commands
  • Profile Management
  • Interactive Hub
  • LLM API Server
  • Billing
• Architecture
• Troubleshooting
• Contributing

---

⚙️ Installation

Prerequisites

• Python: 3.10 or higher.
• Credentials: Modal account credentials (token_id, token_secret).
• Modal CLI: Ensure the modal CLI is installed and in your PATH.

PyPI (Recommended)

The fastest way to get started is by installing directly from PyPI.

pip install m-gpux

From Source

Great for contributors or users who want the bleeding edge.

git clone https://github.com/PuxHocDL/m-gpux.git
cd m-gpux
pip install -e .

---

🚀 Quick Start

Get up and running in 5 easy steps:

# 1) Add your first profile
m-gpux account add

# 2) Check configured profiles
m-gpux account list

# 3) Launch the interactive GPU hub
m-gpux hub

# 4) Deploy an LLM as an OpenAI-compatible API
m-gpux serve deploy

# 5) Inspect 30-day usage across all accounts
m-gpux billing usage --days 30 --all

---

🛠️ Core Commands

Whether you need to manage your accounts, deploy APIs, or check your billing, we've got you covered. Check out our global commands with m-gpux --help and m-gpux info.

👥 Profile Management

Seamlessly hop between different Modal environments.

m-gpux account list                    # View all active profiles
m-gpux account add                     # Interactively add a new profile
m-gpux account switch <profile_name>   # Switch active profile
m-gpux account remove <profile_name>   # Remove an existing profile

Note: Modal profiles are safely persisted in ~/.modal.toml. If the active profile is removed, another existing profile is automatically promoted.

⚡ Interactive Hub

Your control center for remote execution.

m-gpux hub

Actions included:

• 🪐 Launch Jupyter Lab on your selected GPU.
• 📜 Run local Python scripts natively on remote GPUs.
• 💻 Initiate an interactive web Bash shell session.

🧠 LLM API Server

Turn your HuggingFace models into live endpoints.

m-gpux serve deploy             # Deploy a model (interactive wizard)
m-gpux serve dashboard          # Live metrics dashboard in terminal
m-gpux serve logs               # Stream server logs
m-gpux serve warmup             # Trigger cold start and warm up engine
m-gpux serve stop               # Stop the server

# Secure your endpoints
m-gpux serve keys create        # Generate a new API key
m-gpux serve keys list          # List all keys (masked for security)
m-gpux serve keys show <name>   # Reveal the full key value
m-gpux serve keys revoke <name> # Revoke access

Key Features:

• Bearer token authentication (401/403).
• Full support for streaming & non-streaming chat completions.
• Live dashboard — GPU/CPU/RAM metrics, latency percentiles, traffic, and token counts with progress bars.
• Resilient proxy — automatic retry with backoff, backpressure (429), internal streaming to prevent timeouts on long inference.
• Configurable vLLM hyperparameters (GPU memory utilization, tensor parallelism, max sequences).
• 11 built-in popular model presets (Qwen, Llama, Gemma, Phi, etc.).

💸 Billing

Keep unexpected costs at bay.

m-gpux billing open                    # Open billing dashboard in browser
m-gpux billing usage --days 7          # Review last 7 days of usage
m-gpux billing usage --account dev     # Target specific accounts
m-gpux billing usage --all             # Aggregate cross-account usage

🛑 Stop Processes

Clean up your workspace quickly.

m-gpux stop          # Stop apps on the current profile
m-gpux stop --all    # Stop apps across ALL profiles

---

📚 Documentation

Dive deeper into our extensive guides:

• 🌐 Website: puxhocdl.github.io/m-gpux
• 🏠 Local Index: docs/index.md
• 🚀 Getting Started: docs/getting-started.md
• 🧰 Commands Reference: docs/commands.md
• ❓ FAQ: docs/faq.md

---

🏗️ Architecture

Under the hood, m-gpux is built for modularity:

Component	Responsibility
m_gpux/main.py	CLI entrypoint and command registration
m_gpux/commands/account.py	Profile CRUD operations and switching
m_gpux/commands/billing.py	Usage aggregation and dashboard linking
m_gpux/commands/hub.py	Guided GPU runtime execution launcher
m_gpux/commands/serve.py	LLM API deployment, proxy, and auth management
m_gpux/commands/load.py	Live hardware metrics probe

---

🔧 Troubleshooting

Have issues? Here's how to fix common hiccups:

• No configured Modal profiles found
  • Fix: Run m-gpux account add to set one up.
• modal: command not found
  • Fix: Make sure the Modal CLI is installed and your PATH is set correctly.
• Script file does not exist in hub mode
  • Fix: Ensure you run the command from the script's directory, or double-check the path you provided.

---

🤝 Contributing

We welcome your PRs! Help us polish the UX, refine commands, and expand the documentation.

Local Setup:

pip install -e .
python -m m_gpux.main --help

📦 PyPI Publishing

Automated with GitHub Actions. Maintainers can release instantly:

1. Ensure the PyPI Trusted Publisher is configured (pypi environment, PuxHocDL/m-gpux).
2. Update the version inside pyproject.toml.
3. Tag the release:

git tag v1.0.8 && git push origin v1.0.8

The Publish Python Package workflow will build and upload.

---

Available under the MIT License.