CLI und SDK

Der Befehl nodelodge und die SDKs für TypeScript und Python rufen die Node Lodge API mit einem API-Schlüssel auf. Sie finden eine Secure-Maschine von Node Lodge, starten eine Sitzung mit Höchstkosten, liefern Ihnen den SSH-Befehl und stoppen die Sitzung.

Voraussetzungen

1. Öffnen Sie in der Konsole Keys und erstellen Sie einen Schlüssel mit den Scopes workloads:read, workloads:write und billing:read.
2. Legen Sie seine Spending limits fest (pro Sitzung und insgesamt). Node Lodge lehnt jede Sitzung ab, die eines davon überschreiten würde.
3. Halten Sie ein SSH-Schlüsselpaar bereit. Siehe SSH-Schlüssel.

Jede Sitzung reserviert beim Start ihre Höchstkosten als Budget auf dem Guthaben Ihrer Organisation. Abgerechnet wird ihre tatsächliche Laufzeit, nie mehr als das Budget. Siehe Abrechnung.

Kommandozeile

Erfordert Node.js 22 oder neuer.

Installation

mkdir -p ~/.local/bin && cd ~/.local/bin
curl -fsSLO https://nodelodge.com/downloads/nodelodge.mjs
curl -fsSLO https://nodelodge.com/downloads/nodelodge.mjs.sha256
sha256sum -c nodelodge.mjs.sha256 && mv nodelodge.mjs nodelodge && chmod +x nodelodge

Unter macOS prüfen Sie mit shasum -a 256 -c nodelodge.mjs.sha256. Stellen Sie sicher, dass ~/.local/bin in Ihrem PATH liegt.

Anmelden

nodelodge login

Fügen Sie den Schlüssel ein, wenn Sie dazu aufgefordert werden. Er wird geprüft und dann nur für Sie lesbar in Ihrem Konfigurationsordner gespeichert (~/.config/nodelodge unter Linux, ~/Library/Application Support/nodelodge unter macOS, %APPDATA%\nodelodge unter Windows). Der Schlüssel wird nie auf der Kommandozeile eingegeben und bleibt so aus Ihrem Shell-Verlauf heraus. Setzen Sie in CI stattdessen NODELODGE_API_KEY. nodelodge logout entfernt den gespeicherten Schlüssel.

Eine Maschine finden

nodelodge offers --min-vram 48
nodelodge offers --gpu H100 --min-gpus 2

Filter: --gpu <model>, --min-gpus <n>, --min-vram <GB>, --max-price <USD per hour>, --all (auch nicht vorrätige Maschinen). Die Angebote erscheinen günstigste zuerst, mit Spezifikationen, Stundenpreis und Standort.

Starten, verbinden, stoppen

nodelodge balance
nodelodge launch 3f0c8f5e-8c3a-4f39-9a8e-2d9b4c1e7a10 --max-cost 20 --allow 203.0.113.7
nodelodge status 9b2d6a1e-1f5c-4a8e-9a77-3c0f2e6d4b21 --wait
nodelodge raise-budget 9b2d6a1e-1f5c-4a8e-9a77-3c0f2e6d4b21 --max-cost 40
nodelodge stop 9b2d6a1e-1f5c-4a8e-9a77-3c0f2e6d4b21

• --max-cost ist erforderlich: der Höchstbetrag der Sitzung in USD. Er wird auf Ihrem Guthaben reserviert, und die Sitzung stoppt, bevor er aufgebraucht ist. Mit --hours <n> stoppt sie nach n Stunden.
• --environment <id> wählt die Umgebung, standardmäßig jupyterlab: Rechenzentrumsmaschinen führen jupyterlab aus.
• raise-budget erhöht das Budget einer laufenden Sitzung auf ein neues --max-cost, innerhalb der Limits des Schlüssels.
• --allow ist die öffentliche IPv4-Adresse, von der aus Sie sich verbinden, oder ein Bereich bis /24. Nur sie erreicht die Maschine per SSH.
• Der SSH-Schlüssel wird aus ~/.ssh/id_ed25519.pub gelesen (danach id_ecdsa.pub, id_rsa.pub). Einen anderen übergeben Sie mit --ssh-key <file>. Er öffnet nur diese Sitzung und wird nicht in Ihrem Konto gespeichert.
• status --wait wartet, bis die Maschine läuft, zeigt dabei jeden Startschritt an, sobald er beginnt, und gibt dann ihren ssh-Befehl aus. Mit --json wird nur das Sitzungsobjekt ausgegeben, mit seinem Feld launch. status allein listet Ihre laufenden Sitzungen, status --ended die beendeten.
• stop beendet die Sitzung: Die Abrechnung endet, Maschine und Festplatte werden gelöscht. Kopieren Sie Ihre Ergebnisse vorher von der Maschine.

Mit --json liefert jeder Befehl die Sitzungsobjekte, für Skripte:

id=$(nodelodge launch "$OFFER" --max-cost 20 --allow "$MY_IP" --json | jq -r .id)
nodelodge status "$id" --wait --json | jq -r '.ssh.host'

Exit-Codes: 0 erledigt, 1 von Node Lodge abgelehnt (Grund und Code werden ausgegeben), 2 ungültige Kommandozeile.

TypeScript-SDK

Erfordert Node.js 22 oder neuer.

npm install https://nodelodge.com/downloads/nodelodge-sdk.tgz

import { ConflictError, NodeLodge, PaymentRequiredError } from '@nodelodge/sdk';

const nl = new NodeLodge({ apiKey: process.env.NODELODGE_API_KEY ?? '' });

const { items } = await nl.offers.list({ minVramGb: 48, bookableOnly: true });
try {
  const session = await nl.sessions.launch({
    offerId: items[0].id,
    maxCostCents: 2000,
    sshPublicKey: 'ssh-ed25519 AAAA... you@laptop',
    allowedCidr: '203.0.113.7',
  });
  let s = await nl.sessions.get(session.id);
  while (!s.ssh) {
    await new Promise((r) => setTimeout(r, 10_000));
    s = await nl.sessions.get(session.id);
  }
  console.log(`ssh ${s.ssh.user}@${s.ssh.host}`);
  // ... run your job ...
  await nl.sessions.stop(session.id);
} catch (err) {
  if (err instanceof ConflictError) console.error(err.code, err.message); // API_KEY_LIMIT
  else if (err instanceof PaymentRequiredError) console.error('Add credit in Billing.');
  else throw err;
}

Beträge werden in Cent angegeben. nl.sessions.raiseBudget(id, 4000) erhöht das Budget einer laufenden Sitzung. launch nimmt eine optionale environmentId, und nl.environments.list({ offerId }) listet, was eine Community-Maschine ausführen kann. nl.account.funds() liefert das für eine neue Sitzung verfügbare Guthaben.

Python-SDK

Erfordert Python 3.10 oder neuer.

pip install https://nodelodge.com/downloads/nodelodge-0.2.0-py3-none-any.whl

import os
import time

from nodelodge import ConflictError, NodeLodge, PaymentRequiredError

with NodeLodge(os.environ["NODELODGE_API_KEY"]) as nl:
    offer = nl.offers.list(min_vram_gb=48, bookable_only=True).items[0]
    try:
        session = nl.sessions.launch(
            offer.id,
            max_cost_cents=2000,
            ssh_public_key=open(os.path.expanduser("~/.ssh/id_ed25519.pub")).read().strip(),
            allowed_cidr="203.0.113.7",
        )
        while (s := nl.sessions.get(session.id)).ssh is None:
            time.sleep(10)
        print(f"ssh {s.ssh.user}@{s.ssh.host}")
        # ... run your job ...
        nl.sessions.stop(session.id)
    except ConflictError as e:      # API_KEY_LIMIT
        print(e.code, e.message)
    except PaymentRequiredError:
        print("Add credit in Billing.")

Die Modelle sind typisiert, mit Feldern in snake_case, zum Beispiel offer.price_per_hour_cents und session.max_cost_cents. nl.sessions.raise_budget(session.id, 4000) erhöht das Budget einer laufenden Sitzung. launch nimmt eine optionale environment_id, und nl.environments.list(offer_id=...) listet, was eine Community-Maschine ausführen kann.

Sitzungen in beiden SDKs

Eine Sitzung hat in beiden SDKs dieselben Felder (camelCase in TypeScript, snake_case in Python):

Was beide SDKs für Sie übernehmen

• Wiederholungen: Lesezugriffe und Starts werden bei Netzwerkfehlern, 429 und 5xx mit exponentiellem Backoff wiederholt, Retry-After wird beachtet. Ein Start wird mit einem Idempotenzschlüssel gesendet, eine Wiederholung startet also nie zwei Sitzungen. Stoppen und Budgeterhöhungen werden nach einem Fehler, der Node Lodge erreicht haben könnte, nicht wiederholt: Prüfen Sie die Sitzung stattdessen mit get.
• Typisierte Fehler: AuthenticationError (401), PaymentRequiredError (402), PermissionError (403), NotFoundError (404), ConflictError (409), RateLimitError (429), ServerError (5xx), NetworkError und TimeoutError. Jeder API-Fehler hat einen stabilen code und eine Meldung, die Sie einer Person zeigen können.
• Ein fehlgeschlagener Start kostet nichts: Kann die Maschine nicht starten, schlägt die Sitzung fehl, nichts wird abgerechnet, und ihr Budget wird freigegeben.
• Sitzungen und Buchungen: Auf einem Konto, das Rechenzentrumsmaschinen als Buchungen bucht (RESERVATION_REQUIRED), funktionieren launch, get, list und stop genauso, und kind ist reservation.
• Ihr Schlüssel bleibt privat: Er wird nur über HTTPS an Node Lodge gesendet und erscheint nie in einer Fehlermeldung.

Um Sitzungen stattdessen aus einem KI-Agenten zu steuern, siehe Node Lodge aus einem KI-Agenten nutzen (MCP).