inferhive (SDK + CLI)

Python SDK and command line for InferHive, the collaborative GPU lending and LLM inference platform by Impulsate: rent or reserve GPUs, run batch jobs (with a queue when every GPU is busy), move files to and from the cloud, and call an OpenAI-compatible LLM gateway. Everything is paid in processing coins (PC), the platform's credits.

• Commands: inferhive (and pcoin, kept as an alias).
• Python import package: pcoin.
• Requires Python 3.12+. The portal lives at https://inferhive.impulsate.lat.

Install

pip install inferhive            # SDK + CLI
pip install 'inferhive[openai]'  # plus the OpenAI client for the LLM gateway
pip install 'inferhive[worker]'  # plus llama-cpp-python, to lend your own device as a worker

Log in

inferhive login              # opens the portal in your browser; type the code shown here
inferhive balance

inferhive login asks the portal for an API key: you approve it in the browser with your usual portal session, typing the code the terminal prints. The key is stored in ~/.config/pcoin/platform_key (mode 0600) and used by the CLI and the SDK from then on. Revoke it any time from the portal (API keys). Scripts and CI can use a key you created in the portal instead, through the INFERHIVE_API_KEY environment variable.

Command line

inferhive offers                                   # GPUs and CPU you can rent right now
inferhive rent --gpu dp-note --template pytorch-jupyter --hours 1   # then open the URL it prints
inferhive instances | stop INS-XXXXXX              # your rentals
inferhive reserve --gpu knode11 --start 2026-11-10T18:00 --hours 2

inferhive job run python:3.12-slim -- python -c "print('hola')"            # CPU job
inferhive job run ghcr.io/you/whisper:1 --offer gpu --minutes 60 \
    --input meeting.mp3 --outputs ./results -- python -m pcoin.jobio -- python run.py
inferhive job list | logs JOB-XXXXXX | cancel JOB-XXXXXX

inferhive artifact put data.zip | list | get ART-XXXXXXXX | rm ART-XXXXXXXX
inferhive volume create dp-note 5 | list | delete VOL-XXXXXX
inferhive llm chat "Explain processing coins in one line"

GPU jobs sent with --offer gpu (any GPU) or with --wait on a busy node wait in a queue and start when a GPU frees up; nothing is charged while they wait. Inside the job container, python -m pcoin.jobio -- <your command> downloads the input files to /inputs, runs your program and uploads /outputs as a tarball when it ends.

Python

import pcoin

with pcoin.Client() as c:                      # uses the key saved by `inferhive login`
    print(c.balance())                         # {"currency": "PC", "available": ..., ...}

    free = [o for o in c.offers(gpu="4060") if o["available_now"]]
    inst = c.rent(free[0]["id"], "pytorch-jupyter", hours=1)
    c.stop(inst["id"])

    audio = c.upload_artifact("meeting.mp3")
    job = c.submit_job(
        "ghcr.io/you/whisper:1",
        offer="gpu",                           # or a node name
        timeout_minutes=60,
        inputs=[audio["id"]],
        outputs=True,
        command=["python", "-m", "pcoin.jobio", "--", "python", "run.py"],
    )
    done = c.wait_job(job["id"], on_update=lambda j: print(j["status"], j.get("queue_position")))
    c.download_artifact(done["result"]["output_artifact"], "results.tar.gz")

LLM gateway, with any OpenAI client (pip install 'inferhive[openai]'):

from pcoin import llm

client = llm.openai_client()                   # PCOIN_API_KEY or ~/.config/pcoin/api_key
reply = client.chat.completions.create(
    model="qwen3.8-27b",
    messages=[{"role": "user", "content": "Hola"}],
)
print(reply.choices[0].message.content)
print(llm.chat_full("Hola")["cost_pc"])        # the PC the gateway charged for that call

Environment variables

Errors

Every API error raises a pcoin.errors.PCoinError subclass with a stable code (AuthError, InsufficientCreditsError, NotFoundError, ValidationError, RateLimitError, ServerError). The CLI prints the message and exits with status 1.

Changes

• 0.3.0: pcoin.jobio uses /inputs and /outputs when the portal mounts them and otherwise writable folders under /scratch, and retries connection errors; automatic retry of 429 following Retry-After; artifact get no longer overwrites local files (--force); job run --secret-env, --detach --outputs and job outputs; rent --minutes; llm keys save.
• 0.2.0: browser login (pcoin login), GPU queue, cloud files and batch jobs.

License

MIT. Full documentation, pricing and the platform's architecture: https://hive.impulsate.lat.