Developer Documentation

Submit Python scripts to EU GPU nodes, stream logs back, and pay per second. SDK v0.2.0.

Per-second billing GDPR Art. 28 DPA EU-hosted (Frankfurt)

Quick Start

Submit your first GPU job in under 2 minutes. Get your API key from the dashboard.

1. Install

bash

pip install ghostnexus           # sync Client + CLI
pip install "ghostnexus[async]"   # + AsyncClient (requires httpx)

2. Configure your API key

bash

ghostnexus configure
# → prompts for API key, saves to ~/.ghostnexus/config

3. Submit a job

python

import ghostnexus

client = ghostnexus.Client()  # reads GHOSTNEXUS_API_KEY or ~/.ghostnexus/config

job = client.run("train.py", task_name="llama3-qlora")
print(f"Status:   {job.status}")
print(f"Duration: {job.duration_seconds:.0f}s")
print(f"Cost:     ${job.cost_credits:.4f}")

Authentication

All API requests require an API key via the x-api-key header. Keys expire after 90 days and can be rotated from the dashboard or via API.

x-api-key: gn_live_<your-api-key>

Set GHOSTNEXUS_API_KEY in your environment to avoid passing the key explicitly. The SDK reads it automatically.

Sync Client

Blocking client — works anywhere Python runs. No event loop required.

python — submit and wait

import ghostnexus

client = ghostnexus.Client()  # reads GHOSTNEXUS_API_KEY or ~/.ghostnexus/config

job = client.run("train.py", task_name="llama3-qlora")
print(f"Status:   {job.status}")
print(f"Duration: {job.duration_seconds:.0f}s")
print(f"Cost:     ${job.cost_credits:.4f}")

python — stream logs in real time

# Stream logs in real time (no polling)
job = client.run("train.py", task_name="llama3-qlora")
for chunk in job.stream_logs():
    print(chunk, end="", flush=True)

Method	Returns	Description
Client(api_key=...)	Client	Init — reads env var if omitted
client.run(script, task_name=...)	Job	Submit job; waits for completion
client.status(job_id)	dict	Poll a job by ID without blocking
client.history(limit=20)	list[dict]	Recent jobs with cost/duration
client.balance()	float	Current credit balance in USD
job.stream_logs()	Iterator[str]	Stream stdout chunks as they arrive

Async Client

Drop-in async equivalent for asyncio environments. Requires pip install "ghostnexus[async]".

python — parallel dispatch

import asyncio
import ghostnexus

async def main():
    async with ghostnexus.AsyncClient() as client:
        # Dispatch two jobs in parallel
        jobs = await asyncio.gather(
            client.run("eval_a.py", task_name="eval-A"),
            client.run("eval_b.py", task_name="eval-B"),
        )
        for job in jobs:
            print(f"{job.task_name}: {job.status} — ${job.cost_credits:.4f}")

asyncio.run(main())

python — async log streaming

async with ghostnexus.AsyncClient() as client:
    job = await client.run("train.py")
    async for chunk in job.stream_logs():
        print(chunk, end="", flush=True)

All sync Client methods have async equivalents. Use as a context manager (async with) to ensure connections are closed.

CLI

The ghostnexus command is installed with the SDK. Configure once, then run scripts directly from your terminal.

bash

# Submit and stream logs
ghostnexus run train.py --stream --task llama3-qlora

# Inline script
ghostnexus run --script "import torch; print(torch.cuda.get_device_name(0))"

# Check status
ghostnexus status <job-id>

# View job history
ghostnexus history --limit 20

# Credit balance
ghostnexus balance

Command	Description
ghostnexus configure	Save API key to ~/.ghostnexus/config
ghostnexus run <file> [--stream] [--task NAME]	Submit a .py file; --stream tails logs
ghostnexus run --script "..."	Submit inline Python code
ghostnexus run --demo	Run a built-in GPU health check (no API key needed)
ghostnexus status <job-id>	Get job status, cost, duration
ghostnexus history [--limit N]	List recent jobs in a table
ghostnexus balance	Show current credit balance

REST API

Base URL: https://ghostnexus.net. All requests require x-api-key.

POST/api/jobs — Submit a job

bash

curl -X POST https://ghostnexus.net/api/jobs \
  -H "x-api-key: gn_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "task_name": "my-job",
    "script_content": "import torch\nprint(torch.cuda.get_device_name(0))"
  }'

# → 200 OK
{
  "job_id": "a3f8c2d1-...",
  "status": "queued",
  "task_name": "my-job"
}

GET/api/jobs/{job_id} — Job status

bash

GET /api/jobs/{job_id}
Authorization: x-api-key gn_live_...

# Response
{
  "job_id": "a3f8c2d1-...",
  "task_name": "my-job",
  "status": "success",          // queued | running | success | failed | error
  "duration_seconds": 142.3,
  "cost_credits": 0.0198,
  "output_logs": "RTX 4090\n..."
}

GET/api/jobs — Job history

bash

GET /api/jobs?limit=20&offset=0
Authorization: x-api-key gn_live_...

# Response
[
  { "job_id": "...", "task_name": "...", "status": "success", "cost_credits": 0.02 },
  ...
]

GET/api/me — Account info & balance

bash

GET /api/me
Authorization: x-api-key gn_live_...

# Response
{
  "email": "you@example.com",
  "credit_balance": 14.82,
  "api_key_expires_at": "2026-07-24T..."
}

POST/api/me/rotate-key — Rotate API key(rate-limited: 5/hour)

bash

POST /api/me/rotate-key
Authorization: x-api-key gn_live_...

# Response
{
  "api_key": "gn_live_NEW...",
  "expires_at": "2026-07-25T...",
  "message": "API key rotated. Update your config."
}

Keys expire after 90 days. Rotation is also available in the dashboard Settings.

Job status values

queuedrunningsuccessfailederror

GitHub Action

Dispatch GPU jobs from your CI pipeline with Milaskinger/ghostnexus-run@v1. No dependencies — pure Python stdlib.

yaml — .github/workflows/train.yml

- name: Run on GPU
  uses: Milaskinger/ghostnexus-run@v1
  with:
    api-key: ${{ secrets.GHOSTNEXUS_API_KEY }}
    script-path: train.py
    task-name: train-${{ github.sha }}
    timeout-minutes: 60

Full GitHub Action reference →

Provider Node

Have a GPU? Earn passive income by connecting it to the network. Jobs run in isolated Docker containers — your system stays safe.

bash

pip install ghostnexus-node
ghostnexus-node start --api-key gn_live_...

Full provider setup guide

Pricing

GPU	$/hr	$/sec
RTX 4070 / RTX 3080	$0.30	$0.000083
RTX 4090 / RTX 3090 Ti	$0.50	$0.000139
A100 (40 GB)	$2.20	$0.000611
H100 (80 GB)	$3.50	$0.000972

No minimum commitment, no per-hour rounding. Full pricing details →

Ready to start?

Create an account and get $15 free compute credits with code WELCOME15.

Get Free Credits