SDK Python cho sandbox trong 5 phút: từ pip install eqvps đến lần chạy đầu tiên

Hướng dẫn này đưa bạn từ con số không đến một sandbox chạy được bằng Python. Bạn sẽ khởi động một microVM Firecracker cô lập, chạy code trong đó, cài một gói, chuyển file vào và ra, rồi chạy một việc dài ở chế độ nền. Mỗi bước chỉ là vài dòng để dán.

Bạn cần Python 3.8 trở lên và một tài khoản EQVPS. SDK không có phụ thuộc nào.

1. Lấy token

Sandbox được trả từ số dư tài khoản, nên SDK cần token tài khoản. Trang kết nối tài khoản chỉ ra ba cách lấy token: bảng điều khiển, API hoặc máy chủ MCP. Sau đó đặt nó vào biến môi trường:

export EQVPS_API_KEY="your-token"

Chưa có số dư? Không sao. Lần đầu một tài khoản mới tạo sandbox mà không đủ số dư, tài khoản đó nhận $1 tín dụng sandbox, có hiệu lực 14 ngày.

2. Cài SDK

pip install eqvps

3. Khởi động sandbox và chạy code

Lưu đoạn này thành hello.py rồi chạy:

from eqvps import Sandbox

with Sandbox.create(tariff="small") as sb:
    print(sb.id)
    r = sb.run("import platform; print(platform.python_version())")
    print(r.exit_code, r.stdout)

Bạn sẽ thấy id của sandbox (sb_ và thêm 24 ký tự), rồi đến 0 3.12.x. Sandbox khởi động trong khoảng một giây, chạy code và bị xóa khi khối with kết thúc.

Một vài điều nên biết về kết quả:

• r.ok là true khi mã thoát bằng 0 và lệnh không bị quá thời gian chờ;
• mã thoát khác 0 không phải exception, nên hãy tự kiểm tra r.ok;
• stdout và stderr mỗi luồng giới hạn 1 MiB, và r.truncated cho biết đầu ra có bị cắt hay không.

4. Cài gói và chạy lệnh shell

Trong sandbox, bạn là root trên một hệ Linux nhỏ có Python, Node.js, git và curl. exec chạy bất kỳ lệnh shell nào:

from eqvps import Sandbox

with Sandbox.create(tariff="small") as sb:
    sb.exec("pip install --quiet requests", timeout=55)
    r = sb.run("import requests; print(requests.get('https://example.com').status_code)")
    print(r.stdout)   # 200

Thời gian chờ mặc định là 30 giây, và một lệnh gọi đồng bộ kéo dài tối đa 55 giây. Những lần cài đặt lớn nên đưa vào tác vụ nền (bước 6).

5. Chuyển file vào và ra

from eqvps import Sandbox

with Sandbox.create() as sb:
    sb.upload("/root/data.csv", "a,b\n1,2\n3,4\n")
    sb.run("""
import csv
rows = list(csv.DictReader(open('/root/data.csv')))
open('/root/sum.txt', 'w').write(str(sum(int(r['b']) for r in rows)))
""")
    print(sb.download_text("/root/sum.txt"))   # 6

Đường dẫn phải là tuyệt đối. Mỗi lần truyền giới hạn 5 MB; download trả về byte, download_text trả về chuỗi.

6. Chạy tác vụ dài ở chế độ nền

Truyền background=True và bạn nhận ngay một tác vụ thay vì phải chờ. Tác vụ này không có giới hạn 55 giây:

from eqvps import Sandbox

with Sandbox.create(tariff="standard") as sb:
    task = sb.exec("for i in 1 2 3 4 5; do echo step $i; sleep 20; done", background=True)
    result = task.wait(on_output=lambda out, err: print(out, end=""))
    print(result.state, result.exit_code)   # done 0

task.wait() kiểm tra mỗi 2 giây và in đầu ra mới ngay khi có. Bạn cũng có thể tự gọi task.logs(), hoặc task.kill() để dừng nó. Khi tác vụ còn chạy, sandbox không bị xóa vì không hoạt động.

Tốn bao nhiêu

Mỗi khối with ở trên chỉ sống vài giây và bị tính mức tối thiểu 60 giây. Trên small là $0.00055 mỗi khối, nên cả năm ví dụ cộng lại khoảng một phần ba cent. Giá của mọi gói, chế độ lưu trữ lâu dài và hạn mức chi tiêu có trong giới hạn và tính phí sandbox.

Khi có lỗi

Lỗi từ API là exception mà bạn có thể bắt:

from eqvps import Sandbox, InsufficientBalanceError, RateLimitError

try:
    with Sandbox.create() as sb:
        print(sb.run("print(1)").stdout)
except InsufficientBalanceError:
    print("Top up the balance")
except RateLimitError as e:
    print("Too many at once, retry in", e.retry_after)

SDK đã tự thử lại các phản hồi 429 và 503 tối đa ba lần khi máy chủ cho biết cần chờ bao lâu. Đủ 11 lớp lỗi có trong tài liệu tham khảo SDK.

Bước tiếp theo

• Các bước tương tự bằng JavaScript: SDK TypeScript cho sandbox trong 5 phút.
• Để một mô hình AI viết code và chạy ở đây: tác vụ agent đầu tiên trong sandbox.
• Các gói, tín dụng dùng thử và những gì có trong sandbox: trang sandbox.