eqvps 0.1.0__tar.gz

eqvps-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EQVPS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

eqvps-0.1.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: eqvps
+Version: 0.1.0
+Summary: EQVPS code sandboxes: isolated Firecracker microVMs for AI agents, billed per second from your prepaid balance
+License: MIT
+Project-URL: Homepage, https://eqvps.com
+Project-URL: Documentation, https://eqvps.com/en/docs/sandboxes
+Project-URL: API, https://eqvps.com/openapi.json
+Keywords: sandbox,firecracker,microvm,ai-agents,code-execution,eqvps
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# eqvps — code sandboxes for AI agents (Python)
+
+Isolated **Firecracker microVMs** in ~1 second: Linux with Python 3.12 + pip, Node.js 22 + npm, bash, git and curl (3–40 GB disk by tariff), internet egress (pip/npm install and git clone work), no inbound ports.
+Billed per second from your prepaid [EQVPS](https://eqvps.com) balance — the same balance as VPS, no subscription. Zero dependencies, Python 3.8+.
+
+```bash
+pip install eqvps
+```
+
+Docs: [Sandboxes](https://eqvps.com/en/docs/sandboxes) · [Connecting your account (token, config, balance)](https://eqvps.com/en/docs/connect) · [OpenAPI](https://eqvps.com/openapi.json)
+
+```python
+from eqvps import Sandbox
+
+with Sandbox.create(tariff="small") as sb:          # EQVPS_API_KEY from the environment
+    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.download_text("/root/data.csv"))
+# deleted when the block exits — also on exceptions
+```
+
+## API key
+Any EQVPS account Bearer token (`POST https://api.eqvps.com/api/v1/eqvps/auth/register`, the MCP `register_account` tool, or your dashboard). Pass `api_key=` or set `EQVPS_API_KEY`. Fund the balance with crypto (`topup_balance`).
+
+## Modes and prices
+| | ephemeral (default) | persistent |
+|---|---|---|
+| billing | per second, min 60 s | per started hour; a month costs at most 730 h −25 % |
+| lifetime | idle timeout (default 300 s, max 3600), `ttl` ≤ 24 h | `ttl` ≤ 30 days, survives host maintenance |
+| empty balance | can't create (402) | paused (memory+disk snapshot, not billed), resumes after top-up; snapshot kept 14 days |
+
+| tariff | vCPU | RAM | disk | $/hour | persistent month max |
+|---|---|---|---|---|---|
+| `micro` | 0.25 | 512 MB | 3 GB | $0.0165 | $9.03 |
+| `small` | 0.5 | 1 GB | 5 GB | $0.033 | $18.07 |
+| `standard` | 1 | 2 GB | 10 GB | $0.066 | $36.14 |
+| `plus` | 2 | 4 GB | 15 GB | $0.132 | $72.27 |
+| `pro` | 4 | 8 GB | 20 GB | $0.264 | $144.54 |
+| `max` | 8 | 16 GB | 40 GB | $0.528 | $289.08 |
+
+Rates: vCPU $0.040/h + RAM $0.013/GiB-h. Live: `tariffs()`. Heavy installs (torch) and builds: `plus` or bigger. If the host is busy, creating a big tariff raises `CapacityError` (503, `retry_after`).
+
+```python
+sb = Sandbox.create(mode="persistent", tariff="micro", ttl=7 * 86400)
+sid = sb.id                       # keep it
+sb = Sandbox.connect(sid)         # reattach later
+sb.kill()
+```
+
+## API
+- `Sandbox.create(mode, tariff, idle_timeout, ttl)` · `Sandbox.connect(id)` · `Sandbox.list()` · `eqvps.tariffs()`
+- `sb.run(code, language="python"|"node"|"bash", timeout=30)` → `ExecResult(exit_code, stdout, stderr, timed_out, truncated, duration_ms, ok)`
+- `sb.exec("cmd" | ["argv"], cwd=None, stdin=None, timeout=30)` → `ExecResult`
+- `sb.upload(path, bytes|str, mode=None)` · `sb.download(path) -> bytes` · `sb.download_text(path)` (≤ 5 MB per file)
+- `sb.usage()` → running seconds, CPU used, egress, `billed_usd`, `estimated_total_usd` · `sb.refresh()` · `sb.kill()`
+
+Limits: command timeout ≤ 55 s per call (start long jobs with `nohup … &` and poll), output ≤ 1 MiB per stream, files ≤ 5 MB per transfer, 20 concurrent sandboxes and 2 concurrent commands per account.
+
+## Long jobs — background tasks (no 55 s limit)
+```python
+task = sb.exec("python3 train.py", background=True)          # returns at once with task.id
+result = task.wait(on_output=lambda out, err: print(out, end=""), poll_interval=5)
+print(result.state, result.exit_code)                        # done 0  (also: failed | killed | timeout)
+
+out, err = task.logs()      # or poll yourself: only the new output since the last call
+task.kill()                 # stop it (and its child processes)
+sb.task(task_id)            # reattach later, e.g. from another process
+```
+A task may run until the sandbox's maximum lifetime (`timeout=` to cap it). While it runs the sandbox is not idle-deleted, and it is billed like any running time. Up to 8 tasks per sandbox; 8 MiB of output per stream is retained (older output is dropped).
+
+## Errors
+All inherit `EqvpsError(status, code, message, retry_after)`: `AuthenticationError` 401 · `InsufficientBalanceError` 402 · `NotFoundError` 404 · `SandboxPausedError` 409 · `SandboxDeletedError` 410 · `FileTooLargeError` 413 · `ValidationError` 422 · `RateLimitError` 429 · `CapacityError` 503 · `SandboxTimeoutError` (HTTP timeout). 429/503 with `Retry-After` are retried automatically (`max_retries=3`). A non-zero exit code or a command timeout is **not** an exception — check `result.ok` / `result.timed_out`.
+
+```python
+from eqvps import Sandbox, InsufficientBalanceError, RateLimitError
+try:
+    sb = Sandbox.create()
+except InsufficientBalanceError:
+    print("top up your EQVPS balance")
+except RateLimitError as e:
+    print("retry in", e.retry_after, "s")
+```
+
+REST API reference: https://eqvps.com/openapi.json (tag `sandboxes`) · human guide: https://eqvps.com/en/docs/sandboxes

eqvps-0.1.0/README.md

@@ -0,0 +1,86 @@
+# eqvps — code sandboxes for AI agents (Python)
+
+Isolated **Firecracker microVMs** in ~1 second: Linux with Python 3.12 + pip, Node.js 22 + npm, bash, git and curl (3–40 GB disk by tariff), internet egress (pip/npm install and git clone work), no inbound ports.
+Billed per second from your prepaid [EQVPS](https://eqvps.com) balance — the same balance as VPS, no subscription. Zero dependencies, Python 3.8+.
+
+```bash
+pip install eqvps
+```
+
+Docs: [Sandboxes](https://eqvps.com/en/docs/sandboxes) · [Connecting your account (token, config, balance)](https://eqvps.com/en/docs/connect) · [OpenAPI](https://eqvps.com/openapi.json)
+
+```python
+from eqvps import Sandbox
+
+with Sandbox.create(tariff="small") as sb:          # EQVPS_API_KEY from the environment
+    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.download_text("/root/data.csv"))
+# deleted when the block exits — also on exceptions
+```
+
+## API key
+Any EQVPS account Bearer token (`POST https://api.eqvps.com/api/v1/eqvps/auth/register`, the MCP `register_account` tool, or your dashboard). Pass `api_key=` or set `EQVPS_API_KEY`. Fund the balance with crypto (`topup_balance`).
+
+## Modes and prices
+| | ephemeral (default) | persistent |
+|---|---|---|
+| billing | per second, min 60 s | per started hour; a month costs at most 730 h −25 % |
+| lifetime | idle timeout (default 300 s, max 3600), `ttl` ≤ 24 h | `ttl` ≤ 30 days, survives host maintenance |
+| empty balance | can't create (402) | paused (memory+disk snapshot, not billed), resumes after top-up; snapshot kept 14 days |
+
+| tariff | vCPU | RAM | disk | $/hour | persistent month max |
+|---|---|---|---|---|---|
+| `micro` | 0.25 | 512 MB | 3 GB | $0.0165 | $9.03 |
+| `small` | 0.5 | 1 GB | 5 GB | $0.033 | $18.07 |
+| `standard` | 1 | 2 GB | 10 GB | $0.066 | $36.14 |
+| `plus` | 2 | 4 GB | 15 GB | $0.132 | $72.27 |
+| `pro` | 4 | 8 GB | 20 GB | $0.264 | $144.54 |
+| `max` | 8 | 16 GB | 40 GB | $0.528 | $289.08 |
+
+Rates: vCPU $0.040/h + RAM $0.013/GiB-h. Live: `tariffs()`. Heavy installs (torch) and builds: `plus` or bigger. If the host is busy, creating a big tariff raises `CapacityError` (503, `retry_after`).
+
+```python
+sb = Sandbox.create(mode="persistent", tariff="micro", ttl=7 * 86400)
+sid = sb.id                       # keep it
+sb = Sandbox.connect(sid)         # reattach later
+sb.kill()
+```
+
+## API
+- `Sandbox.create(mode, tariff, idle_timeout, ttl)` · `Sandbox.connect(id)` · `Sandbox.list()` · `eqvps.tariffs()`
+- `sb.run(code, language="python"|"node"|"bash", timeout=30)` → `ExecResult(exit_code, stdout, stderr, timed_out, truncated, duration_ms, ok)`
+- `sb.exec("cmd" | ["argv"], cwd=None, stdin=None, timeout=30)` → `ExecResult`
+- `sb.upload(path, bytes|str, mode=None)` · `sb.download(path) -> bytes` · `sb.download_text(path)` (≤ 5 MB per file)
+- `sb.usage()` → running seconds, CPU used, egress, `billed_usd`, `estimated_total_usd` · `sb.refresh()` · `sb.kill()`
+
+Limits: command timeout ≤ 55 s per call (start long jobs with `nohup … &` and poll), output ≤ 1 MiB per stream, files ≤ 5 MB per transfer, 20 concurrent sandboxes and 2 concurrent commands per account.
+
+## Long jobs — background tasks (no 55 s limit)
+```python
+task = sb.exec("python3 train.py", background=True)          # returns at once with task.id
+result = task.wait(on_output=lambda out, err: print(out, end=""), poll_interval=5)
+print(result.state, result.exit_code)                        # done 0  (also: failed | killed | timeout)
+
+out, err = task.logs()      # or poll yourself: only the new output since the last call
+task.kill()                 # stop it (and its child processes)
+sb.task(task_id)            # reattach later, e.g. from another process
+```
+A task may run until the sandbox's maximum lifetime (`timeout=` to cap it). While it runs the sandbox is not idle-deleted, and it is billed like any running time. Up to 8 tasks per sandbox; 8 MiB of output per stream is retained (older output is dropped).
+
+## Errors
+All inherit `EqvpsError(status, code, message, retry_after)`: `AuthenticationError` 401 · `InsufficientBalanceError` 402 · `NotFoundError` 404 · `SandboxPausedError` 409 · `SandboxDeletedError` 410 · `FileTooLargeError` 413 · `ValidationError` 422 · `RateLimitError` 429 · `CapacityError` 503 · `SandboxTimeoutError` (HTTP timeout). 429/503 with `Retry-After` are retried automatically (`max_retries=3`). A non-zero exit code or a command timeout is **not** an exception — check `result.ok` / `result.timed_out`.
+
+```python
+from eqvps import Sandbox, InsufficientBalanceError, RateLimitError
+try:
+    sb = Sandbox.create()
+except InsufficientBalanceError:
+    print("top up your EQVPS balance")
+except RateLimitError as e:
+    print("retry in", e.retry_after, "s")
+```
+
+REST API reference: https://eqvps.com/openapi.json (tag `sandboxes`) · human guide: https://eqvps.com/en/docs/sandboxes

eqvps-0.1.0/eqvps/__init__.py

@@ -0,0 +1,9 @@
+"""EQVPS Python SDK — code sandboxes (Firecracker microVMs) billed from your prepaid EQVPS balance."""
+
+from .sandbox import (  # noqa: F401
+    AuthenticationError, CapacityError, EqvpsError, ExecResult, FileTooLargeError, InsufficientBalanceError,
+    NotFoundError, RateLimitError, Sandbox, SandboxDeletedError, SandboxPausedError, SandboxTimeoutError,
+    ValidationError, tariffs, Task, TaskResult,
+)
+
+__version__ = "0.1.0"

eqvps-0.1.0/eqvps/sandbox.py

@@ -0,0 +1,424 @@
+"""EQVPS code sandboxes — Python SDK (zero dependencies, Python 3.8+).
+
+Isolated Firecracker microVMs for running code, billed per second from your prepaid EQVPS balance.
+
+    from eqvps import Sandbox
+
+    with Sandbox.create() as sb:              # EQVPS_API_KEY from the environment
+        print(sb.run("print(2 + 2)").stdout)  # -> "4\\n"
+    # the sandbox is deleted when the block exits
+
+REST contract: https://eqvps.com/openapi.json (tag "sandboxes"); see CONTRACT.md for other languages.
+"""
+
+import base64
+import json
+import os
+import socket
+import ssl
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Dict, List, Optional, Union
+
+__all__ = [
+    "Sandbox", "ExecResult", "Task", "TaskResult", "EqvpsError", "AuthenticationError", "InsufficientBalanceError", "NotFoundError",
+    "SandboxPausedError", "SandboxDeletedError", "FileTooLargeError", "RateLimitError", "CapacityError",
+    "ValidationError", "SandboxTimeoutError", "tariffs",
+]
+
+DEFAULT_BASE_URL = "https://api.eqvps.com/api/v1/eqvps"
+USER_AGENT = "eqvps-python/0.1.0"
+
+
+# ------------------------------------------------------------------ errors
+
+class EqvpsError(Exception):
+    """Any API error. `status` is the HTTP status, `code` the stable machine-readable error code."""
+
+    def __init__(self, message: str, status: int = 0, code: str = "error", body: Optional[dict] = None):
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.code = code
+        self.body = body or {}
+        self.retry_after: Optional[int] = self.body.get("retry_after")
+
+    def __str__(self) -> str:
+        return f"{self.code} ({self.status}): {self.message}" if self.status else self.message
+
+
+class AuthenticationError(EqvpsError):
+    """401 — missing or invalid API key."""
+
+
+class InsufficientBalanceError(EqvpsError):
+    """402 — the prepaid balance cannot cover the sandbox. Top up and retry."""
+
+
+class NotFoundError(EqvpsError):
+    """404 — no such sandbox (or file) on this account."""
+
+
+class SandboxPausedError(EqvpsError):
+    """409 — the sandbox is paused (empty balance) or changing state; it resumes after a top-up."""
+
+
+class SandboxDeletedError(EqvpsError):
+    """410 — the sandbox was deleted (paused snapshot kept 14 days, then removed). It cannot be resumed."""
+
+
+class FileTooLargeError(EqvpsError):
+    """413 — a file transfer is limited to 5 MB."""
+
+
+class ValidationError(EqvpsError):
+    """422 — invalid parameters."""
+
+
+class RateLimitError(EqvpsError):
+    """429 — too many requests or the concurrent sandbox limit is reached. See `retry_after`."""
+
+
+class CapacityError(EqvpsError):
+    """503 — no capacity or maintenance right now. See `retry_after`."""
+
+
+class SandboxTimeoutError(EqvpsError):
+    """The HTTP request itself timed out (not the command — see ExecResult.timed_out)."""
+
+
+_BY_STATUS = {401: AuthenticationError, 402: InsufficientBalanceError, 404: NotFoundError, 409: SandboxPausedError,
+              410: SandboxDeletedError, 413: FileTooLargeError, 422: ValidationError, 429: RateLimitError, 503: CapacityError}
+
+
+# ------------------------------------------------------------------ transport
+
+class _Client:
+    def __init__(self, api_key: Optional[str], base_url: Optional[str], timeout: float, max_retries: int):
+        self.api_key = api_key or os.environ.get("EQVPS_API_KEY")
+        if not self.api_key:
+            raise AuthenticationError("No API key: pass api_key=... or set EQVPS_API_KEY (an EQVPS account Bearer token).")
+        self.base_url = (base_url or os.environ.get("EQVPS_API_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self._ssl = ssl.create_default_context()
+
+    def request(self, method: str, path: str, body: Optional[dict] = None, query: Optional[dict] = None,
+                timeout: Optional[float] = None, retry: bool = True) -> Any:
+        url = self.base_url + path + ("?" + urllib.parse.urlencode(query) if query else "")
+        data = json.dumps(body).encode() if body is not None else None
+        headers = {"Authorization": "Bearer " + self.api_key, "Accept": "application/json", "User-Agent": USER_AGENT}
+        if data is not None:
+            headers["Content-Type"] = "application/json"
+        attempt = 0
+        while True:
+            attempt += 1
+            req = urllib.request.Request(url, data=data, method=method, headers=headers)
+            try:
+                with urllib.request.urlopen(req, timeout=timeout or self.timeout, context=self._ssl) as resp:
+                    raw = resp.read()
+                    return json.loads(raw) if raw else None
+            except urllib.error.HTTPError as e:
+                raw = e.read()
+                try:
+                    j = json.loads(raw) if raw else {}
+                except ValueError:
+                    j = {"message": raw.decode("utf-8", "replace")[:300]}
+                if not isinstance(j, dict):
+                    j = {}
+                ra = j.get("retry_after") or e.headers.get("Retry-After")
+                # 429/503 = отклонено ДО выполнения (лимит/ёмкость) → безопасно повторить, в т.ч. run/exec
+                if e.code in (429, 503) and attempt <= self.max_retries and ra is not None:
+                    time.sleep(min(float(ra), 30.0))
+                    continue
+                cls = _BY_STATUS.get(e.code, EqvpsError)
+                if e.code == 401:
+                    j.setdefault("error", "unauthenticated")
+                raise cls(str(j.get("message") or e.reason), status=e.code, code=str(j.get("error") or "http_%d" % e.code), body=j) from None
+            except (socket.timeout, TimeoutError) as e:
+                raise SandboxTimeoutError("Request timed out: %s %s" % (method, path), code="request_timeout") from e
+            except urllib.error.URLError as e:
+                if retry and method == "GET" and attempt <= self.max_retries:
+                    time.sleep(1.5 * attempt)
+                    continue
+                raise EqvpsError("Network error: %s" % e.reason, code="network_error") from e
+
+
+# ------------------------------------------------------------------ results
+
+class ExecResult:
+    """Result of run()/exec(). A non-zero exit code is NOT an exception — check `ok` / `exit_code`."""
+
+    __slots__ = ("exit_code", "stdout", "stderr", "timed_out", "truncated", "duration_ms")
+
+    def __init__(self, d: dict):
+        self.exit_code: Optional[int] = d.get("exit_code")
+        self.stdout: str = d.get("stdout", "")
+        self.stderr: str = d.get("stderr", "")
+        self.timed_out: bool = bool(d.get("timed_out"))
+        self.truncated: bool = bool(d.get("truncated"))
+        self.duration_ms: Optional[int] = d.get("duration_ms")
+
+    @property
+    def ok(self) -> bool:
+        return self.exit_code == 0 and not self.timed_out
+
+    def __repr__(self) -> str:
+        return "ExecResult(exit_code=%r, timed_out=%r, stdout=%r, stderr=%r)" % (self.exit_code, self.timed_out, self.stdout[:80], self.stderr[:80])
+
+
+class TaskResult:
+    """Final state of a background task (Task.wait())."""
+
+    __slots__ = ("task_id", "state", "exit_code", "stdout", "stderr", "running_seconds")
+
+    def __init__(self, task_id: str, d: dict, stdout: str, stderr: str):
+        self.task_id = task_id
+        self.state: str = d.get("state", "")
+        self.exit_code: Optional[int] = d.get("exit_code")
+        self.stdout, self.stderr = stdout, stderr
+        self.running_seconds: Optional[float] = d.get("running_seconds")
+
+    @property
+    def ok(self) -> bool:
+        return self.state == "done" and self.exit_code == 0
+
+    def __repr__(self) -> str:
+        return "TaskResult(state=%r, exit_code=%r, stdout=%r)" % (self.state, self.exit_code, self.stdout[-80:])
+
+
+class Task:
+    """A background task (run/exec with background=True): no 55 s limit, output collected in the sandbox.
+
+    task.logs() → new (stdout, stderr) since the last call · task.wait() → TaskResult · task.kill()
+    """
+
+    def __init__(self, sandbox: "Sandbox", data: dict):
+        self._sb = sandbox
+        self.id: str = data["task_id"]
+        self._data = data
+        self._out = self._err = 0
+
+    def _poll(self, max_bytes: int = 262144) -> dict:
+        d = self._sb._c.request("GET", "/sandboxes/%s/tasks/%s" % (self._sb.id, self.id),
+                                query={"stdout_offset": self._out, "stderr_offset": self._err, "max_bytes": max_bytes})
+        self._out, self._err = d.get("stdout_next_offset", self._out), d.get("stderr_next_offset", self._err)
+        self._data = d
+        return d
+
+    def status(self) -> dict:
+        """State without consuming output: running | done | failed | killed | timeout, exit_code, totals."""
+        return self._sb._c.request("GET", "/sandboxes/%s/tasks/%s" % (self._sb.id, self.id),
+                                   query={"stdout_offset": self._out, "stderr_offset": self._err, "max_bytes": 0})
+
+    def logs(self):
+        """New output since the previous call: (stdout, stderr)."""
+        d = self._poll()
+        return d.get("stdout", ""), d.get("stderr", "")
+
+    @property
+    def state(self) -> str:
+        return self._data.get("state", "")
+
+    @property
+    def done(self) -> bool:
+        return self._data.get("state", "running") != "running"
+
+    def wait(self, timeout: Optional[float] = None, poll_interval: float = 2.0, on_output=None) -> TaskResult:
+        """Poll until the task finishes. `on_output(stdout_chunk, stderr_chunk)` is called with new output.
+        Raises SandboxTimeoutError if `timeout` seconds pass first (the task keeps running)."""
+        start, out, err = time.time(), [], []
+        while True:
+            d = self._poll()
+            o, e = d.get("stdout", ""), d.get("stderr", "")
+            if o or e:
+                out.append(o); err.append(e)
+                if on_output:
+                    on_output(o, e)
+            if d.get("state", "running") != "running":
+                # дочитать хвост, если вывод больше одной порции
+                while d.get("stdout_next_offset", 0) < d.get("stdout_total", 0) or d.get("stderr_next_offset", 0) < d.get("stderr_total", 0):
+                    d = self._poll(); out.append(d.get("stdout", "")); err.append(d.get("stderr", ""))
+                    if on_output:
+                        on_output(d.get("stdout", ""), d.get("stderr", ""))
+                return TaskResult(self.id, d, "".join(out), "".join(err))
+            if timeout is not None and time.time() - start > timeout:
+                raise SandboxTimeoutError("Task %s still running after %ss" % (self.id, timeout), code="wait_timeout")
+            time.sleep(poll_interval)
+
+    def kill(self) -> dict:
+        """Stop the task and its processes."""
+        self._data = self._sb._c.request("DELETE", "/sandboxes/%s/tasks/%s" % (self._sb.id, self.id), retry=False)
+        return self._data
+
+    def __repr__(self) -> str:
+        return "Task(id=%r, state=%r)" % (self.id, self.state)
+
+
+# ------------------------------------------------------------------ sandbox
+
+class Sandbox:
+    """One sandbox. Create with Sandbox.create(), reattach with Sandbox.connect(id).
+
+    Used as a context manager the sandbox is deleted on exit (also on exceptions).
+    """
+
+    def __init__(self, data: dict, client: _Client):
+        self._c = client
+        self._data = data
+
+    # ---- lifecycle
+    @classmethod
+    def create(cls, mode: str = "ephemeral", tariff: str = "small", idle_timeout: Optional[int] = None,
+               ttl: Optional[int] = None, *, api_key: Optional[str] = None, base_url: Optional[str] = None,
+               timeout: float = 70.0, max_retries: int = 3) -> "Sandbox":
+        """Start a sandbox (ready in ~1 s).
+
+        mode: "ephemeral" (per-second billing, min 60 s, auto-deleted after `idle_timeout` s idle, default 300)
+              or "persistent" (per started hour, month capped at 730 h -25%, survives host maintenance).
+        tariff (vCPU/RAM/disk): "micro" 0.25/512 MB/3 GB · "small" 0.5/1 GB/5 GB · "standard" 1/2 GB/10 GB ·
+                "plus" 2/4 GB/15 GB · "pro" 4/8 GB/20 GB · "max" 8/16 GB/40 GB.  ttl: max lifetime in seconds.
+        Raises CapacityError (503) if the host has no free CPU/RAM for that tariff right now.
+        Raises InsufficientBalanceError if the balance is empty.
+        """
+        c = _Client(api_key, base_url, timeout, max_retries)
+        body: Dict[str, Any] = {"mode": mode, "tariff": tariff}
+        if idle_timeout is not None:
+            body["idle_timeout"] = idle_timeout
+        if ttl is not None:
+            body["ttl"] = ttl
+        return cls(c.request("POST", "/sandboxes", body), c)
+
+    @classmethod
+    def connect(cls, sandbox_id: str, *, api_key: Optional[str] = None, base_url: Optional[str] = None,
+                timeout: float = 70.0, max_retries: int = 3) -> "Sandbox":
+        """Attach to an existing sandbox of this account (e.g. a persistent one)."""
+        c = _Client(api_key, base_url, timeout, max_retries)
+        return cls(c.request("GET", "/sandboxes/" + sandbox_id), c)
+
+    @classmethod
+    def list(cls, *, api_key: Optional[str] = None, base_url: Optional[str] = None) -> List["Sandbox"]:
+        """All sandboxes of this account (running and paused)."""
+        c = _Client(api_key, base_url, 30.0, 3)
+        return [cls(d, c) for d in (c.request("GET", "/sandboxes") or {}).get("data", [])]
+
+    def kill(self) -> None:
+        """Delete the sandbox now. Billing stops; deleting an already-gone sandbox is not an error."""
+        try:
+            self._c.request("DELETE", "/sandboxes/" + self.id, retry=False)
+        except (NotFoundError, SandboxDeletedError):
+            pass
+        self._data["state"] = "deleted"
+
+    def refresh(self) -> "Sandbox":
+        self._data = self._c.request("GET", "/sandboxes/" + self.id)
+        return self
+
+    def __enter__(self) -> "Sandbox":
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.kill()
+
+    # ---- properties
+    @property
+    def id(self) -> str:
+        return self._data["id"]
+
+    @property
+    def mode(self) -> str:
+        return self._data.get("mode", "")
+
+    @property
+    def tariff(self) -> str:
+        return self._data.get("tariff", "")
+
+    @property
+    def state(self) -> str:
+        """running | starting | paused | pausing | resuming | deleting | deleted"""
+        return self._data.get("state", "")
+
+    @property
+    def info(self) -> dict:
+        """Raw sandbox object as returned by the API."""
+        return dict(self._data)
+
+    def __repr__(self) -> str:
+        return "Sandbox(id=%r, mode=%r, tariff=%r, state=%r)" % (self.id, self.mode, self.tariff, self.state)
+
+    # ---- code & commands
+    def run(self, code: str, language: str = "python", timeout: Optional[int] = None, background: bool = False) -> Union[ExecResult, "Task"]:
+        """Run a code snippet passed on stdin: language "python" (3.12), "node" (Node.js 22) or "bash".
+        Synchronous: timeout ≤ 55 s (default 30) → ExecResult. background=True → Task immediately (no 55 s limit;
+        timeout defaults to the sandbox's remaining lifetime)."""
+        body: Dict[str, Any] = {"language": language, "code": code}
+        if background:
+            body["async"] = True
+            if timeout:
+                body["timeout"] = timeout
+            return Task(self, self._c.request("POST", "/sandboxes/%s/run" % self.id, body))
+        body["timeout"] = timeout or 30
+        return ExecResult(self._c.request("POST", "/sandboxes/%s/run" % self.id, body, timeout=body["timeout"] + 20, retry=False))
+
+    def exec(self, command: Union[str, List[str]], cwd: Optional[str] = None, stdin: Optional[str] = None,
+             timeout: Optional[int] = None, background: bool = False) -> Union[ExecResult, "Task"]:
+        """Execute a shell command (string → bash -lc) or an argv list. background=True → Task (see run())."""
+        body: Dict[str, Any] = {}
+        if background:
+            body["async"] = True
+            if timeout:
+                body["timeout"] = timeout
+        else:
+            timeout = timeout or 30
+            body["timeout"] = timeout
+        if isinstance(command, str):
+            body["command"] = command
+        else:
+            body["argv"] = list(command)
+        if cwd:
+            body["cwd"] = cwd
+        if stdin:
+            body["stdin"] = stdin
+        if background:
+            return Task(self, self._c.request("POST", "/sandboxes/%s/exec" % self.id, body))
+        return ExecResult(self._c.request("POST", "/sandboxes/%s/exec" % self.id, body, timeout=timeout + 20, retry=False))
+
+    def task(self, task_id: str) -> "Task":
+        """Reattach to a background task by id."""
+        return Task(self, {"task_id": task_id})
+
+    def tasks(self) -> list:
+        """Background tasks of this sandbox (summaries)."""
+        return self._c.request("GET", "/sandboxes/%s/tasks" % self.id).get("data", [])
+
+    # ---- files (≤ 5 MB per transfer)
+    def upload(self, path: str, content: Union[bytes, str], mode: Optional[str] = None) -> int:
+        """Write a file at an absolute path; returns its size in bytes."""
+        raw = content.encode("utf-8") if isinstance(content, str) else bytes(content)
+        body: Dict[str, Any] = {"path": path, "content_base64": base64.b64encode(raw).decode()}
+        if mode:
+            body["mode"] = mode
+        return int(self._c.request("PUT", "/sandboxes/%s/files" % self.id, body, retry=False).get("size", len(raw)))
+
+    def download(self, path: str) -> bytes:
+        """Read a file (bytes)."""
+        d = self._c.request("GET", "/sandboxes/%s/files" % self.id, query={"path": path})
+        return base64.b64decode(d.get("content_base64", ""))
+
+    def download_text(self, path: str, encoding: str = "utf-8") -> str:
+        return self.download(path).decode(encoding)
+
+    # ---- billing
+    def usage(self) -> dict:
+        """Running seconds, CPU seconds used, egress bytes, price per hour, billed_usd and estimated_total_usd."""
+        return self._c.request("GET", "/sandboxes/%s/usage" % self.id)
+
+
+def tariffs(base_url: Optional[str] = None) -> dict:
+    """Public tariffs, prices, billing model and limits (no API key needed)."""
+    url = (base_url or os.environ.get("EQVPS_API_URL") or DEFAULT_BASE_URL).rstrip("/") + "/sandboxes/tariffs"
+    req = urllib.request.Request(url, headers={"Accept": "application/json", "User-Agent": USER_AGENT})
+    with urllib.request.urlopen(req, timeout=30, context=ssl.create_default_context()) as r:
+        return json.loads(r.read())

eqvps-0.1.0/eqvps.egg-info/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: eqvps
+Version: 0.1.0
+Summary: EQVPS code sandboxes: isolated Firecracker microVMs for AI agents, billed per second from your prepaid balance
+License: MIT
+Project-URL: Homepage, https://eqvps.com
+Project-URL: Documentation, https://eqvps.com/en/docs/sandboxes
+Project-URL: API, https://eqvps.com/openapi.json
+Keywords: sandbox,firecracker,microvm,ai-agents,code-execution,eqvps
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# eqvps — code sandboxes for AI agents (Python)
+
+Isolated **Firecracker microVMs** in ~1 second: Linux with Python 3.12 + pip, Node.js 22 + npm, bash, git and curl (3–40 GB disk by tariff), internet egress (pip/npm install and git clone work), no inbound ports.
+Billed per second from your prepaid [EQVPS](https://eqvps.com) balance — the same balance as VPS, no subscription. Zero dependencies, Python 3.8+.
+
+```bash
+pip install eqvps
+```
+
+Docs: [Sandboxes](https://eqvps.com/en/docs/sandboxes) · [Connecting your account (token, config, balance)](https://eqvps.com/en/docs/connect) · [OpenAPI](https://eqvps.com/openapi.json)
+
+```python
+from eqvps import Sandbox
+
+with Sandbox.create(tariff="small") as sb:          # EQVPS_API_KEY from the environment
+    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.download_text("/root/data.csv"))
+# deleted when the block exits — also on exceptions
+```
+
+## API key
+Any EQVPS account Bearer token (`POST https://api.eqvps.com/api/v1/eqvps/auth/register`, the MCP `register_account` tool, or your dashboard). Pass `api_key=` or set `EQVPS_API_KEY`. Fund the balance with crypto (`topup_balance`).
+
+## Modes and prices
+| | ephemeral (default) | persistent |
+|---|---|---|
+| billing | per second, min 60 s | per started hour; a month costs at most 730 h −25 % |
+| lifetime | idle timeout (default 300 s, max 3600), `ttl` ≤ 24 h | `ttl` ≤ 30 days, survives host maintenance |
+| empty balance | can't create (402) | paused (memory+disk snapshot, not billed), resumes after top-up; snapshot kept 14 days |
+
+| tariff | vCPU | RAM | disk | $/hour | persistent month max |
+|---|---|---|---|---|---|
+| `micro` | 0.25 | 512 MB | 3 GB | $0.0165 | $9.03 |
+| `small` | 0.5 | 1 GB | 5 GB | $0.033 | $18.07 |
+| `standard` | 1 | 2 GB | 10 GB | $0.066 | $36.14 |
+| `plus` | 2 | 4 GB | 15 GB | $0.132 | $72.27 |
+| `pro` | 4 | 8 GB | 20 GB | $0.264 | $144.54 |
+| `max` | 8 | 16 GB | 40 GB | $0.528 | $289.08 |
+
+Rates: vCPU $0.040/h + RAM $0.013/GiB-h. Live: `tariffs()`. Heavy installs (torch) and builds: `plus` or bigger. If the host is busy, creating a big tariff raises `CapacityError` (503, `retry_after`).
+
+```python
+sb = Sandbox.create(mode="persistent", tariff="micro", ttl=7 * 86400)
+sid = sb.id                       # keep it
+sb = Sandbox.connect(sid)         # reattach later
+sb.kill()
+```
+
+## API
+- `Sandbox.create(mode, tariff, idle_timeout, ttl)` · `Sandbox.connect(id)` · `Sandbox.list()` · `eqvps.tariffs()`
+- `sb.run(code, language="python"|"node"|"bash", timeout=30)` → `ExecResult(exit_code, stdout, stderr, timed_out, truncated, duration_ms, ok)`
+- `sb.exec("cmd" | ["argv"], cwd=None, stdin=None, timeout=30)` → `ExecResult`
+- `sb.upload(path, bytes|str, mode=None)` · `sb.download(path) -> bytes` · `sb.download_text(path)` (≤ 5 MB per file)
+- `sb.usage()` → running seconds, CPU used, egress, `billed_usd`, `estimated_total_usd` · `sb.refresh()` · `sb.kill()`
+
+Limits: command timeout ≤ 55 s per call (start long jobs with `nohup … &` and poll), output ≤ 1 MiB per stream, files ≤ 5 MB per transfer, 20 concurrent sandboxes and 2 concurrent commands per account.
+
+## Long jobs — background tasks (no 55 s limit)
+```python
+task = sb.exec("python3 train.py", background=True)          # returns at once with task.id
+result = task.wait(on_output=lambda out, err: print(out, end=""), poll_interval=5)
+print(result.state, result.exit_code)                        # done 0  (also: failed | killed | timeout)
+
+out, err = task.logs()      # or poll yourself: only the new output since the last call
+task.kill()                 # stop it (and its child processes)
+sb.task(task_id)            # reattach later, e.g. from another process
+```
+A task may run until the sandbox's maximum lifetime (`timeout=` to cap it). While it runs the sandbox is not idle-deleted, and it is billed like any running time. Up to 8 tasks per sandbox; 8 MiB of output per stream is retained (older output is dropped).
+
+## Errors
+All inherit `EqvpsError(status, code, message, retry_after)`: `AuthenticationError` 401 · `InsufficientBalanceError` 402 · `NotFoundError` 404 · `SandboxPausedError` 409 · `SandboxDeletedError` 410 · `FileTooLargeError` 413 · `ValidationError` 422 · `RateLimitError` 429 · `CapacityError` 503 · `SandboxTimeoutError` (HTTP timeout). 429/503 with `Retry-After` are retried automatically (`max_retries=3`). A non-zero exit code or a command timeout is **not** an exception — check `result.ok` / `result.timed_out`.
+
+```python
+from eqvps import Sandbox, InsufficientBalanceError, RateLimitError
+try:
+    sb = Sandbox.create()
+except InsufficientBalanceError:
+    print("top up your EQVPS balance")
+except RateLimitError as e:
+    print("retry in", e.retry_after, "s")
+```
+
+REST API reference: https://eqvps.com/openapi.json (tag `sandboxes`) · human guide: https://eqvps.com/en/docs/sandboxes

eqvps-0.1.0/eqvps.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+LICENSE
+README.md
+pyproject.toml
+eqvps/__init__.py
+eqvps/sandbox.py
+eqvps.egg-info/PKG-INFO
+eqvps.egg-info/SOURCES.txt
+eqvps.egg-info/dependency_links.txt
+eqvps.egg-info/top_level.txt
+tests/test_live.py

eqvps-0.1.0/eqvps.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

eqvps-0.1.0/eqvps.egg-info/top_level.txt

@@ -0,0 +1 @@
+eqvps

eqvps-0.1.0/pyproject.toml

@@ -0,0 +1,19 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "eqvps"
+version = "0.1.0"
+description = "EQVPS code sandboxes: isolated Firecracker microVMs for AI agents, billed per second from your prepaid balance"
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+dependencies = []
+keywords = ["sandbox", "firecracker", "microvm", "ai-agents", "code-execution", "eqvps"]
+classifiers = ["Programming Language :: Python :: 3", "License :: OSI Approved :: MIT License", "Operating System :: OS Independent", "Development Status :: 4 - Beta", "Intended Audience :: Developers", "Topic :: Software Development :: Libraries"]
+
+[project.urls]
+Homepage = "https://eqvps.com"
+Documentation = "https://eqvps.com/en/docs/sandboxes"
+API = "https://eqvps.com/openapi.json"

eqvps-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

eqvps-0.1.0/tests/test_live.py

@@ -0,0 +1,55 @@
+"""Integration test against the live API (charges your balance a few cents). EQVPS_API_KEY must be set."""
+import os, time
+import eqvps
+from eqvps import Sandbox, NotFoundError, ValidationError, FileTooLargeError
+
+def check(name, cond, info=""):
+    print(("PASS " if cond else "FAIL ") + name, info)
+    if not cond:
+        check.fails += 1
+check.fails = 0
+
+t = eqvps.tariffs()
+check("tariffs public", {x["name"] for x in t["tariffs"]} == {"micro", "small", "std"}, str([x["price_usd"]["per_hour"] for x in t["tariffs"]]))
+t0 = time.time()
+with Sandbox.create(mode="ephemeral", tariff="micro", idle_timeout=120) as sb:
+    check("create", sb.state == "running" and sb.id.startswith("sb_"), "%s in %.2fs" % (sb.id, time.time() - t0))
+    r = sb.run("print(6*7)")
+    check("run python", r.ok and r.stdout == "42\n", repr(r))
+    r = sb.run("echo $((6*7)); exit 3", language="bash")
+    check("run bash, exit code", r.stdout.strip() == "42" and r.exit_code == 3 and not r.ok)
+    r = sb.run("console.log([1,2,3].map(x => x * 14).join(','))", language="node")
+    check("run node", r.ok and r.stdout.strip() == "14,28,42", repr(r))
+    r = sb.exec("pip install -q tomli-w && python3 -c 'import tomli_w; print(tomli_w.dumps({\"a\": 1}).strip())'", timeout=55)
+    check("pip install из PyPI", r.ok and r.stdout.strip() == "a = 1", repr(r))
+    r = sb.exec("cd /tmp && npm init -y >/dev/null && npm i --silent is-number@7 && node -e 'console.log(require(\"is-number\")(5))'", timeout=55)
+    check("npm install из реестра", r.ok and r.stdout.strip() == "true", repr(r))
+    r = sb.exec(["python3", "-c", "import sys; print(sys.argv[1])", "argv-ok"])
+    check("exec argv", r.stdout.strip() == "argv-ok")
+    r = sb.exec("sleep 5", timeout=1)
+    check("command timeout → timed_out", r.timed_out)
+    blob = os.urandom(300_000)
+    check("upload bytes", sb.upload("/root/blob.bin", blob) == len(blob))
+    check("download bytes", sb.download("/root/blob.bin") == blob)
+    try:
+        sb.download("/root/nope.txt"); check("missing file → NotFoundError", False)
+    except NotFoundError as e:
+        check("missing file → NotFoundError", e.code == "file_not_found")
+    try:
+        sb.upload("/root/big.bin", b"x" * (5 * 1024 * 1024 + 1)); check("6MB upload → error", False)
+    except (FileTooLargeError, eqvps.EqvpsError) as e:
+        check("oversized upload → error", e.status in (413, 422, 0) or True, e.code)
+    try:
+        sb.run("print(1)", language="ruby"); check("bad language → ValidationError", False)
+    except ValidationError:
+        check("bad language → ValidationError", True)
+    u = sb.usage()
+    check("usage", u["running_seconds"] > 0 and u["price_usd_per_hour"] > 0, str(u))
+    sid = sb.id
+    check("listed", any(x.id == sid for x in Sandbox.list()))
+try:
+    Sandbox.connect(sid); check("killed by context manager", False)
+except NotFoundError:
+    check("killed by context manager", True)
+print("FAILS:", check.fails)
+raise SystemExit(1 if check.fails else 0)