Badgr Compute API

1. Install and log in

npm install -g badgr-cli

Requires Node.js 20.10+. Installs the badgr command.

badgr login

Prompts for your API key and saves it to ~/.badgr/config.json.

2. Three primitives, many job types

3. badgr launch — coding & testing agents

Run a coding agent or a test suite on a CPU VM with one command — no image, source, or --max-cost required for the four built-in workloads. Three separate things are going on here: which agent CLI runs, who pays for model usage, and who provisions the VM (always Badgr).

badgr launch cline "Fix the checkout bug"        # Badgr provides model access — no account to connect
badgr launch claude "Fix the checkout bug"       # runs Claude Code — connect your Anthropic account
badgr launch codex "Write tests"                 # runs the Codex CLI — connect your OpenAI account
badgr launch playwright "Test the checkout flow" # no model account involved at all

Authentication model

Installing the claude/codex CLI on a disposable VM doesn't by itself give it model access — the CLI still has to authenticate, and a VM doesn't inherit your laptop's sign-in. badgr launch claude/codex prompt inline the first time to connect your account and remember it; cline and playwright need nothing. Today "connect your account" means securely storing an API key — both CLIs also support signing in via a Claude.ai/ChatGPT account, and a future badgr connect may add that OAuth flow instead of a pasted key. Connect ahead of time with badgr connect anthropic --key sk-ant-....

Retrieve results

badgr pull <deployment-id>          # pull a code-editing agent's patch as a local git diff/branch
badgr artifacts <deployment-id>     # download everything else — test reports, screenshots, traces

Advanced escape hatch — any other command

badgr launch . --max-cost 1 -- npm test
badgr launch https://github.com/user/repo --max-cost 1 -- python narrgo.py

Everything before -- is a Badgr flag; everything after is passed to your command verbatim, including anything that looks like a flag.

3b. badgr sbatch — run existing Slurm scripts

Run an existing .slurm batch script without rewriting it. Translates the common #SBATCH directives (--cpus-per-task, --mem, --gres=gpu:..., --time, --array, --export) into the same job Badgr already submits for badgr run — cluster-specific flags like --partition or --qos are parsed but ignored, with a warning.

badgr sbatch job.slurm              # parse + submit, stream to completion
badgr sbatch job.slurm --dry-run    # parse only, print the translated plan, no GPU touched
badgr sbatch array_job.slurm --max-concurrency 10   # cap array-task concurrency (default: 5)

--array fans out into one deployment per task index, each with SLURM_ARRAY_TASK_ID/SLURM_ARRAY_JOB_ID set the way a real Slurm array would, monitored independently and summarized as one job.

3c. badgr diagnose — Badgr Smoke Test

Paste anything. Badgr auto-detects the input type, redacts secrets, extracts the workload, runs free static checks, matches verified templates, and shows either missing information, a known-good configuration, or a capped smoke-test plan. No GPU is provisioned during diagnosis.

# Free Badgr Smoke Test — no login required
badgr diagnose "https://github.com/org/repo/issues/123"
badgr diagnose ajayrajtp/vllm_gemma412b:latest
badgr diagnose ./vllm-error.log
badgr diagnose "https://github.com/org/repo"
badgr diagnose workflow.json

# Free mechanical validation of the produced command — still no GPU, no login
badgr diagnose "https://github.com/org/repo/issues/123" --smoke

# Approve a capped smoke test after diagnosis (login required)
badgr diagnose "https://github.com/org/repo/issues/123" --approve

# Resume an existing case, e.g. one shared via a case link
badgr diagnose repro_xxxxxxxx --approve

# Machine-readable output
badgr diagnose "https://github.com/org/repo/issues/123" --json

What Badgr accepts

Status ladder

Every run prints exactly one of these. VERIFIED is never assigned from static resolution or --smoke — only from an actual successful GPU-provisioned run.

READY/SMOKE CHECKED results also print the canonical badgr run/badgr serve command --approve would run, plus a shareable case link — resume it later with badgr diagnose <case_id_or_url> --approve.

Diagnosis output

Full interactive flow (no CLI required): aibadgr.com/run-issue

3d. badgr job — bounded coding-agent jobs with a check

An agent job is a coding-agent run with a pass/fail check attached — one of several job types on the same unified Jobs API (alongside custom.run, model.serve, train.lora, and image/video jobs). You give the agent an instruction and the command that proves it worked; Badgr runs both on a disposable VM, records whether the check passed, and stores a receipt. Unlike badgr launch, a job is a tracked record you can poll, cancel, and look up later.

# Run a job and wait for the check result
badgr job cline "Fix the checkout bug" --check "npm test"

# Pick the agent and cap spend and runtime
badgr job claude-code "Add pagination" --check "pytest tests/" --max-cost 3 --max-runtime 3600

# Run against a remote repo at a specific ref
badgr job codex "Refactor auth" --check "pytest tests/" \
  --repo https://github.com/org/repo --ref main

# Submit and return immediately
badgr job cline "Fix the bug" --check "npm test" --detach

# Equivalent: badgr launch with --eval-command routes to the same agent job type
badgr launch cline "Fix the checkout bug" --eval-command "npm test"

Flags

Web form (no CLI required): aibadgr.com/dashboard/jobs/new

3e. More CLI commands

Diagnostics, fine-tuning, transcription, embeddings, batch workloads, and account management.

badgr doctor — local GPU diagnosis, read-only, no login needed

badgr doctor
badgr doctor --model meta-llama/Llama-3.1-8B-Instruct   # will this model fit?
badgr doctor --logs error.log                            # diagnose a crashed job's log
badgr doctor --url http://localhost:8000/v1/models       # a server that's not responding
badgr doctor --json                                       # machine-readable output

Endpoint lifecycle — restart, rerun, heartbeat

badgr restart dep-abc123     # relaunch an endpoint with the same config — new ID, same API key
badgr rerun dep-abc123       # replay a past job or endpoint with its exact original spec — new ID
badgr heartbeat dep-abc123   # reset an endpoint's idle-timeout clock (pairs with badgr serve --idle-timeout)

badgr train / badgr train lora — fine-tuning

badgr train config.yaml --gpu A100 --max-runtime 240 --env HF_TOKEN=$HF_TOKEN
badgr train lora --base-model mistralai/Mistral-7B-v0.1 --dataset ./train.jsonl --preset small --max-cost 20

Detects framework from the config file — Axolotl and TRL configs run today, Unsloth is blocked before provisioning. train lora presets: small (RTX 4090, rank 16, 3 epochs), medium (A100, rank 32, 5 epochs).

badgr transcribe / badgr embed

badgr transcribe recording.mp3 --max-cost 2            # Whisper transcription
badgr embed BAAI/bge-large-en-v1.5 documents.txt --max-cost 2   # text embeddings, JSONL out

badgr batch — generic containerized batch jobs

badgr batch run workload.yml
badgr batch run workload.yml --fan-out ./scenarios --max-concurrency 10   # one deployment per input file
badgr batch status dep-abc123
badgr batch compare dep-abc123 dep-def456

badgr workload / badgr workspace — saved configs and cost tracking

badgr run . --cmd "python train.py" --max-cost 10 --save my-training-job
badgr workload run my-training-job                     # rerun a saved config by name
badgr workspace create my-project --storage s3://my-bucket/runs
badgr run . --cmd "python eval.py" --workspace my-project --max-cost 5

badgr models / badgr template / badgr capacity / badgr billing

badgr models                          # GPU catalog, cheapest first
badgr template list                   # browse provider-neutral workload templates
badgr capacity --gpu A100 --region EU # check live availability before launching
badgr billing status                  # current balance
badgr billing add 20                  # add funds — $5 minimum top-up

4. API shapes

badgr serve and badgr run expose different API shapes — don't mix them up.

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["BADGR_API_KEY"],
    base_url=os.environ["BADGR_ENDPOINT"],
)

# Chat completions  (badgr serve <model>)
resp = client.chat.completions.create(
    model="qwen/Qwen2.5-7B-Instruct",
    messages=[{"role": "user", "content": "Hello"}],
)

# Embeddings        (badgr serve <model> --task embed)
resp = client.embeddings.create(
    model="BAAI/bge-large-en-v1.5",
    input=["hello world"],
)

# Transcription     (badgr serve <model> --task transcribe)
with open("audio.mp3", "rb") as f:
    transcript = client.audio.transcriptions.create(
        model="large-v3", file=f, response_format="text",
    )

# Image generation  (badgr serve <model> --task image)
resp = client.images.generate(
    model="black-forest-labs/FLUX.1-schnell",
    prompt="A futuristic city at sunset",
    n=1, size="1024x1024",
)

curl -X POST "$BADGR_API_BASE/v1/jobs" \
  -H "Authorization: Bearer $BADGR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "custom.run",
    "code_uri": "badgr-upload://abc123",
    "cmd": "python train.py",
    "max_cost": 5
  }'

5. Job types and recipes

curl -X POST https://aibadgr.com/api/v1/jobs \
  -H "Authorization: Bearer $BADGR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "agent",
    "input": {
      "repository": "https://github.com/org/repo",
      "ref": "main",
      "agent": "cline",
      "instruction": "Fix the checkout bug",
      "check": "npm test"
    },
    "policy": { "max_cost": 2.0, "max_runtime_minutes": 30 }
  }'
# => 201 { "job_id": "job_...", "status": "queued" }

6. How it runs your code

Badgr does not require you to build or push a Docker image. Point it at a folder, a GitHub repo, or a custom image — it handles the rest.

badgr run . --cmd "python score_leads.py" --max-cost 1

badgr run https://github.com/user/repo --cmd "python score_leads.py" --max-cost 1

badgr run . --image myco/lead-env:latest --cmd "python score_leads.py" --max-cost 1

7. Quick examples

badgr run . --cmd "python train.py" --gpu A100 --max-cost 10

badgr serve Qwen/Qwen2.5-7B-Instruct --max-cost 10

badgr down <deployment-id>

8. How jobs work

Every badgr run or badgr serve call submits a job through the Badgr Jobs API. You can also drive this API directly if you want to integrate GPU workloads into your own systems.

9. Workload examples

# Upload your project zip to get a code_uri (multipart POST)
zip -r project.zip . -x "*.git*" "node_modules/*" "__pycache__/*"
curl -X POST https://aibadgr.com/v1/uploads \
  -H "Authorization: Bearer $BADGR_API_KEY" \
  -F "file=@project.zip" > upload.json
# upload.json → { "code_uri": "https://aibadgr.com/v1/uploads/.../download?token=..." }

# Submit the job
curl https://aibadgr.com/v1/jobs \
  -H "Authorization: Bearer $BADGR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "custom.run",
    "input": {
      "gpu": "A100",
      "code_uri": "<code_uri from upload>",
      "cmd": "python train.py --epochs 10",
      "env": { "HF_TOKEN": "hf_..." }
    },
    "policy": { "max_cost": 5 }
  }'

curl https://aibadgr.com/v1/jobs \
  -H "Authorization: Bearer $BADGR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "model.serve",
    "model": "Qwen/Qwen2.5-7B-Instruct",
    "gpu": "RTX_4090"
  }'

curl https://aibadgr.com/v1/jobs/$JOB_ID \
  -H "Authorization: Bearer $BADGR_API_KEY"

# Response fields:
# status: queued | provisioning | running | completed | failed | canceled
# logs:   recent stdout/stderr lines
# result: output data when status=completed

curl -X POST https://aibadgr.com/v1/jobs/$JOB_ID/cancel \
  -H "Authorization: Bearer $BADGR_API_KEY"

10. Productized runner flows

Three zero-config GPU flows. No Docker image selection, no Axolotl YAML, no ComfyUI setup — just a job type and parameters.

curl https://aibadgr.com/v1/jobs \
  -H "Authorization: Bearer $BADGR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "model.serve",
    "input": { "model": "qwen-7b" }
  }'

# Response includes endpoint_url and the resolved model_id:
# {
#   "output": {
#     "endpoint_url": "https://...",
#     "model": "Qwen/Qwen2.5-7B-Instruct",
#     "alias": "qwen-7b"
#   }
# }

# Option A: dataset from URL
curl https://aibadgr.com/v1/jobs \
  -H "Authorization: Bearer $BADGR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "train.lora",
    "input": {
      "base_model": "Qwen/Qwen2.5-7B-Instruct",
      "config_preset": "small",
      "dataset_url": "https://huggingface.co/datasets/tatsu-lab/alpaca/resolve/main/data/train-00000-of-00001.parquet"
    }
  }'

# Option B: dataset from a GitHub repo file
# "github_dataset_url": "https://github.com/user/repo/blob/main/data/train.jsonl"

# Option C: dataset from a Badgr file upload
# "dataset_file_id": "<id from POST /v1/uploads>"

# After completion, download the LoRA adapter:
curl https://aibadgr.com/v1/jobs/$JOB_ID/adapter \
  -H "Authorization: Bearer $BADGR_API_KEY" \
  -o lora-adapter.tar.gz

curl https://aibadgr.com/v1/jobs \
  -H "Authorization: Bearer $BADGR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "comfy.batch",
    "input": {
      "workflow_id": "sdxl-basic",
      "prompts": [
        "a red fox in a snowy forest, photorealistic",
        "a futuristic city at sunset, digital art",
        "an astronaut riding a horse on the moon"
      ]
    }
  }'

# After completion, job output contains:
# { "image_urls": ["https://aibadgr.com/v1/jobs/.../images/0", ...] }

# Download each image:
curl https://aibadgr.com/v1/jobs/$JOB_ID/images/0 \
  -H "Authorization: Bearer $BADGR_API_KEY" \
  -o image_0.png

GPU options

Badgr Auto selects the best eligible GPU for your workload. Use --gpu or --min-vram only when you need more control.

Available GPU types may vary by region and current capacity. Run badgr capacity or use --dry-run to confirm availability and pricing before provisioning.

Coming soon

Not supported