clients/python/README.md

matrixcloud — Python client & CLI

Official Python SDK and command-line interface for Matrix Cloud / Matrix Runtime. Talk to the /v1 API: authenticate, run jobs, inspect models, and drive MCP sandboxes.

Install (with uv — fast)

cd clients/python
uv sync --extra dev      # creates .venv and installs the package + dev tools
uv run mxc status        # or: source .venv/bin/activate && mxc status

From the repo root you can also run make venv (uv) and make py-test.

Plain pip works too:

python -m venv .venv && . .venv/bin/activate
pip install -e '.[dev]'

CLI

mxc signup                       # create a workspace + owner
mxc login                        # sign in (token stored in ~/.config/matrixcloud)
mxc status                       # runtime health + capabilities
mxc jobs                         # list jobs
mxc inspect hf:Qwen/Qwen2.5-7B-Instruct
mxc sandbox start mcp_server:filesystem \
    --cmd 'npx -y @modelcontextprotocol/server-filesystem /tmp'
mxc sandbox tools <session_id>
mxc sandbox call  <session_id> list_directory --args '{"path":"/tmp"}'
mxc sandbox stop  <session_id>

Point at a remote runtime with --url or MATRIXCLOUD_URL; use MATRIXCLOUD_TOKEN to pass a session token in CI.

Library

from matrixcloud import MatrixCloud

with MatrixCloud("http://localhost:8080") as mc:
    mc.login("you@acme.io", "secret123")
    print(mc.capabilities()["capabilities"])
    meta = mc.inspect_model("hf:Qwen/Qwen2.5-7B-Instruct")
    print(meta["recommended_runtime"], meta["estimated_parameters"])

    s = mc.create_sandbox("mcp_server:filesystem",
                          "npx -y @modelcontextprotocol/server-filesystem /tmp")
    for ev in mc.stream_sandbox_events(s["session_id"]):
        print(ev["step"], ev["message"])
        if ev["step"] == "ready":
            break
    print([t["name"] for t in mc.sandbox_tools(s["session_id"])])
    mc.delete_sandbox(s["session_id"])

Licensed under Apache-2.0.