Ein Skript schreiben und ausführen

Ein Skript ist ein benanntes Stück Quellcode in deinem Workspace – eine Datei, eine Sprache, ein Slug – im Browser geschrieben und überall wiederverwendbar, wo SupaCloud genau diese Logik braucht. Skripte findest du unter Build → Skripte.

Ein Skript läuft nicht in einem Container. Es läuft in einem festen, vorgebauten Interpreter – boa für JavaScript und TypeScript, CPython für Python – innerhalb einer WebAssembly-Sandbox (WASI 0.2). Dein Quellcode wird diesem Interpreter als Daten übergeben: nichts wird kompiliert, keine Pakete werden installiert, kein Image wird geladen. Genau das macht ein Skript billig im Start und sicher im unbeaufsichtigten Betrieb: standardmäßig hat es kein Dateisystem, keine Shell, keine Datenbank und überhaupt kein Netzwerk. Netzwerkzugriff ist etwas, das du gewährst – Host für Host und nie versehentlich.

Ein Skript ist nicht dasselbe wie eine Workflow-Code-Node

Beide führen deinen Code aus, aber es sind verschiedene Maschinen.

• Ein Skript ist ein eigenständiges Artefakt mit eigenem Board, Editor, Laufverlauf und Versionsliste. Es läuft immer auf dem oben beschriebenen WebAssembly-Substrat, mit festen 30 Sekunden Budget.
• Eine Workflow-Code-Node ist ein Schritt in einem Workflow. Unverändert läuft sie in einem hermetischen Docker-Container mit vollständig abgeschaltetem Netzwerk, sie kann ein mehrdateiliges Projekt tragen, und ihr Timeout ist bis zu 30 Minuten konfigurierbar. Erst wenn du einer Code-Node explizite Ressourcen-Bindungen gibst, wechselt sie auf dasselbe WebAssembly-Substrat – und dort kann sie, anders als ein eigenständiges Skript, zusätzlich bewachten Datenbankzugriff bekommen.

Eine Code-Node kann ein Skript referenzieren (Modus Script, siehe unten). Sie übernimmt dann Quellcode und Sprache des Skripts, behält aber ihr eigenes Ausführungsmodell. Derselbe Skripttext kann sich also je nach Ausführungsort unterschiedlich verhalten – lies deshalb den Lauf-Vertrag unten, bevor du etwas annimmst. Code-Nodes haben zudem einen eigenen Weg, Logik untereinander zu teilen, den ein Skript nicht nutzt – siehe Code zwischen Code-Nodes teilen.

Ein Skript anlegen

1. Öffne Build → Skripte und wähle + Neues Skript.

2. Fülle die Kopffelder aus:

   • Name – die menschenlesbare Bezeichnung, bis zu 200 Zeichen.
   • Slug – wird automatisch aus dem Namen abgeleitet, solange du ihn nicht angefasst hast. Nur Kleinbuchstaben, Ziffern und Bindestriche, 1–63 Zeichen, und er darf nicht mit einem Bindestrich beginnen. Das ist die stabile Adresse, die alles andere verwendet – wähle sie also bewusst; sie muss im Workspace eindeutig sein.
   • Sprache – TypeScript, JavaScript oder Python. Ein Sprachwechsel bei noch leerem Editor tauscht den Starter-Schnipsel aus.
   • Beschreibung – optional, wird im Board angezeigt.

3. Schreibe den Rumpf im Editor Quellcode. Ein Skript ist eine einzige Datei, deshalb zeigt der Editor keinen Dateibaum – nur den Code und einen Zeilenzähler.

4. Wähle Skript erstellen. Du landest im Vollbild-Editor, rechts das Ausführungs-Panel und im Kopf die Reiter Bearbeiten / Versionen.

Für den Lauf-Vertrag schreiben

Der Starter-Schnipsel, den der Editor vorbelegt, ist für eine Workflow-Code-Node geformt – eine exportierte handler-Funktion oder Python, das von der Standardeingabe liest. Ein direkter Skriptlauf ruft das nie auf. Das Substrat wertet deinen Quellcode von oben nach unten aus und nimmt den Wert des letzten Ausdrucks als Ergebnis. Ersetze den Starter also vor dem ersten Lauf.

Die Regeln sind in jeder Sprache dieselben:

• Was du als Eingabe übergibst, kommt als globale input an (sie ist null, wenn du nichts sendest).
• Das Ergebnis ist der Wert des letzten Ausdrucks. In Python wird, falls die letzte Anweisung auf oberster Ebene kein Ausdruck ist, stattdessen eine Variable result auf oberster Ebene verwendet – setzt du keines von beidem, ist das Ergebnis leer.
• Das Ergebnis muss JSON-serialisierbar sein. Python weist eine Koroutine oder einen Generator mit einer klaren Meldung zurück, weil Skripte synchron laufen.

TypeScript / JavaScript

// input ist das übergebene JSON; der letzte Ausdruck ist das Ergebnis.
const names = (input as { names?: string[] })?.names ?? [];

({
  count: names.length,
  upper: names.map((n) => n.toUpperCase()),
});

TypeScript wird vor der Auswertung von seinen Typen befreit – Typen werden also entfernt, nicht geprüft. Ein Typfehler ist damit kein Laufzeitfehler, ein echter Laufzeitfehler schon.

Python

# input ist das übergebene JSON.
names = (input or {}).get("names", [])

result = {"count": len(names), "upper": [n.upper() for n in names]}

Die vollen Python-Builtins stehen zur Verfügung, und ein breiter Teil der Standardbibliothek ist fest im Interpreter eingefroren. Drittanbieter-Pakete sind es nicht – es gibt keinen pip-Schritt und zur Installationszeit kein Netzwerk.

Einem Skript Netzwerkzugriff geben

Ein Skript startet mit leerer Egress-Allowlist, und eine leere Allowlist bedeutet: jede ausgehende Anfrage wird abgewiesen. Du öffnest eine Lücke, indem du im Quellcode selbst deklarierst, welche Workspace-Ressource das Skript braucht:

// resource: billing_api

Python darf beide Kommentarformen verwenden – # resource: billing_api funktioniert genauso. Der Marker muss der ganze Kommentar sein; eine angehängte //-Notiz nach dem Namen wird abgeschnitten, und wiederholte Namen werden zusammengefasst.

Beim Start schlägt der Server jeden deklarierten Namen unter den Ressourcen deines Workspace nach, entschlüsselt dessen Secret und leitet daraus die Autoritäten ab, die diese Ressource freischaltet:

• Eine Ressource, deren Konfiguration ein base_url, url oder endpoint trägt, schaltet genau dieses Schema, diesen Host und diesen Port frei – eine https://-Ressource lässt sich also nicht auf Klartext gegen denselben Host herabstufen.
• Eine Ressource mit host (und optional port) schaltet diesen Host und Port frei.

Mehr ist nicht erreichbar. Jede Anfrage wird zusätzlich gegen den SSRF-Klassifizierer geprüft – private, Loopback-, Link-Local- und Cloud-Metadaten-Adressen sind gesperrt – und die Adresse wird nach dieser Prüfung festgenagelt, sodass eine DNS-Antwort sich zwischen Prüfung und Verbindung nicht mehr ändern kann.

Im Skript ist Egress ein expliziter Aufruf, keine allgegenwärtige Fähigkeit:

Sprache	Anfrage stellen	Gebundene Ressource lesen
JavaScript / TypeScript	scHttp.request(method, url, { headers, body }) oder der fetch-Ersatz über denselben Weg	scResource(name)
Python	sc_http	sc_resource

Eine nicht existierende Ressource zu deklarieren lässt den Lauf scheitern

Passt der Name im Marker zu keiner Ressource desselben Workspace, scheitert der Lauf sofort mit „Script declares resource ‘…’, but no resource with that name exists in this workspace”. Gemeint ist der Name der Ressource, nicht ihr Slug oder ihre Id. Siehe Eine Custom-Verbindung anlegen zum Anlegen und Secrets in der Benutzeroberfläche verwalten dazu, wo das Credential liegt.

Zwei Datenbanken, die ein eigenständiges Skript nie binden darf

Ein eigenständiges Skript hat weder App- noch Workflow-Kontext und kann deshalb die mandantenbezogene Rolle nicht auflösen, über die die eingebaute App-Datenbank und die verwaltete Workflow-Datenbank isoliert sind. Beide zu binden wird abgewiesen, mit einem Hinweis darauf, wo es doch geht – aus einer App heraus oder aus einem Workflow, dessen Namespace darauf liegt. Das ist Absicht: ein Rückfall auf das gemeinsame Plattform-Credential würde Mandantengrenzen überschreiten.

Allgemeiner gilt: eine Ressourcen-Bindung gewährt Netzwerk-Reichweite, keine Datenbank-Reichweite. Ein eigenständiges Skript hat überhaupt keine Datenbank-Fähigkeit; die Datenbank-Aufrufe existieren in der Sandbox, antworten aber immer mit „this run has no DB capability”. Brauchst du SQL, nimm einen Workflow mit db_query/db_execute-Nodes oder eine gebundene Code-Node.

Ausführen und das Ergebnis lesen

1. Nutze im Vollbild-Editor das Panel Skript ausführen auf der rechten Seite.

2. Trage ein JSON-Objekt in Eingabe (JSON) ein – daraus wird die globale input. Lass {} stehen, wenn das Skript nichts erwartet. Ungültiges JSON wird abgewiesen, bevor überhaupt etwas gestartet wird.

3. Wähle Ausführen. Der Start kehrt sofort mit einer Lauf-Id zurück und das Panel beginnt zu pollen; das Skript selbst läuft im Hintergrund zu Ende.

4. Beobachte Letzte Läufe. Jede Zeile zeigt Status und Zeitpunkt und führt zur vollständigen Lauf-Detailansicht. Ein gescheiterter Lauf trägt den Grund direkt in der Zeile.

Die Eingabe wird direkt an den Interpreter übergeben und nie gespeichert – am Lauf festgehalten werden nur die Tatsache, dass eine Eingabe vorlag, sowie die Namen der vom Skript deklarierten Ressourcen. Damit kannst du gefahrlos ein Einmal-Token oder eine Kundenkennung übergeben, ohne dass es im Laufverlauf landet.

Zwei Ausführungsflächen, eine davon ohne Funktion

Wählst du eine Zeile im Board Skripte aus, öffnet sich eine Peek-Schublade mit einem Testlauf-Bereich für Kommandozeilenargumente und Standardeingabe. Dieser Bereich ist die Vorschau auf eine Fläche, die es noch nicht gibt – seine Schaltfläche ist deaktiviert. Nutze für einen echten Lauf das Panel Skript ausführen im Vollbild-Editor oder den Startdialog weiter unten.

Das Skript von woanders aufrufen

Das Editor-Panel ist nur der nächstliegende Weg. Dasselbe Skript lässt sich von vier weiteren Stellen aus starten, und jede hat ihren eigenen Grund.

Aus einem Workflow

Füge eine code-Node hinzu, stelle ihren Modus auf Script und wähle das Skript aus der Workspace-Liste. Die Engine lädt Quellcode und Sprache dieses Skripts in die Node, bevor sie läuft.

So bekommst du ein Skript auf einen Zeitplan: Ein Zeitplan kann kein Skript direkt ansprechen, aber ein Workflow kann einen Schedule-Trigger tragen, und seine Code-Node kann das Skript referenzieren. Siehe Deinen ersten Workflow erstellen und Einen Zeitplan einrichten.

Denk an den Substrat-Unterschied aus dem Hinweis am Seitenanfang: Eine Code-Node ohne Ressourcen-Bindungen führt dein Skript in einem Docker-Container ohne Netzwerk aus – dort existiert scHttp nicht.

Aus dem Startdialog

Wähle Run starten, wo immer es angeboten wird, und dann den Reiter Script. Skript auswählen, optional JSON-Eingabe angeben, starten – du landest auf der Lauf-Detailseite. Das ist derselbe Start wie im Editor-Panel, nur ohne das Skript zu öffnen.

Über die API

curl -X POST https://supacloud.example.com/api/scripts/<script-id>/run \
  -H "Authorization: Bearer <session-or-API-token>" \
  -H "Content-Type: application/json" \
  -d '{ "input": { "names": ["ada"] } }'

Die Antwort trägt run_id, den anfänglichen status, Id und Slug des Skripts sowie bound_resources – die Namen, die der Server aus deinen Markern aufgelöst hat. Das ist der schnellste Weg, eine Bindung zu bestätigen. Frage GET /api/scripts/<script-id>/runs für das Ergebnis ab.

Für ein Skript gibt es keine unauthentifizierte Trigger-URL. Brauchst du eine, lege das Skript in einen Workflow und gib dem Workflow einen Webhook-Trigger.

Von einem Agenten

Ein Agent kann ein Skript über das MCP-Tool script.run ausführen und spricht es dabei per Id oder Slug an. Das ist bewusst schwerer erreichbar als die Lese-Tools: Es braucht die eigene Berechtigung supacloud.script.run, die aus der Ops-Stufe herausgeschnitten und nicht in ihr enthalten ist, und es zählt gegen das Ops-Ratenbudget des Agenten.

Ein Agentprofil kann zusätzlich mit einer Skript-Allowlist einschränken – einer Liste von Slugs, die das Profil ausführen darf. Keine Liste bedeutet jedes Skript im Workspace, eine leere Liste bedeutet keines. Siehe Berechtigungen und MCP-Tool-Stufen.

Im Audit-Log landen nur die Tatsache, dass eine Eingabe vorlag, und die Namen der gebundenen Ressourcen – nie die Eingabe selbst.

Änderungen über Versionen verfolgen

Jedes Speichern, das den Quellcode ändert, sichert die vorherige Fassung als Version. Der Editor zeigt also immer den aktuellen Code, und der Verlauf hält alles davor. Öffne den Reiter Versionen, um sie neueste zuerst aufzulisten, den Quellcode einer Fassung anzusehen oder eine Fassung gegen den aktuellen Stand zu diffen. Versionen, die von Repo-Sync oder einem anderen Systemweg geschrieben wurden, tragen keinen Autor. Wird ein Skript gelöscht, verschwindet sein Verlauf mit ihm.

Das Löschen ist außerdem blockiert, solange eine Workflow-Code-Node das Skript noch referenziert – die Fehlermeldung nennt die Workflows, damit du sie zuerst lösen kannst.

Grenzen

Schranke	Wert
Laufzeitbudget pro Lauf	30 Sekunden, fest – nicht pro Skript einstellbar
Speicher pro Lauf	128 MiB, harte Obergrenze 256 MiB
Quellcode-Größe	1 MiB, und er darf nicht leer sein
Sprache, Eingabe und Quellcode zusammen	8 MiB pro Start
Name	200 Zeichen
Slug	1–63 Zeichen, Kleinbuchstaben, Ziffern und Bindestriche

Für den Rückgabewert eines Skripts gibt es keine eigene Schranke; er ist durch den Speicher pro Lauf begrenzt. Ein Lauf, der sein Budget überschreitet, endet als failed und wird als abgelaufen markiert.

Eine Sprache ist nur nutzbar, wenn deine Instanz ihren Interpreter bereitstellt

Die drei Interpreter sind gebaute Artefakte, die mit dem Deployment ausgeliefert werden – sie sind nicht Teil der Anwendungsbinary. Fehlt der Interpreter einer Sprache, degradiert nur diese eine Sprache – alles andere funktioniert weiter –, und ein Lauf scheitert mit „script runtime for ‘…’ is not provisioned”.

Nichts im Editor blendet eine nicht bereitgestellte Sprache aus. Auf einer selbst gehosteten Instanz kannst du also ein Python-Skript anlegen und starten, das nie erfolgreich sein kann. Triffst du auf diese Meldung, ist die Behebung eine Betreiberaufgabe: die Interpreter werden unter SUPACLOUD_SCRIPT_RUNTIME_DIR bereitgestellt. Auf einem Deployment, das Wasm-Arbeit an eine Runner-Flotte verteilt, muss jeder Runner zusätzlich die Sprachen ausweisen, die er bereitgestellt hat – siehe Einen Runner sicher einrichten.

Siehe auch

• Runs und Tasks – wie ein Skriptlauf in das gemeinsame Run-Modell passt.
• Eine Custom-Verbindung anlegen – die Ressource anlegen, die ein Skript für Netzwerkzugriff bindet.
• Ein Marktplatz-Paket veröffentlichen – ein Skript zusammen mit dem Workflow oder der App ausliefern, die es nutzt.
• Referenz der Web-Terminal-Befehle