샌드박스 API 레퍼런스: Python과 TypeScript SDK

SDK는 샌드박스 REST API를 얇게 감싼 것입니다. 요청을 직접 만드는 일, 플랫폼이 바쁠 때 재시도하는 일, 코드가 예외를 던졌을 때 샌드박스 삭제를 잊는 일, 이 세 가지를 덜어 줍니다. 이 페이지의 내용은 두 패키지의 0.2.0 버전에 해당합니다.

샌드박스를 만들어 본 적이 없다면 5분 연결 가이드에서 먼저 토큰을 받으세요. 샌드박스가 무엇이고 안에 무엇이 있는지는 샌드박스에 있습니다.

설치와 설정

pip install eqvps          # Python 3.8+
npm i @eqvps/sdk           # Node.js 18+, Deno, Bun
export EQVPS_API_KEY=...   # your EQVPS account token

두 언어로 쓴 같은 프로그램: 샌드박스를 만들고, 코드를 실행하고, 삭제합니다.

from eqvps import Sandbox

with Sandbox.create(tariff="small") as sb:
    r = sb.run("print(2 + 2)")
    print(r.exit_code, r.stdout)   # 0 4

import { Sandbox } from "@eqvps/sdk";

await Sandbox.with({ tariff: "small" }, async (sb) => {
  const r = await sb.run("print(2 + 2)");
  console.log(r.exit_code, r.stdout); // 0 4
});

샌드박스 만들기와 찾기

Sandbox.create(...)는 샌드박스를 시작하며, 보통 약 1초가 걸립니다. Python은 키워드 인수를, TypeScript는 옵션 객체 하나를 받습니다.

Sandbox.connect(id)는 기존 샌드박스에 연결합니다. 보통 어제 만든 영구 샌드박스입니다. Sandbox.list()는 계정의 모든 샌드박스(실행 중, 일시 중지)를 반환합니다.

속성: id(sb_ + 16진수 24자), mode, tariff, state(running, starting, paused, pausing, resuming, deleting, deleted), env_keys / envKeys(이름만, 값은 절대 돌려주지 않음), info(원본 객체). refresh()로 다시 불러옵니다.

kill()은 샌드박스를 삭제하고 과금을 멈춥니다. 이미 없는 샌드박스에 호출해도 오류가 아닙니다.

코드 실행

run(code, language="python", timeout=30)은 stdin으로 코드를 Python 3.12, Node.js 22, bash("python", "node", "bash")에 전달합니다. exec(command, cwd=None, stdin=None, timeout=30)은 셸 명령을 실행합니다. 문자열은 bash -lc를 거치고, 리스트는 셸 없이 argv로 실행됩니다.

둘 다 ExecResult를 반환합니다:

동기 호출은 최대 55초까지입니다. 두 메서드 모두 그 호출에만 적용되는 env도 받으며, 생성 시 설정한 값을 덮어씁니다.

긴 작업: 백그라운드 작업

background=True(TypeScript: { background: true })를 넘기면 바로 Task를 받습니다. 55초 제한이 없고 샌드박스 수명이 끝날 때까지 실행할 수 있습니다. 샌드박스당 최대 8개 작업입니다.

task = sb.exec("cd /root/app && python3 -m pytest -q", background=True)
result = task.wait(on_output=lambda out, err: print(out, end=""))
print(result.state, result.exit_code)   # done 0

const task = await sb.exec("cd /root/app && npm test", { background: true });
const result = await task.wait({ onOutput: (out) => process.stdout.write(out) });

wait가 자신의 타임아웃에 도달하면 SandboxTimeoutError를 던지지만 작업은 계속 실행됩니다. 실행 중인 작업이 있으면 임시 샌드박스가 무활동으로 삭제되지도 않습니다.

파일과 사용량

upload(path, content, mode=None)는 절대 경로에 파일을 쓰고 크기를 반환합니다. download(path)는 바이트를, download_text(path) / downloadText(path)는 문자열을 반환합니다. 한 번의 전송은 5 MB로 제한됩니다.

usage()는 실행 초, 사용한 CPU 초, 송신 바이트, 시간당 가격, billed_usd, estimated_total_usd를 반환합니다. tariffs()는 키가 필요 없는 일반 함수로 현재 가격과 한도를 반환합니다. 과금 규칙은 샌드박스 한도와 과금에 있습니다.

오류

모든 API 오류는 EqvpsError의 하위 클래스이며 status(HTTP), code(고정 문자열), body를 가집니다. 서버가 보내면 retry_after / retryAfter가 채워집니다.

429의 대부분은 두 가지 한도에서 옵니다. 한 계정은 동시에 2개의 명령을 실행하고 최대 20개의 샌드박스를 보유할 수 있습니다. 서버가 대기 시간을 알려 주면 SDK가 재시도하고, 세 번 실패하면 예외가 발생합니다.

SDK가 필요 없을 때

HTTP 클라이언트가 있는 언어라면 어떤 언어로든 API를 직접 호출할 수 있습니다. 엔드포인트는 https://eqvps.com/openapi.json의 OpenAPI 파일에 있습니다. Claude, Cursor 등 MCP 클라이언트에서 동작하는 에이전트는 코드조차 필요 없습니다. MCP 서버에 같은 샌드박스 도구가 있습니다. 동작하는 모습만 보고 싶다면 샌드박스 페이지에 요금제와 신규 계정용 $1 체험이 있습니다.