Sandboxes

Was eine Sandbox ist

Eine kleine Linux-Maschine, die du per API oder MCP erstellst, ein paar Sekunden oder ein paar Tage nutzt und wieder löschst. Ausgehendes Internet funktioniert (pip install, npm install, git clone). Es gibt keine eingehenden Ports und kein SSH: Befehle und Dateien laufen über die API. Drin: Python 3.12 mit pip, Node.js 22 mit npm, bash, git und curl.

Zwei Modi

Tarife

Du zahlst für vCPU und RAM des gewählten Tarifs: $0.040 pro vCPU-Stunde und $0.013 pro GiB-Stunde. Aktuelle Preise ohne Token: GET /sandboxes/tariffs.

Grenzen, die du kennen solltest

Ein Befehl läuft bis zu 55 Sekunden; längere Jobs laufen als Hintergrundaufgaben, deren Ergebnis du abfragst. Dateien bis 5 MB pro Anfrage, größere (bis 2 GB) über einmalige Download- und Upload-Links. Ein Konto kann bis zu 20 Sandboxes und 2 Befehle gleichzeitig betreiben.

Umgebungsvariablen

Übergeben Sie Secrets und Einstellungen als env. Beim Erstellen gesetzt, gelten sie für jeden Befehl in der Sandbox; bei exec oder run gesetzt, gelten sie nur für diesen Aufruf und überschreiben die Sandbox-Werte. Bis zu 64 Variablen, 32 KB pro Wert und 64 KB insgesamt. Werte werden verschlüsselt gespeichert, nie von der API zurückgegeben und nicht protokolliert: Antworten zeigen nur die Namen (env_keys).

API=https://api.eqvps.com/api/v1/eqvps
AUTH="Authorization: Bearer $EQVPS_API_KEY"

# env for the whole sandbox (only the names come back, as env_keys)
SB=$(curl -s -X POST $API/sandboxes -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"tariff":"small","env":{"DB_URL":"postgres://user:pass@db/app","MODE":"test"}}' | jq -r .id)

# env for one call, merged over the sandbox env
curl -s -X POST $API/sandboxes/$SB/exec -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"command":"echo $MODE $RUN_ID","env":{"RUN_ID":"42"}}'

Ausgabenlimit

Standardmäßig haben Sandboxes kein Ausgabenlimit. Sie können im Dashboard oder mit PUT /sandboxes/budget ein Tages- und ein Monatslimit setzen. Ist ein Limit erreicht, erhalten neue Sandboxes 429 budget_exceeded, laufende temporäre werden gelöscht und dauerhafte mit erhaltener Festplatte pausiert. Sie laufen weiter, sobald Sie das Limit erhöhen oder ein neuer Tag bzw. Monat beginnt (UTC).

# daily cap $5, monthly cap $50 (null = no cap)
curl -s -X PUT $API/sandboxes/budget -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"daily_usd":5,"monthly_usd":50}'

# spent today / this month and when the caps reset (UTC)
curl -s $API/sandboxes/budget -H "$AUTH"

Schnellstart: MCP (Claude Code, Cursor und andere Clients)

Verbinde den MCP-Server einmal und sag dem Agenten dann einfach, was er tun soll. Sandbox-Tools: create_sandbox, run_code, exec_command, get_task, kill_task, get_upload_url, get_download_url, list_sandboxes, get_sandbox, kill_sandbox, sandbox_pricing.

claude mcp add --transport http eqvps https://mcp.eqvps.com/mcp \
  --header "Authorization: Bearer $EQVPS_API_KEY"

Erstelle eine kleine Sandbox, führe in Python print(2 + 2) aus, zeig mir die Ausgabe und lösch die Sandbox.

Schnellstart: REST aus Python und Node.js

Keine zusätzlichen Pakete nötig. Leg dein Token in die Umgebungsvariable EQVPS_API_KEY (wie du eins bekommst, steht unter „Konto verbinden“).

# first_sandbox.py — Python 3.8+, standard library only
import json, os, urllib.request

API = "https://api.eqvps.com/api/v1/eqvps"
KEY = os.environ["EQVPS_API_KEY"]

def call(method, path, body=None):
    req = urllib.request.Request(API + path, method=method,
        data=json.dumps(body).encode() if body is not None else None,
        headers={"Authorization": "Bearer " + KEY,
                 "Content-Type": "application/json", "Accept": "application/json"})
    with urllib.request.urlopen(req, timeout=90) as r:   # HTTPError on 401/402/…
        return json.loads(r.read() or b"{}")

sb = call("POST", "/sandboxes", {"tariff": "small"})
try:
    r = call("POST", f"/sandboxes/{sb['id']}/run",
             {"language": "python", "code": "print(2 + 2)"})
    print(r["exit_code"], r["stdout"])                    # 0 4
finally:
    call("DELETE", f"/sandboxes/{sb['id']}")

// first_sandbox.mjs — Node.js 18+ (built-in fetch), run: node first_sandbox.mjs
const API = "https://api.eqvps.com/api/v1/eqvps";
const KEY = process.env.EQVPS_API_KEY;

async function call(method, path, body) {
  const r = await fetch(API + path, {
    method,
    headers: { Authorization: `Bearer ${KEY}`, "Content-Type": "application/json", Accept: "application/json" },
    body: body ? JSON.stringify(body) : undefined,
  });
  const data = await r.json();
  if (!r.ok) throw new Error(`${r.status} ${data.error ?? ""} ${data.message ?? ""}`);
  return data;
}

const sb = await call("POST", "/sandboxes", { tariff: "small" });
try {
  const r = await call("POST", `/sandboxes/${sb.id}/run`, { language: "node", code: "console.log(2 + 2)" });
  console.log(r.exit_code, r.stdout); // 0 4
} finally {
  await call("DELETE", `/sandboxes/${sb.id}`);
}

SDK für Python und TypeScript

Lieber eine Bibliothek? Die Pakete für Python und TypeScript machen dieselben REST-Aufrufe, wiederholen 429 und 503 selbst und löschen die Sandbox immer am Ende des Blocks. Installation und Beispiel:

# pip install -U eqvps       https://pypi.org/project/eqvps/  (0.2.0+ for env)
# "eqvps sandbox create" = Sandbox.create() here · create_sandbox in MCP · POST /sandboxes in REST (no CLI)
from eqvps import Sandbox

# EQVPS_API_KEY from the environment; env = secrets for your code, stored encrypted
with Sandbox.create(tariff="small", env={"DB_URL": "postgres://user:pass@db/app"}) as sb:
    r = sb.run("print(2 + 2)")
    print(r.stdout, r.exit_code)             # "4\n" 0
    sb.upload("/root/data.csv", "a,b\n1,2\n")
    print(sb.exec("wc -l /root/data.csv").stdout)
    print(sb.exec("echo $RUN_ID", env={"RUN_ID": "42"}).stdout)   # env for one call
# the sandbox is deleted when the block exits, also on errors

// npm i @eqvps/sdk@latest   https://www.npmjs.com/package/@eqvps/sdk  (0.2.0+ for env)
import { Sandbox } from "@eqvps/sdk";

// EQVPS_API_KEY from the environment; env = secrets for your code, stored encrypted
await Sandbox.with({ tariff: "small", env: { DB_URL: "postgres://user:pass@db/app" } }, async (sb) => {
  const r = await sb.run("print(2 + 2)");
  console.log(r.stdout, r.exit_code);                    // "4\n" 0
  console.log((await sb.exec("echo $RUN_ID", { env: { RUN_ID: "42" } })).stdout); // env for one call
});                                                       // deleted afterwards, also on errors

Konto verbinden: Token, Konfiguration, erste Sandbox, Guthaben →