Chutes

# Chutes!

This package provides the command line interface and development kit for use with the chutes.ai platform.

The miner code is available [here](https://github.com/rayonlabs/chutes-miner), and validator/API code [here](https://github.com/rayonlabs/chutes-api).

## 📚 Glossary

Before getting into the weeds, it might be useful to understand the terminology.

### 🐳 image

Images are simply docker images that all chutes (applications) will run on within the platform.

Images must meet a few requirements:
- Contain a cuda installation, preferably version 12.2-12.6
- Contain clinfo, opencl dev libraries, clblast, openmi, etc.
- Contain a python 3.10+ installation, where `python` and `pip` are contained within the executable path `PATH`

__*We HIGHLY, HIGHLY recommend you start with our base image: parachutes/python:3.12 to avoid dependency hell*__

### 🪂 chute

A chute is essentially an application that runs on top of an image, within the platform.  Think of a chute as a single FastAPI application.

### λ cord

A cord is a single function within the chute.  In the FastAPI analogy, this would be a single route & method.

### ✅ graval

GraVal is the graphics card validation library used to help ensure the GPUs that miners claim to be running are authentic/correct.
The library performs VRAM capacity checks, matrix multiplications seeded by device information, etc.

You don't really need to know anything about graval, except that it runs as middleware within the chute to decrypt traffic from the validator and perform additional validation steps (filesystem checks, device info challenges, pings, etc.)

## 🔐 Register

Currently, to become a user on the chutes platform, you must have a Bittensor wallet and hotkey, as authentication is performed via Bittensor hotkey signatures.
Once you are registered, you can create API keys that can be used with a simple "Authorization" header in your requests.

If you don't already have a wallet, you can create one by installing `bittensor<8`, e.g. `pip install 'bittensor<8'`  _note: you can use the newer bittensor-wallet package but it requires rust, which is absurd_

Then, create a coldkey and hotkey according to the library you installed, e.g.:
```bash
btcli wallet new_coldkey --n_words 24 --wallet.name chutes-user
btcli wallet new_hotkey --wallet.name chutes-user --n_words 24 --wallet.hotkey chutes-user-hotkey
```

Once you have your hotkey, just run:
```bash
chutes register
```

*__Don't override CHUTES_API_URL unless you are developing chutes, you can just stop here!__*

To use a development environment, simply set the `CHUTES_API_URL` environment variable accordingly to whatever your dev environment endpoint is, e.g.:
```bash
CHUTES_API_URL=https://api.chutes.dev chutes register
```

Once you've completed the registration process, you'll have a file in `~/.chutes/config.ini` which contains the configuration for using chutes.

## 🔑 Create API keys

You can create API keys, optionally limiting the scope of each key, with the `chutes keys` subcommand, e.g.:

Full admin access:
```bash
chutes keys create --name admin-key --admin
```

Access to images:
```bash
chutes keys create --name image-key --images
```

Access to a single chute.
```bash
chutes keys create --name foo-key --chute-ids 5eda1993-9f4b-5426-972c-61c33dbaf541
```

## 👨‍💻 Developer deposit

*_As of 2025-10-02, this is no longer required! You must have >= $50 balance to build images, and there is a deployment fee (also mentioned in this doc) to deploy chutes_*

### Return the developer deposit

To get your deposit back, perform a POST to the `/return_developer_deposit` endpoint, e.g.:
```bash
curl -XPOST https://api.chutes.ai/return_developer_deposit \
  -H 'content-type: application/json' \
  -H 'authorization: cpk_...' \
  -d '{"address": "5EcZsewZSTxUaX8gwyHzkKsqT3NwLP1n2faZPyjttCeaPdYe"}'
```

## 🛠️ Building an image

The first step in getting an application onto the chutes platform is to build an image.
This SDK includes an image creation helper library as well, and we have a recommended base image which includes python 3.12 and all necessary cuda packages: `parachutes/python:3.12`

Here is an entire chutes application, which has an image that includes `vllm` -- let's store it in `llama1b.py`:

```python
from chutes.chute import NodeSelector
from chutes.chute.template.vllm import build_vllm_chute
from chutes.image import Image

image = (
    Image(username="chutes", name="vllm", tag="0.6.3", readme="## vLLM - fast, flexible llm inference")
    .from_base("parachutes/python:3.12")
    .run_command("pip install 'vllm<0.6.4' wheel packaging")
    .run_command("pip install flash-attn")
    .run_command("pip uninstall -y xformers")
)

chute = build_vllm_chute(
    username="chutes",
    readme="## Meta Llama 3.2 1B Instruct\n### Hello.",
    model_name="unsloth/Llama-3.2-1B-Instruct",
    image=image,
    node_selector=NodeSelector(
        gpu_count=1,
    ),
)
```

The `chutes.image.Image` class includes many helper directives for environment variables, adding files, installing python from source, etc.

To build this image, you can use the chutes CLI:
```bash
chutes build llama1b:chute --public --wait --debug
```

Explanation of the flags:
- `--public` means we want this image to be public/available for ANY user to use -- use with care but we do like public/open source things!
- `--wait` means we want to stream the docker build logs back to the command line.  All image builds occur remotely on our platform, so without the `--wait` flag you just have to wait for the image to become available, whereas with this flag you can see real-time logs/status.
- `--debug` additional debug logging

## 🚀 Deploying a chute

Once you have an image that is built and pushed and ready for use (see above), you can deploy applications on top of those.

To use the same example `llama1b.py` file outlined in the image building section above, we can deploy the llama-3.2-1b-instruct model with:
```bash
chut