CLI et SDK

La commande nodelodge et les SDK TypeScript et Python appellent l’API Node Lodge avec une clé d’API. Ils trouvent une machine Node Lodge Secure, lancent une session avec un coût maximal, vous donnent la commande SSH et arrêtent la session.

Avant de commencer

1. Dans la console, ouvrez Keys et créez une clé avec les portées workloads:read, workloads:write et billing:read.
2. Définissez ses Spending limits (par session et au total). Node Lodge refuse toute session qui en dépasserait une.
3. Préparez une paire de clés SSH. Voir Clés SSH.

Chaque session réserve son coût maximal sur le crédit de votre organisation au lancement, comme budget. Elle est facturée pour son temps réel d’exécution, jamais au-delà du budget. Voir Facturation.

Ligne de commande

Requiert Node.js 22 ou plus récent.

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

Sur macOS, vérifiez avec shasum -a 256 -c nodelodge.mjs.sha256. Assurez-vous que ~/.local/bin figure dans votre PATH.

Connexion

nodelodge login

Collez la clé à l’invite. Elle est vérifiée, puis enregistrée, lisible par vous seul, dans votre dossier de configuration (~/.config/nodelodge sous Linux, ~/Library/Application Support/nodelodge sous macOS, %APPDATA%\nodelodge sous Windows). La clé n’est jamais saisie sur la ligne de commande : elle reste hors de l’historique de votre shell. En CI, définissez plutôt NODELODGE_API_KEY. nodelodge logout supprime la clé enregistrée.

Trouver une machine

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

Filtres : --gpu <model>, --min-gpus <n>, --min-vram <GB>, --max-price <USD per hour>, --all (y compris les machines en rupture de stock). Les offres sont listées de la moins chère à la plus chère, avec leurs caractéristiques, leur prix horaire et leur emplacement.

Lancer, se connecter, arrêter

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 est obligatoire : le coût maximal de la session, en USD. Il est réservé sur votre crédit, et la session s’arrête avant qu’il soit dépensé. Ajoutez --hours <n> pour l’arrêter après n heures.
• --environment <id> choisit l’environnement, jupyterlab par défaut : les machines en centre de données exécutent jupyterlab.
• raise-budget relève le budget d’une session en cours à un nouveau --max-cost, dans les limites de la clé.
• --allow est l’adresse IPv4 publique depuis laquelle vous vous connectez, ou une plage jusqu’à /24. Elle seule peut joindre la machine en SSH.
• La clé SSH est lue dans ~/.ssh/id_ed25519.pub (puis id_ecdsa.pub, id_rsa.pub). Indiquez-en une autre avec --ssh-key <file>. Elle ouvre cette session seulement et n’est pas enregistrée sur votre compte.
• status --wait attend que la machine tourne en affichant chaque étape du lancement dès qu’elle commence, puis affiche sa commande ssh. Avec --json, seul l’objet de la session est affiché, avec son champ launch. status seul liste vos sessions actives, status --ended vos sessions terminées.
• stop met fin à la session : la facturation s’arrête, la machine et son disque sont supprimés. Copiez d’abord vos résultats hors de la machine.

Ajoutez --json à n’importe quelle commande pour obtenir les objets de session, pour vos scripts :

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

Codes de sortie : 0 terminé, 1 refusé par Node Lodge (le motif et son code sont affichés), 2 ligne de commande invalide.

SDK TypeScript

Requiert Node.js 22 ou plus récent.

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;
}

Les montants sont en cents. nl.sessions.raiseBudget(id, 4000) relève le budget d’une session en cours. launch accepte un environmentId facultatif, et nl.environments.list({ offerId }) liste ce qu’une machine Community peut exécuter. nl.account.funds() renvoie le crédit disponible pour une nouvelle session.

SDK Python

Requiert Python 3.10 ou plus récent.

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.")

Les modèles sont typés avec des champs en snake_case, par exemple offer.price_per_hour_cents et session.max_cost_cents. nl.sessions.raise_budget(session.id, 4000) relève le budget d’une session en cours. launch accepte un environment_id facultatif, et nl.environments.list(offer_id=...) liste ce qu’une machine Community peut exécuter.

Les sessions dans les deux SDK

Une session a les mêmes champs dans les deux SDK (camelCase en TypeScript, snake_case en Python) :

Ce que les deux SDK font pour vous

• Nouvelles tentatives : les lectures et les lancements sont relancés en cas d’erreur réseau, de 429 et de 5xx, avec un délai exponentiel, et Retry-After est respecté. Un lancement est envoyé avec une clé d’idempotence : une nouvelle tentative ne démarre jamais deux sessions. L’arrêt et la hausse de budget ne sont pas répétés après un échec qui a pu atteindre Node Lodge : vérifiez plutôt la session avec get.
• Erreurs typées : AuthenticationError (401), PaymentRequiredError (402), PermissionError (403), NotFoundError (404), ConflictError (409), RateLimitError (429), ServerError (5xx), NetworkError et TimeoutError. Chaque erreur de l’API a un code stable et un message présentable à une personne.
• Un démarrage manqué ne coûte rien : si la machine ne peut pas démarrer, la session échoue, rien n’est facturé et son budget est libéré.
• Sessions et réservations : sur un compte qui réserve les machines en centre de données sous forme de réservations (RESERVATION_REQUIRED), launch, get, list et stop fonctionnent de la même façon, et kind vaut reservation.
• Votre clé reste privée : elle n’est envoyée qu’à Node Lodge, en HTTPS, et n’apparaît jamais dans un message d’erreur.

Pour piloter des sessions depuis un agent d’IA, voir Utiliser Node Lodge depuis un agent d’IA (MCP).