Metadata-Version: 2.4
Name: matmul-cloud
Version: 0.1.0
Summary: MatMul CLI and Python SDK: rent GPUs and run jobs on the cheapest live capacity across neoclouds
Author: MatMul
License-Expression: Apache-2.0
Project-URL: Homepage, https://matmul.cloud
Project-URL: Documentation, https://matmul.cloud/docs
Project-URL: Get an API key, https://app.matmul.cloud/app/cli
Project-URL: Guide, https://matmul.cloud/blog/rent-a-cloud-gpu-in-5-minutes
Keywords: gpu,cloud,neocloud,cli,sdk,machine-learning,h100,compute
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: System :: Distributed Computing
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# matmul-cloud

The command line tool and Python SDK for [MatMul](https://matmul.cloud). Rent a GPU from the
cheapest live offer across the neoclouds, run your container image on it, SSH in, and stop
paying when you're done. One account, one prepaid balance.

The package is called `matmul-cloud` on PyPI. It installs the `matmul` command, and you import it
as `matmul`. It uses only the Python standard library, so it installs in seconds and won't
conflict with anything in your environment. Python 3.9 or newer.

## Install

```bash
pip install matmul-cloud        # or: pipx install matmul-cloud
matmul --version
```

## Log in

Create an API key on the **CLI & API** page of the console:
<https://app.matmul.cloud/app/cli>. The key is shown once, with a ready-made login command:

```bash
matmul login --api-key lmk_... --url https://api.matmul.cloud
```

That saves the key to `~/.config/matmul/config.json`, readable only by you. In CI, set
`MATMUL_API_KEY` in the environment instead. `MATMUL_API_URL` overrides the API base URL.

## Rent a GPU from the command line

```bash
matmul ssh-key add                        # registers ~/.ssh/id_ed25519.pub (or --file)
matmul offers --gpu H100                  # live offers, cheapest first
matmul instance create --name dev --gpu H100 --max-price 3 --wait
matmul ssh dev -- nvidia-smi
matmul instance rm dev                    # releases the machine; billing stops
```

`--max-price` is a hard ceiling in dollars per hour: if the live price has moved above it,
nothing is launched and nothing is charged. Run `matmul --help`, or `matmul <command> --help`,
for every command and flag.

## Use it from Python

```python
import matmul

client = matmul.Client()  # MATMUL_API_KEY, or the key saved by `matmul login`

offers = client.offers(gpu="H100", max_price_cents=300)
offer = offers[0]
key = client.ssh_keys()[0]

inst = client.create_instance(
    offer.id, "sdk-demo", image=None, ssh_key_id=key.id,  # image=None: a plain VM
    max_hourly_price_cents=300,
)
try:
    inst = client.wait_instance(inst.id)
    print("ssh:", inst.ssh_command)
finally:
    client.delete_instance(inst.id)  # always stop billing
```

Failures raise `matmul.MatMulError`, with `.status` (the HTTP status) and `.message`.

## Links

- Documentation: <https://matmul.cloud/docs>
- Step-by-step guide: [Rent a cloud GPU in 5 minutes](https://matmul.cloud/blog/rent-a-cloud-gpu-in-5-minutes)
- Use MatMul from Claude, Cursor or any MCP client: [`matmul-mcp`](https://pypi.org/project/matmul-mcp/)

## Changelog

### 0.1.0

First release on PyPI.

- GPU instances: `offers`, `ssh-key add/ls/rm`, `instance create/ls/get/rm`, `ssh`, and public HTTPS
  links for ports (`expose`, `unexpose`, `ports`).
- Prepaid billing: `billing balance`, `billing ledger`, `billing add-credit`.
- Managed jobs (preview): `run` with `--gpu`, `--max-price` and `--wait`, plus `ls`, `status`,
  `logs` and `down`.
- `matmul --version`.
