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 job outputs JOB-XXXXXX ./results        # outputs of a job sent with --detach (--force to overwrite)

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="gemma4-e4b",
    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.1: pcoin.jobio retries GCS 5xx/429 and incomplete downloads (.part then rename), refuses two inputs with the same file name, builds the outputs tarball on disk and keeps the program's exit code when the upload fails; job run --outputs / job outputs never overwrite local files (--force) and list what they extracted; download_artifact uses a unique temporary file and an atomic final check; upload_artifact and job run --input delete the reserved files when an upload fails; the CLI says when it waits for a 429 (INFERHIVE_RETRY_429_MAX_WAIT); the Access redirect error tells students to run inferhive login; messages name the inferhive command.
• 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.