SubstrateCloud SDK & CLI

A typed, composable Python SDK and command-line interface for the SubstrateCloud On-Demand GPU platform. Find GPU capacity, launch instances, run Docker or boot-script workloads, and tear everything down — from one tool.

Requirements

• Python 3.10+ (3.10, 3.11, 3.12, and 3.13 are supported).
• On Debian/Ubuntu, the standard-library venv module: sudo apt install -y python3-venv.
• A SubstrateCloud MCP token — create one in the console under Resources → MCP Keys. Tokens start with mcp_ and are org-scoped (max 3 active tokens per org — see Cost Safety).
• Your org's API base URL — https://io.substrate.ai/functions/v1/ondemand-mcp-manager.

If you haven't set up your account and wallet yet, start with Getting Started and On-Demand MCP.

Install

One-liner (recommended, once the repo is public)

Installs an isolated virtual environment — no system pip, no git, no pipx required:

curl -fsSL https://raw.githubusercontent.com/substrate-cloud/probable-dollop/main/scripts/install-cli.sh | bash

This creates a venv at ~/.local/share/substratecloud/venv and places a substratecloud launcher in ~/.local/bin. If that directory isn't on your PATH, add it:

export PATH="$HOME/.local/bin:$PATH"   # add to ~/.bashrc or ~/.zshrc

The installer honors a few environment variables:

Variable	Purpose	Default
SUBSTRATECLOUD_SDK_REPO	Source repo (owner/name)	substrate-cloud/probable-dollop
SUBSTRATECLOUD_SDK_BRANCH	Branch to install	main
SUBSTRATECLOUD_HOME	Install root	$XDG_DATA_HOME/substratecloud

With pip (no curl)

The package installs from a GitHub archive, so you can do the same thing pip-side. Use a virtual environment (or pipx) on PEP 668 systems:

python3 -m venv .venv && source .venv/bin/activate
pip install "substratecloud[cli] @ https://github.com/substrate-cloud/probable-dollop/archive/refs/heads/main.zip"

Drop the [cli] extra if you only need the Python SDK and not the substratecloud command.

From source (development)

This is the method that works today while the repo is private — the git clone uses your authenticated GitHub credentials (it requires read access to substrate-cloud/probable-dollop):

git clone https://github.com/substrate-cloud/probable-dollop substrate-sdk
cd substrate-sdk
uv venv && source .venv/bin/activate
uv pip install -e ".[dev,cli]"

Verify

substratecloud --version
substratecloud --help

60-second quickstart

substratecloud config init                      # enter your MCP token + API base URL
substratecloud inventory cheapest --gpu a100    # find capacity
substratecloud instance launch --gpu a100 --name exp-1
substratecloud instance ls
substratecloud instance terminate exp-1         # stop billing when done

The equivalent in Python:

from substratecloud import SubstrateCloud

with SubstrateCloud() as client:                 # token/base_url from env or config
    item = client.inventory.find_cheapest(gpu_type="A100")
    inst = client.instances.create(inventory_gpu_id=item.id, name="exp-1")
    client.instances.wait_until_active(inst.id, timeout=600)
    # ... use the instance via inst.ip_address ...
    client.instances.delete(inst.id)             # stop billing

Where to next

• Authentication & Config — tokens, profiles, env vars.
• CLI Reference — every command and flag.
• SDK Usage — the Python client, workloads, secrets, manifests.
• Cost Safety & Troubleshooting — billing model and errors.