Sandbox

Sandbox là gì

Một máy Linux nhỏ mà bạn tạo qua API hoặc MCP, dùng vài giây hay vài ngày rồi xóa. Internet chiều ra hoạt động (pip install, npm install, git clone). Không có cổng chiều vào và không có SSH: lệnh và tệp đi qua API. Bên trong: Python 3.12 kèm pip, Node.js 22 kèm npm, bash, git và curl.

Hai chế độ

Gói

Bạn trả cho vCPU và RAM của gói đã chọn: $0.040 mỗi vCPU-giờ và $0.013 mỗi GiB-giờ. Giá hiện tại, không cần token: GET /sandboxes/tariffs.

Giới hạn nên biết

Một lệnh chạy tối đa 55 giây; việc dài hơn chạy thành tác vụ nền và bạn hỏi kết quả. Tệp tới 5 MB mỗi yêu cầu, tệp lớn hơn (tới 2 GB) qua liên kết tải xuống và tải lên dùng một lần. Một tài khoản chạy được tới 20 sandbox và 2 lệnh cùng lúc.

Biến môi trường

Truyền bí mật và cấu hình qua env. Đặt khi tạo thì áp dụng cho mọi lệnh trong sandbox; đặt trong exec hoặc run thì chỉ áp dụng cho lần gọi đó và ghi đè giá trị của sandbox. Tối đa 64 biến, 32 KB mỗi giá trị và tổng 64 KB. Giá trị được lưu mã hóa, API không bao giờ trả về và không ghi vào log: phản hồi chỉ hiển thị tên (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"}}'

Giới hạn chi tiêu

Mặc định sandbox không có giới hạn chi tiêu. Bạn có thể đặt mức trần theo ngày và theo tháng trong bảng điều khiển hoặc bằng PUT /sandboxes/budget. Khi đạt mức trần, sandbox mới nhận 429 budget_exceeded, sandbox tạm thời đang chạy bị xóa và sandbox lâu dài được tạm dừng, ổ đĩa vẫn được giữ. Chúng chạy tiếp khi bạn tăng mức trần hoặc sang ngày hay tháng mới (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"

Bắt đầu nhanh: MCP (Claude Code, Cursor và các client khác)

Kết nối máy chủ MCP một lần, sau đó chỉ cần nói với tác tử bằng lời của bạn. Công cụ sandbox: 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"

Tạo một sandbox nhỏ, chạy print(2 + 2) bằng Python, cho tôi xem kết quả rồi xóa sandbox.

Bắt đầu nhanh: REST từ Python và Node.js

Không cần gói bổ sung. Đặt token của bạn vào biến môi trường EQVPS_API_KEY (cách lấy token: “Kết nối tài khoản”).

# 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 cho Python và TypeScript

Thích dùng thư viện? Các gói Python và TypeScript gọi cùng các API REST, tự thử lại khi gặp 429 và 503 và luôn xóa sandbox khi khối lệnh kết thúc. Cài đặt và ví dụ:

# 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

Kết nối tài khoản: token, cấu hình, sandbox đầu tiên, số dư →