CLI y SDK

El comando nodelodge y los SDK de TypeScript y Python llaman a la API de Node Lodge con una clave de API. Encuentran una máquina Node Lodge Secure, lanzan una sesión con un costo máximo, le dan el comando SSH y detienen la sesión.

Antes de empezar

1. En la consola, abra Keys y cree una clave con los alcances workloads:read, workloads:write y billing:read.
2. Defina sus Spending limits (por sesión y total). Node Lodge rechaza cualquier sesión que superaría alguno.
3. Tenga listo un par de claves SSH. Consulte Claves SSH.

Cada sesión reserva su costo máximo sobre el crédito de su organización al lanzarse, como presupuesto. Se factura por el tiempo real en marcha, nunca más allá del presupuesto. Consulte Facturación.

Línea de comandos

Requiere Node.js 22 o posterior.

Instalación

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

En macOS, verifique con shasum -a 256 -c nodelodge.mjs.sha256. Asegúrese de que ~/.local/bin esté en su PATH.

Inicio de sesión

nodelodge login

Pegue la clave cuando se le pida. Se verifica y luego se guarda, legible solo por usted, en su carpeta de configuración (~/.config/nodelodge en Linux, ~/Library/Application Support/nodelodge en macOS, %APPDATA%\nodelodge en Windows). La clave nunca se escribe en la línea de comandos, así que no queda en el historial del shell. En CI, defina NODELODGE_API_KEY en su lugar. nodelodge logout elimina la clave guardada.

Buscar una máquina

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

Filtros: --gpu <model>, --min-gpus <n>, --min-vram <GB>, --max-price <USD per hour>, --all (incluye máquinas sin stock). Las ofertas se listan de la más barata a la más cara, con sus especificaciones, su precio por hora y su ubicación.

Lanzar, conectar, detener

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 es obligatorio: lo máximo que puede costar la sesión, en USD. Se reserva sobre su crédito, y la sesión se detiene antes de gastarlo. Añada --hours <n> para detenerla tras n horas.
• --environment <id> elige el entorno, jupyterlab por defecto: las máquinas de centro de datos ejecutan jupyterlab.
• raise-budget aumenta el presupuesto de una sesión en curso a un nuevo --max-cost, dentro de los límites de la clave.
• --allow es la dirección IPv4 pública desde la que se conecta, o un rango de hasta /24. Solo ella puede llegar a la máquina por SSH.
• La clave SSH se lee de ~/.ssh/id_ed25519.pub (luego id_ecdsa.pub, id_rsa.pub). Indique otra con --ssh-key <file>. Abre solo esta sesión y no se guarda en su cuenta.
• status --wait espera hasta que la máquina esté en marcha, mostrando cada paso del arranque en cuanto empieza, y luego imprime su comando ssh. Con --json, solo se imprime el objeto de la sesión, con su campo launch. status solo lista sus sesiones activas; status --ended, las finalizadas.
• stop finaliza la sesión: la facturación se detiene y la máquina y su disco se eliminan. Copie antes sus resultados fuera de la máquina.

Añada --json a cualquier comando para obtener los objetos de sesión, para scripts:

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

Códigos de salida: 0 terminado, 1 rechazado por Node Lodge (se imprimen el motivo y su código), 2 línea de comandos no válida.

SDK de TypeScript

Requiere Node.js 22 o posterior.

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

Los importes están en centavos. nl.sessions.raiseBudget(id, 4000) aumenta el presupuesto de una sesión en curso. launch acepta un environmentId opcional, y nl.environments.list({ offerId }) lista lo que puede ejecutar una máquina Community. nl.account.funds() devuelve el crédito disponible para una nueva sesión.

SDK de Python

Requiere Python 3.10 o posterior.

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

Los modelos están tipados con campos en snake_case, por ejemplo offer.price_per_hour_cents y session.max_cost_cents. nl.sessions.raise_budget(session.id, 4000) aumenta el presupuesto de una sesión en curso. launch acepta un environment_id opcional, y nl.environments.list(offer_id=...) lista lo que puede ejecutar una máquina Community.

Las sesiones en ambos SDK

Una sesión tiene los mismos campos en ambos SDK (camelCase en TypeScript, snake_case en Python):

Lo que ambos SDK hacen por usted

• Reintentos: las lecturas y los lanzamientos se reintentan ante errores de red, 429 y 5xx, con espera exponencial, y se respeta Retry-After. Un lanzamiento se envía con una clave de idempotencia, así que un reintento nunca inicia dos sesiones. La detención y el aumento de presupuesto no se repiten tras un fallo que pudo haber llegado a Node Lodge: consulte la sesión con get.
• Errores tipados: AuthenticationError (401), PaymentRequiredError (402), PermissionError (403), NotFoundError (404), ConflictError (409), RateLimitError (429), ServerError (5xx), NetworkError y TimeoutError. Cada error de la API tiene un code estable y un mensaje que puede mostrar a una persona.
• Un inicio fallido no cuesta nada: si la máquina no puede iniciarse, la sesión falla, no se factura nada y su presupuesto se libera.
• Sesiones y reservas: en una cuenta que contrata las máquinas de centro de datos como reservas (RESERVATION_REQUIRED), launch, get, list y stop funcionan igual, y kind vale reservation.
• Su clave permanece privada: solo se envía a Node Lodge por HTTPS y nunca aparece en un mensaje de error.

Para controlar sesiones desde un agente de IA, consulte Use Node Lodge desde un agente de IA (MCP).