modelmux-cli 0.1.0__tar.gz

modelmux_cli-0.1.0/.gitignore

@@ -0,0 +1,29 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+build/
+dist/
+
+# Tooling
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# Local config and secrets
+.env
+.env.*
+!.env.example
+*.env
+secrets/
+*.pem
+*.key
+
+# Editors / OS
+.vscode/
+.idea/
+.DS_Store

modelmux_cli-0.1.0/PKG-INFO

@@ -0,0 +1,40 @@
+Metadata-Version: 2.5
+Name: modelmux-cli
+Version: 0.1.0
+Summary: Set up, log in to and run ModelMux: AI coding CLIs as an OpenAI-compatible API
+Project-URL: Homepage, https://github.com/smit153/modelmux
+Project-URL: Source, https://github.com/smit153/modelmux
+Project-URL: Issues, https://github.com/smit153/modelmux/issues
+License-Expression: Apache-2.0
+Classifier: Environment :: Console
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# modelmux-cli
+
+Set up, log in to and run [ModelMux](https://github.com/smit153/modelmux):
+AI coding CLIs (Claude Code, Codex) as a secure, OpenAI-compatible API on your
+own machine.
+
+```bash
+pipx install modelmux-cli      # or: uvx --from modelmux-cli modelmux
+modelmux up                    # set up Docker containers, start logged-in providers
+modelmux login claude          # guided login (opens your browser), then a real test
+modelmux config litellm        # ready-to-paste config for LiteLLM, OpenAI SDK, LangChain...
+```
+
+Other commands: `status`, `logs`, `doctor`, `upgrade`, `logout`, `key show`, `down`.
+
+- Requires Docker with Compose v2 (Docker Desktop on macOS and Windows) and
+  Python 3.10+. No other dependencies.
+- Each CLI release runs the server image built in the same release, pinned by
+  digest.
+- Logins live in per-provider Docker volumes; the API key is generated
+  locally and stored with owner-only permissions.
+
+Full documentation: <https://github.com/smit153/modelmux/blob/main/docs/CLI.md>

modelmux_cli-0.1.0/README.md

@@ -0,0 +1,23 @@
+# modelmux-cli
+
+Set up, log in to and run [ModelMux](https://github.com/smit153/modelmux):
+AI coding CLIs (Claude Code, Codex) as a secure, OpenAI-compatible API on your
+own machine.
+
+```bash
+pipx install modelmux-cli      # or: uvx --from modelmux-cli modelmux
+modelmux up                    # set up Docker containers, start logged-in providers
+modelmux login claude          # guided login (opens your browser), then a real test
+modelmux config litellm        # ready-to-paste config for LiteLLM, OpenAI SDK, LangChain...
+```
+
+Other commands: `status`, `logs`, `doctor`, `upgrade`, `logout`, `key show`, `down`.
+
+- Requires Docker with Compose v2 (Docker Desktop on macOS and Windows) and
+  Python 3.10+. No other dependencies.
+- Each CLI release runs the server image built in the same release, pinned by
+  digest.
+- Logins live in per-provider Docker volumes; the API key is generated
+  locally and stored with owner-only permissions.
+
+Full documentation: <https://github.com/smit153/modelmux/blob/main/docs/CLI.md>

modelmux_cli-0.1.0/hatch_build.py

@@ -0,0 +1,33 @@
+"""Bundle the repository's language-neutral /shared data into the package.
+
+From the repository, the data is at ../../shared. Inside a source
+distribution it was copied to ./shared, so wheels built from the sdist (as
+pip and uv do) still get it.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+
+PARTS = ("providers", "schema", "templates")
+FILES = ("release.json",)
+
+
+class SharedDataHook(BuildHookInterface):  # type: ignore[type-arg]
+    PLUGIN_NAME = "custom"
+
+    def initialize(self, version: str, build_data: dict[str, Any]) -> None:
+        root = Path(self.root)
+        for candidate in (root.parent.parent / "shared", root / "shared"):
+            if all((candidate / part).is_dir() for part in PARTS) and all(
+                (candidate / name).is_file() for name in FILES
+            ):
+                break
+        else:
+            raise RuntimeError("modelmux shared data (providers, schema) not found")
+        prefix = "modelmux_cli/_shared" if self.target_name == "wheel" else "shared"
+        for part in (*PARTS, *FILES):
+            build_data["force_include"][str(candidate / part)] = f"{prefix}/{part}"

modelmux_cli-0.1.0/pyproject.toml

@@ -0,0 +1,88 @@
+[project]
+name = "modelmux-cli"
+version = "0.1.0"
+description = "Set up, log in to and run ModelMux: AI coding CLIs as an OpenAI-compatible API"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.10"
+# Deliberately no runtime dependencies: this tool drives Docker on the user's
+# machine, so it stays small and easy to audit.
+dependencies = []
+classifiers = [
+    "Environment :: Console",
+    "Operating System :: MacOS",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development",
+]
+
+[project.urls]
+Homepage = "https://github.com/smit153/modelmux"
+Source = "https://github.com/smit153/modelmux"
+Issues = "https://github.com/smit153/modelmux/issues"
+
+[project.scripts]
+modelmux = "modelmux_cli.main:main"
+
+[dependency-groups]
+dev = [
+    "ruff>=0.6",
+    "mypy>=1.11",
+    "pytest>=8.3",
+    "pytest-cov>=5.0",
+    "jsonschema>=4.23",
+    "types-jsonschema>=4.23",
+]
+
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/modelmux_cli"]
+
+# The language-neutral data in /shared is bundled by hatch_build.py, both
+# from the repository and when a wheel is built from the sdist.
+[tool.hatch.build.hooks.custom]
+path = "hatch_build.py"
+
+# ---------------------------------------------------------------- ruff
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = [
+    "E", "W", "F", "I", "B", "UP", "S", "N", "SIM", "RUF", "PL", "TID", "PT", "C4", "RET",
+]
+ignore = ["PLR0913", "PLR2004"]
+
+[tool.ruff.lint.pylint]
+max-returns = 10
+
+[tool.ruff.lint.flake8-tidy-imports.banned-api]
+"subprocess".msg = "Run commands only via modelmux_cli.docker."
+"os.system".msg = "No shells. Run commands only via modelmux_cli.docker."
+"os.popen".msg = "No shells. Run commands only via modelmux_cli.docker."
+"pty".msg = "Run commands only via modelmux_cli.docker."
+
+[tool.ruff.lint.per-file-ignores]
+"src/modelmux_cli/docker.py" = ["TID251", "S603", "S606"]
+"tests/**" = ["S101", "S105", "S106", "S108", "TID251", "S603", "S607", "PLR0917"]
+
+# ---------------------------------------------------------------- mypy
+[tool.mypy]
+python_version = "3.10"
+strict = true
+files = ["src"]
+
+# ---------------------------------------------------------------- pytest
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra --strict-markers"
+
+[tool.coverage.run]
+source = ["modelmux_cli"]
+branch = true

modelmux_cli-0.1.0/shared/providers/claude.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "../schema/provider.schema.json",
+  "schema_version": 1,
+  "name": "claude",
+  "display_name": "Claude Code",
+  "driver": "claude",
+  "default_port": 8101,
+  "volume": "claude-home",
+  "home": "/home/modelmux/driver-home",
+  "example_model": "sonnet",
+  "login": {
+    "default_method": "browser",
+    "methods": {
+      "browser": {
+        "description": "Claude subscription: open a link, sign in, paste the code back",
+        "command": ["claude", "auth", "login"]
+      },
+      "console": {
+        "description": "Anthropic Console (API billing): open a link, sign in, paste the code back",
+        "command": ["claude", "auth", "login", "--console"]
+      }
+    },
+    "link_pattern": "https://\\S+",
+    "timeout_seconds": 600
+  },
+  "status": {
+    "command": ["claude", "auth", "status"],
+    "logged_in_exit_code": 0
+  },
+  "logout": {
+    "command": ["claude", "auth", "logout"]
+  },
+  "docs_url": "https://docs.anthropic.com/en/docs/claude-code"
+}

modelmux_cli-0.1.0/shared/providers/codex.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "../schema/provider.schema.json",
+  "schema_version": 1,
+  "name": "codex",
+  "display_name": "OpenAI Codex",
+  "driver": "codex",
+  "default_port": 8102,
+  "volume": "codex-home",
+  "home": "/home/modelmux/driver-home",
+  "example_model": "gpt-6.1-sol",
+  "login": {
+    "default_method": "device",
+    "methods": {
+      "device": {
+        "description": "ChatGPT account: open a link and enter the one-time code shown",
+        "command": ["codex", "login", "--device-auth"]
+      },
+      "api-key": {
+        "description": "OpenAI API key, read from your terminal without echo",
+        "command": ["codex", "login", "--with-api-key"],
+        "secret_stdin": "OpenAI API key"
+      }
+    },
+    "link_pattern": "https://\\S+",
+    "timeout_seconds": 900
+  },
+  "status": {
+    "command": ["codex", "login", "status"],
+    "logged_in_exit_code": 0
+  },
+  "logout": {
+    "command": ["codex", "logout"]
+  },
+  "docs_url": "https://developers.openai.com/codex/cli"
+}

modelmux_cli-0.1.0/shared/release.json

@@ -0,0 +1,4 @@
+{
+  "version": "0.1.0",
+  "image": "ghcr.io/smit153/modelmux@sha256:1edfd02f98bf739c874fa0db043bdbd46d907ac41d2bc30fb7f5b8b311381b72"
+}

modelmux_cli-0.1.0/shared/schema/provider.schema.json

@@ -0,0 +1,81 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/smit153/modelmux/shared/schema/provider.schema.json",
+  "title": "ModelMux provider definition",
+  "description": "How the ModelMux CLI runs, logs in and checks one provider. Language-neutral: every CLI implementation reads these files.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version", "name", "display_name", "driver", "default_port", "volume", "home",
+    "example_model", "login", "status", "logout"
+  ],
+  "properties": {
+    "$schema": {"type": "string"},
+    "schema_version": {"const": 1},
+    "name": {"$ref": "#/$defs/identifier", "description": "Used on the command line: modelmux login <name>"},
+    "display_name": {"type": "string", "minLength": 1, "maxLength": 64},
+    "driver": {"$ref": "#/$defs/identifier", "description": "The server's MODELMUX_DRIVER value"},
+    "default_port": {"type": "integer", "minimum": 1024, "maximum": 65535},
+    "volume": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9_.-]{0,62}$",
+      "description": "Login volume name, unique per provider (prefixed with the compose project name)"
+    },
+    "home": {"type": "string", "pattern": "^/", "description": "HOME inside the container; the volume is mounted here"},
+    "example_model": {"type": "string", "minLength": 1, "maxLength": 64},
+    "login": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["default_method", "methods", "link_pattern", "timeout_seconds"],
+      "properties": {
+        "default_method": {"$ref": "#/$defs/identifier"},
+        "methods": {
+          "type": "object",
+          "minProperties": 1,
+          "propertyNames": {"$ref": "#/$defs/identifier"},
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["description", "command"],
+            "properties": {
+              "description": {"type": "string", "minLength": 1},
+              "command": {"$ref": "#/$defs/command"},
+              "secret_stdin": {
+                "type": "string",
+                "minLength": 1,
+                "description": "If set, prompt for this secret without echo and pass it on stdin"
+              }
+            }
+          }
+        },
+        "link_pattern": {"type": "string", "minLength": 1, "description": "Regex that finds the login link in the CLI's output"},
+        "timeout_seconds": {"type": "integer", "minimum": 30, "maximum": 3600}
+      }
+    },
+    "status": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["command", "logged_in_exit_code"],
+      "properties": {
+        "command": {"$ref": "#/$defs/command"},
+        "logged_in_exit_code": {"type": "integer"}
+      }
+    },
+    "logout": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["command"],
+      "properties": {"command": {"$ref": "#/$defs/command"}}
+    },
+    "docs_url": {"type": "string", "pattern": "^https://"}
+  },
+  "$defs": {
+    "identifier": {"type": "string", "pattern": "^[a-z][a-z0-9-]{0,31}$"},
+    "command": {
+      "type": "array",
+      "minItems": 1,
+      "description": "argv run inside a helper container; the first item is the entrypoint. Never a shell string.",
+      "items": {"type": "string", "pattern": "^[A-Za-z0-9._=/-]+$"}
+    }
+  }
+}

modelmux_cli-0.1.0/shared/templates/compose-service.json

@@ -0,0 +1,12 @@
+{
+  "read_only": true,
+  "tmpfs": ["/tmp:rw,noexec,nosuid,nodev,size=512m"],
+  "cap_drop": ["ALL"],
+  "security_opt": ["no-new-privileges:true"],
+  "user": "10001:10001",
+  "pids_limit": 256,
+  "mem_limit": "2g",
+  "cpus": 2,
+  "restart": "on-failure:3",
+  "labels": {"io.modelmux.managed": "true"}
+}

modelmux_cli-0.1.0/shared/templates/config/curl.json

@@ -0,0 +1,8 @@
+{
+  "description": "curl request",
+  "per": "provider",
+  "key_style": "shell",
+  "header": "",
+  "entry": "# {{display_name}}\ncurl {{base_url}}/chat/completions \\\n  -H \"Authorization: Bearer {{key}}\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\": \"{{model}}\", \"messages\": [{\"role\": \"user\", \"content\": \"Hello!\"}]}'\n\n",
+  "footer": ""
+}

modelmux_cli-0.1.0/shared/templates/config/env.json

@@ -0,0 +1,8 @@
+{
+  "description": "Environment variables (.env)",
+  "per": "provider",
+  "key_style": "env",
+  "header": "MODELMUX_API_KEY={{key}}\n",
+  "entry": "MODELMUX_{{PROVIDER}}_BASE_URL={{base_url}}\nMODELMUX_{{PROVIDER}}_MODEL={{model}}\n",
+  "footer": ""
+}

modelmux_cli-0.1.0/shared/templates/config/langchain.json

@@ -0,0 +1,8 @@
+{
+  "description": "LangChain ChatOpenAI",
+  "per": "provider",
+  "key_style": "python",
+  "header": "import os\n\nfrom langchain_openai import ChatOpenAI\n",
+  "entry": "\n# {{display_name}}\n{{provider_var}} = ChatOpenAI(\n    model=\"{{model}}\",\n    base_url=\"{{base_url}}\",\n    api_key={{key}},\n    use_responses_api=False,  # ModelMux implements Chat Completions\n)\nprint({{provider_var}}.invoke(\"Hello!\").content)\n",
+  "footer": ""
+}

modelmux_cli-0.1.0/shared/templates/config/litellm.json

@@ -0,0 +1,8 @@
+{
+  "description": "LiteLLM proxy config.yaml (model_list)",
+  "per": "model",
+  "key_style": "litellm",
+  "header": "model_list:\n",
+  "entry": "  - model_name: {{provider}}-{{model}}\n    litellm_params:\n      model: openai/{{model}}\n      api_base: {{base_url}}\n      api_key: {{key}}\n",
+  "footer": ""
+}

modelmux_cli-0.1.0/shared/templates/config/openai-python.json

@@ -0,0 +1,8 @@
+{
+  "description": "OpenAI Python SDK",
+  "per": "provider",
+  "key_style": "python",
+  "header": "import os\n\nfrom openai import OpenAI\n",
+  "entry": "\n# {{display_name}}\n{{provider_var}} = OpenAI(base_url=\"{{base_url}}\", api_key={{key}})\nreply = {{provider_var}}.chat.completions.create(\n    model=\"{{model}}\",\n    messages=[{\"role\": \"user\", \"content\": \"Hello!\"}],\n)\nprint(reply.choices[0].message.content)\n",
+  "footer": ""
+}

modelmux_cli-0.1.0/src/modelmux_cli/__init__.py

@@ -0,0 +1,8 @@
+"""modelmux-cli: set up, log in to and run ModelMux."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("modelmux-cli")
+except PackageNotFoundError:  # pragma: no cover - running from a source tree
+    __version__ = "0.0.0"

modelmux_cli-0.1.0/src/modelmux_cli/__main__.py

@@ -0,0 +1,7 @@
+"""``python -m modelmux_cli``."""
+
+import sys
+
+from modelmux_cli.main import main
+
+sys.exit(main())

modelmux_cli-0.1.0/src/modelmux_cli/clientconfig.py

@@ -0,0 +1,87 @@
+"""Render client config snippets from ``shared/templates/config/<target>.json``."""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from typing import Any
+
+from modelmux_cli.errors import CliError
+from modelmux_cli.providers import shared_dir
+
+KEY_ENV = "MODELMUX_API_KEY"
+TARGETS = ("litellm", "openai-python", "langchain", "curl", "env")
+
+# How each target refers to the key: (by reference, when revealed).
+_KEY_STYLES: dict[str, tuple[str, Any]] = {
+    "litellm": (f"os.environ/{KEY_ENV}", lambda key: key),
+    "python": (f'os.environ["{KEY_ENV}"]', json.dumps),
+    "shell": (f"${KEY_ENV}", lambda key: key),
+    "env": ("", lambda key: key),
+}
+_PLACEHOLDER = re.compile(r"\{\{(\w+)\}\}")
+
+
+@dataclass(frozen=True)
+class Template:
+    name: str
+    description: str
+    per: str
+    key_style: str
+    header: str
+    entry: str
+    footer: str
+
+
+@dataclass(frozen=True)
+class Target:
+    provider: str
+    display_name: str
+    base_url: str
+    models: tuple[str, ...]
+
+
+def load_template(name: str) -> Template:
+    path = shared_dir() / "templates" / "config" / f"{name}.json"
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+        template = Template(name=name, **{k: data[k] for k in (
+            "description", "per", "key_style", "header", "entry", "footer")})  # fmt: skip
+    except (OSError, ValueError, KeyError, TypeError):
+        raise CliError(f"The {name!r} config template is missing or invalid.",
+                       hint="Please report this bug.") from None  # fmt: skip
+    if template.per not in {"provider", "model"} or template.key_style not in _KEY_STYLES:
+        raise CliError(f"The {name!r} config template is invalid.", hint="Please report this bug.")
+    return template
+
+
+def _fill(text: str, values: dict[str, str]) -> str:
+    def replace(match: re.Match[str]) -> str:
+        if match.group(1) not in values:
+            raise CliError(f"Unknown placeholder {match.group(0)} in a config template.",
+                           hint="Please report this bug.")  # fmt: skip
+        return values[match.group(1)]
+
+    return _PLACEHOLDER.sub(replace, text)
+
+
+def render(template: Template, targets: list[Target], api_key: str | None) -> str:
+    """``api_key`` None means: refer to $MODELMUX_API_KEY instead of the value."""
+    reference, literal = _KEY_STYLES[template.key_style]
+    key = reference if api_key is None else literal(api_key)
+    parts = [_fill(template.header, {"key": key})]
+    for target in targets:
+        models = target.models if template.per == "model" else target.models[:1]
+        for model in models:
+            parts.append(_fill(template.entry, {
+                "provider": target.provider,
+                "PROVIDER": target.provider.upper().replace("-", "_"),
+                "provider_var": target.provider.replace("-", "_"),
+                "display_name": target.display_name,
+                "model": model,
+                "base_url": target.base_url,
+                "key": key,
+            }))  # fmt: skip
+    parts.append(_fill(template.footer, {"key": key}))
+    return "".join(parts).rstrip("\n") + "\n"

modelmux_cli-0.1.0/src/modelmux_cli/commands/__init__.py

@@ -0,0 +1 @@
+"""One module per command. Each exposes ``run(args, console) -> exit code``."""

modelmux_cli-0.1.0/src/modelmux_cli/commands/basic.py

@@ -0,0 +1,75 @@
+"""``modelmux down``, ``logs`` and ``status``."""
+
+from __future__ import annotations
+
+import argparse
+
+from modelmux_cli import health
+from modelmux_cli.console import Console
+from modelmux_cli.context import make_context
+from modelmux_cli.errors import CliError
+from modelmux_cli.stack import resolve_image, service_name
+
+NOT_SET_UP = "ModelMux is not set up on this machine yet."
+
+
+def down(args: argparse.Namespace, console: Console) -> int:
+    ctx = make_context(console)
+    if not ctx.stack.compose_file.exists():
+        console.success("ModelMux is not running.")
+        return 0
+    ctx.stack.compose("down", timeout=120)
+    console.success("Stopped ModelMux. Your logins are kept.")
+    return 0
+
+
+def logs(args: argparse.Namespace, console: Console) -> int:
+    ctx = make_context(console)
+    stack = ctx.stack
+    if not stack.compose_file.exists():
+        raise CliError(NOT_SET_UP, hint="Start it with: modelmux up")
+    services = [service_name(ctx.providers[args.provider])] if args.provider else []
+    follow = ["--follow"] if args.follow else []
+    return ctx.docker.passthrough(
+        "compose", "-p", "modelmux", "-f", str(stack.compose_file),
+        "logs", "--no-log-prefix" if args.provider else "--timestamps",
+        "--tail", str(max(args.tail, 0)), *follow, *services,
+    )  # fmt: skip
+
+
+def status(args: argparse.Namespace, console: Console) -> int:
+    ctx = make_context(console)
+    ctx.docker.check_available()
+    stack = ctx.stack
+    states = stack.states()
+    try:
+        image: str | None = resolve_image(ctx.config)
+    except CliError:
+        image = None
+
+    rows = [("PROVIDER", "CONTAINER", "LOGIN", "HEALTH", "URL")]
+    for name, provider in sorted(ctx.providers.items()):
+        state = states.get(service_name(provider))
+        port = ctx.config.port(name)
+        container = state.state if state else "not started"
+        login = "?" if image is None else ("yes" if stack.logged_in(provider, image) else "no")
+        if state and state.state == "running":
+            healthy = "ready" if health.ready(port) else "starting"
+        else:
+            healthy = "-"
+        url = f"{health.base_url(port)}/v1" if healthy == "ready" else "-"
+        rows.append((name, container, login, healthy, url))
+
+    widths = [max(len(row[i]) for row in rows) for i in range(len(rows[0]))]
+    for row in rows:
+        console.print("  ".join(cell.ljust(widths[i]) for i, cell in enumerate(row)).rstrip())
+
+    if image is None:
+        console.step("No server image chosen yet: run 'modelmux up' first.")
+    for name, provider in sorted(ctx.providers.items()):
+        state = states.get(service_name(provider))
+        if state and state.state in {"exited", "dead"}:
+            console.step(
+                f"{provider.display_name} has stopped. If its login expired: modelmux login {name}"
+            )
+    return 0