krauncher: Instructions file for Codex

Krauncher — reference for coding agents / LLMs

Accurate, self-contained reference for generating working krauncher code. If anything here conflicts with prose in the README, trust this file and the docstrings in krauncher/. Runnable, verified examples live in tutorial/.

krauncher runs a plain Python function on a remote GPU and returns its result. It is async. No platform abstractions, no container definitions.

---

The one canonical pattern

import asyncio
from krauncher import KrauncherClient

client = KrauncherClient()                 # config from env / .env

@client.task(vram_gb=24, timeout=600)      # decorator makes the function async
def train(epochs: int = 3):
    import torch                           # ALL imports go inside the function
    # ... work on the GPU ...
    return {"loss": 0.01}                  # return value must be JSON-serializable

async def main():
    handle = await train(epochs=5)         # calling submits → returns TaskHandle
    print(handle.task_id, handle.classification.tier)
    result = await handle                  # awaiting the handle → TaskResult
    # or: result = await handle.wait(timeout=3600, on_log=print)
    print(result.output, result.actual_gpu, result.charged_ku)

asyncio.run(main())

Rules that must hold for generated code:

• The task function is called with keyword arguments only (train(epochs=5), not train(5)).
• The function must be self-contained: every import and helper it uses must be defined inside it (or passed via the helper-function mechanism, tutorial 12). It runs in a fresh sandbox with no access to your module-level globals.
• The return value is serialized — return JSON-compatible data (dict, list, str, number, bool, None).
• Everything is async — call task functions inside an async def and await.

---

Install & configuration

pip install krauncher
export CAS_API_KEY="cas_..."

Python 3.11+. All settings read from constructor args (highest priority), then env vars / a .env file in CWD.