SandboxesSchnellstart

Sandboxes-Schnellstart

In diesem Schnellstart erstellen Sie mit Lizard SDK eine Sandbox, führen darin Python aus, schreiben eine Datei, öffnen einen Port und beenden die Sandbox. Jeder Schritt hat Code für TypeScript und Python. Sie brauchen ein Konto bei Lizard (lizard.build) mit Pro oder der Testphase, einen API-Schlüssel und ein Projekt. Was Sandboxes sind, erfahren Sie zuerst im Überblick.

Installation und Anmeldung

Installieren Sie das Lizard SDK und erstellen Sie unter Settings → API keys oder mit lizard keys create <name> einen API-Schlüssel. Speichern Sie ihn in LIZARD_API_KEY. Jede Sandbox gehört zu einem Projekt; die Beispiele übergeben dessen ID als projectId (Python: project_id), und project akzeptiert auch einen Slug oder Namen.

npm install @lizard-build/sdk
pip install lizard-sdk
export LIZARD_API_KEY="<your-api-key>"

Befehl ausführen

Sandbox.create startet eine Sandbox aus einer Vorlage, hier interpreter, die Python und gängige Datenbibliotheken enthält. timeoutMs legt ihre Laufzeit fest; der Standard im SDK sind fünf Minuten.

import { Sandbox } from '@lizard-build/sdk';
 
const sandbox = await Sandbox.create('interpreter', {
  projectId: 'proj_123', timeoutMs: 300_000,
});
try {
  const result = await sandbox.process.exec("python -c 'print(2 ** 10)'");
  console.log(result.stdout, result.stderr, result.exitCode);
} finally {
  await sandbox.kill();
}
from lizard import Sandbox
 
sandbox = Sandbox.create("interpreter", project_id="proj_123", timeout_ms=300_000)
try:
    result = sandbox.process.exec_("python -c 'print(2 ** 10)'")
    print(result.stdout, result.stderr, result.exit_code)
finally:
    sandbox.kill()

Ein Exit-Code ungleich null steht im Ergebnis und löst keine Exception aus: Prüfen Sie exitCode (Python: exit_code) selbst.

Dateien

Schreiben Sie Text oder Bytes mit fs.write, lesen Sie Text mit fs.read und Bytes mit fs.readBytes (Python: read_bytes). Jede Datei auf der Festplatte übersteht eine Pause und landet in einem Snapshot. Ein Kill oder Ablauf löscht die Festplatte; legen Sie Dateien, die Sie später brauchen, daher auf ein Volume aus Persistent Volumes unter /workspace oder in einen Snapshot.

await sandbox.fs.write("/tmp/task.py", "print(42)\n");
const result = await sandbox.process.exec("python /tmp/task.py");
console.log(result.stdout);
sandbox.fs.write("/tmp/task.py", "print(42)\n")
result = sandbox.process.exec_("python /tmp/task.py")
print(result.stdout)

Öffentliche Ports

Starten Sie einen Server auf 0.0.0.0 und rufen Sie dann exposePort(port) auf (Python: expose_port). Der Aufruf gibt url, hostname und accessToken zurück. Der Port ist privat: Öffnen Sie url im Browser (sie enthält ?lizard_token=) oder senden Sie das Token im Header X-Lizard-Access-Token. Anfragen ohne Token erhalten 401. Nach dem Stopp bedient die Sandbox den Port nicht mehr. Für einen Dev-Server, den ein Agent gebaut hat, siehe Vorschau-URLs.

await sandbox.process.exec(
  "nohup python -m http.server 3000 --bind 0.0.0.0 --directory /tmp >/tmp/http.log 2>&1 </dev/null &",
);
const { url, hostname, accessToken } = await sandbox.exposePort(3000);
console.log(url); // open in a browser
const res = await fetch(`https://${hostname}/`, {
  headers: { 'X-Lizard-Access-Token': accessToken },
});
sandbox.process.exec_(
    "nohup python -m http.server 3000 --bind 0.0.0.0 --directory /tmp >/tmp/http.log 2>&1 </dev/null &"
)
exposed = sandbox.expose_port(3000)
print(exposed.url)  # open in a browser

Mit einer laufenden Sandbox verbinden

Merken Sie sich die Sandbox-ID (sandbox.sandboxId, Python: sandbox.sandbox_id) und rufen Sie Sandbox.connect(id) aus einem anderen Prozess oder einer späteren Anfrage auf, um ein Handle auf dieselbe Sandbox zu erhalten. connect prüft nur, ob die Sandbox existiert: Eine pausierte Sandbox wird dadurch nicht fortgesetzt, und sobald die Sandbox beendet oder abgelaufen ist, löst der Aufruf NotFoundError aus.

const connected = await Sandbox.connect(sandbox.sandboxId);
console.log(await connected.getInfo());
connected = Sandbox.connect(sandbox.sandbox_id)
print(connected.get_info())

Pause, Fortsetzen und Snapshots

pause() speichert Arbeitsspeicher, laufende Prozesse und jede Datei auf der Festplatte der Sandbox. Eine erfolgreiche Pause stoppt die Rechenkosten; Speicher in Persistent Volumes wird weiter berechnet. resume() stellt die Sandbox mit derselben ID wieder her und startet die Berechnung der Rechenkosten erneut. Beide Aufrufe reihen die Arbeit ein und kehren sofort zurück; warten Sie auf paused oder running, um den Erfolg zu bestätigen.

await sandbox.pause();
await sandbox.waitForStatus('paused');
await sandbox.resume();
await sandbox.waitForStatus('running');
  • Eine Pause schließt offene Netzwerkverbindungen. Programme in der Sandbox müssen sich nach dem Fortsetzen neu verbinden.
  • Lassen sich die Prozesse nicht speichern, läuft die Sandbox weiter, und waitForStatus löst einen Fehler mit dem Grund aus. Schlägt das Fortsetzen fehl, bleibt die Sandbox mit ihrem Checkpoint pausiert; rufen Sie resume() erneut auf.
  • Während der Pause bleibt die restliche Laufzeit unverändert. Nach dem Fortsetzen zählt sie weiter herunter. Eine pausierte Sandbox zählt nicht zum Limit laufender Sandboxes.

Schnelle Pause. pause({ fast: true }) (Python: pause(fast=True), CLI: lizard sandbox pause <id> --fast) behält nur die Dateien: die ganze Festplatte und /workspace. Das dauert bei jeder Speichergröße etwa eine Sekunde, während eine vollständige Pause umso länger dauert, je mehr Speicher belegt ist. Laufende Prozesse werden beendet, und resume() startet die Sandbox mit ihren Dateien neu, wie nach einem Neustart; die Antwort auf das Fortsetzen enthält memoryRestored: false. Nutzen Sie es, wenn nichts Laufendes erhalten bleiben muss. Abrechnung und Lebensdauer verhalten sich wie bei jeder Pause.

await sandbox.pause({ fast: true });
await sandbox.waitForStatus('paused');

Ein Snapshot speichert Arbeitsspeicher, laufende Prozesse und jede Datei auf der Festplatte einer laufenden Sandbox. Er lässt sich nur im eigenen Projekt und in der eigenen Region wiederherstellen. Wiederherstellen können ihn der Nutzer, der ihn erstellt hat, und die Mitglieder dieses Projekts. Sandbox.restore(id, { projectId }) (Python: project_id=) mit einem anderen Projekt schlägt mit HTTP 403 und code gleich SNAPSHOT_SCOPE fehl. Schließen Sie vor der Aufnahme Clients und Terminals und stoppen Sie Schreibvorgänge in /workspace.

Ist an die Sandbox ein Persistent Volume angehängt, enthält der Snapshot eine Kopie der Dateien des Volumes zum Zeitpunkt der Aufnahme. Jede Wiederherstellung erhält diese Kopie, nicht das laufende Volume, und kann kein weiteres Volume anhängen. Wer den Snapshot wiederherstellen kann, kann diese Dateien lesen. Ein Snapshot einer Sandbox ohne Volume kann bei der Wiederherstellung mit volumeId (Python: volume_id) ein Volume aus demselben Projekt und derselben Region einbinden.

const saved = await sandbox.snapshot('my-app');
await Sandbox.waitForSnapshot(saved.id);
const copy = await Sandbox.restore(saved.id);

Ein Snapshot ist bereit, sobald der Aufruf zurückkehrt, und wird von der Festplatte wiederhergestellt; daher gilt poolSize nicht. Jede Wiederherstellung startet eine Sandbox in der Größe der Quelle. Für sie gilt der Stundenpreis dieser Größe; size gilt nicht für ein Restore. In der CLI nutzen Sie lizard sandbox pause <id>, lizard sandbox resume <id>, lizard sandbox snapshot <id> --name my-app und lizard sandbox restore <snapshot-id>; --volume erklärt lizard sandbox.

Aufräumen und nächste Schritte

Rufen Sie kill() auf, wenn die Aufgabe erledigt ist, wie es die Beispiele in finally tun. In Python beendet with Sandbox.create(...) as sandbox: die Sandbox, wenn der Block endet. Eine nicht beendete Sandbox stoppt nach Ablauf ihrer Laufzeit, fünf Minuten nach der Erstellung, sofern Sie keine andere Laufzeit setzen; siehe Ressourcen und Laufzeit.

ÜbersichtSDK-Referenz

Aktualisiert