wbxsandbox 0.15.2__tar.gz

wbxsandbox-0.15.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KXCOMM s.r.o.
+
+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.

wbxsandbox-0.15.2/PKG-INFO

@@ -0,0 +1,85 @@
+Metadata-Version: 2.4
+Name: wbxsandbox
+Version: 0.15.2
+Summary: Python SDK for WBX Sandbox – isolated cloud sandboxes (Firecracker microVMs) for AI agents
+Author: KXCOMM s.r.o.
+License-Expression: MIT
+Project-URL: Homepage, https://sandbox.wbx.cz
+Project-URL: Documentation, https://sandbox.wbx.cz/docs
+Project-URL: Pricing, https://sandbox.wbx.cz/pricing
+Keywords: sandbox,firecracker,microvm,ai agents,code execution,wbx
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Distributed Computing
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# WBX Sandbox – Python SDK
+
+Python SDK for [WBX Sandbox](https://sandbox.wbx.cz): isolated cloud sandboxes for AI agents
+and code execution. Each sandbox is a Firecracker microVM with its own Linux kernel, disk and
+network rules. No dependencies – only the Python standard library (Python 3.9+).
+
+## Install
+
+    pip install wbxsandbox
+
+## Configure
+
+Create an API key in the portal (API keys) and set it in the environment:
+
+    export WBXSANDBOX_API_KEY=...
+    # optional, defaults to https://sandbox.wbx.cz
+    export WBXSANDBOX_URL=https://sandbox.wbx.cz
+
+Both can also be passed as `url=` and `api_key=` arguments.
+
+## Quick start
+
+```python
+from wbxsandbox import Sandbox
+
+with Sandbox.create(template="base", timeout=300) as sb:
+    r = sb.run("python3 -c 'print(1 + 1)'")
+    print(r.exit_code, r.stdout)          # 0 "2\n"
+    sb.files.write("/home/user/data.txt", "hello")
+    print(sb.files.read_text("/home/user/data.txt"))
+# the sandbox is destroyed when the block ends
+```
+
+Background jobs and batches:
+
+```python
+from wbxsandbox import run_job
+
+job = run_job(command="python3 -c 'print(42)'", template="base", timeout_seconds=600)
+job.wait()
+print(job.summary()["status"])
+```
+
+Interactive terminal in a running sandbox (installed as the `wbx` command):
+
+    wbx connect sb_...
+
+Documentation: https://sandbox.wbx.cz/docs · Pricing: https://sandbox.wbx.cz/pricing
+
+## Versioning
+
+The SDK has its own version. Its `major.minor` follows the platform release line
+(SDK 0.15.x works with platform 0.15.x); the patch number is raised only when the SDK
+itself changes. `pyproject.toml` and `wbxsandbox.__version__` always carry the same
+version (checked by `tests/test_sdk.py`).
+
+## Tests
+
+    cd sdk/python && python3 -m unittest discover -s tests
+
+The tests do not need network access.
+
+## License
+
+MIT – see `LICENSE`.

wbxsandbox-0.15.2/README.md

@@ -0,0 +1,65 @@
+# WBX Sandbox – Python SDK
+
+Python SDK for [WBX Sandbox](https://sandbox.wbx.cz): isolated cloud sandboxes for AI agents
+and code execution. Each sandbox is a Firecracker microVM with its own Linux kernel, disk and
+network rules. No dependencies – only the Python standard library (Python 3.9+).
+
+## Install
+
+    pip install wbxsandbox
+
+## Configure
+
+Create an API key in the portal (API keys) and set it in the environment:
+
+    export WBXSANDBOX_API_KEY=...
+    # optional, defaults to https://sandbox.wbx.cz
+    export WBXSANDBOX_URL=https://sandbox.wbx.cz
+
+Both can also be passed as `url=` and `api_key=` arguments.
+
+## Quick start
+
+```python
+from wbxsandbox import Sandbox
+
+with Sandbox.create(template="base", timeout=300) as sb:
+    r = sb.run("python3 -c 'print(1 + 1)'")
+    print(r.exit_code, r.stdout)          # 0 "2\n"
+    sb.files.write("/home/user/data.txt", "hello")
+    print(sb.files.read_text("/home/user/data.txt"))
+# the sandbox is destroyed when the block ends
+```
+
+Background jobs and batches:
+
+```python
+from wbxsandbox import run_job
+
+job = run_job(command="python3 -c 'print(42)'", template="base", timeout_seconds=600)
+job.wait()
+print(job.summary()["status"])
+```
+
+Interactive terminal in a running sandbox (installed as the `wbx` command):
+
+    wbx connect sb_...
+
+Documentation: https://sandbox.wbx.cz/docs · Pricing: https://sandbox.wbx.cz/pricing
+
+## Versioning
+
+The SDK has its own version. Its `major.minor` follows the platform release line
+(SDK 0.15.x works with platform 0.15.x); the patch number is raised only when the SDK
+itself changes. `pyproject.toml` and `wbxsandbox.__version__` always carry the same
+version (checked by `tests/test_sdk.py`).
+
+## Tests
+
+    cd sdk/python && python3 -m unittest discover -s tests
+
+The tests do not need network access.
+
+## License
+
+MIT – see `LICENSE`.

wbxsandbox-0.15.2/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "wbxsandbox"
+version = "0.15.2"
+description = "Python SDK for WBX Sandbox – isolated cloud sandboxes (Firecracker microVMs) for AI agents"
+readme = "README.md"
+requires-python = ">=3.9"
+dependencies = []
+license = "MIT"
+authors = [{ name = "KXCOMM s.r.o." }]
+keywords = ["sandbox", "firecracker", "microvm", "ai agents", "code execution", "wbx"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: System :: Distributed Computing",
+]
+
+[project.urls]
+Homepage = "https://sandbox.wbx.cz"
+Documentation = "https://sandbox.wbx.cz/docs"
+Pricing = "https://sandbox.wbx.cz/pricing"
+
+[project.scripts]
+wbx = "wbxsandbox.cli:main"
+
+[tool.setuptools]
+packages = ["wbxsandbox"]

wbxsandbox-0.15.2/setup.cfg

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

wbxsandbox-0.15.2/tests/test_sdk.py

@@ -0,0 +1,128 @@
+"""Testy Python SDK bez sítě: verze, podpis webhooku, rozpočet (měna účtu, starší názvy parametrů).
+
+Spuštění: cd sdk/python && python3 -m unittest discover -s tests
+"""
+import hashlib
+import hmac
+import os
+import re
+import sys
+import time
+import unittest
+from unittest import mock
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+SDK = os.path.dirname(HERE)
+sys.path.insert(0, SDK)
+
+import wbxsandbox  # noqa: E402
+
+
+def _read(*parts):
+    with open(os.path.join(*parts), encoding="utf-8") as f:
+        return f.read()
+
+
+class VersionTest(unittest.TestCase):
+    def test_pyproject_matches_package(self):
+        m = re.search(r'^version\s*=\s*"([^"]+)"', _read(SDK, "pyproject.toml"), re.M)
+        self.assertIsNotNone(m)
+        self.assertEqual(m.group(1), wbxsandbox.__version__)
+
+    def test_same_major_minor_as_platform(self):
+        # SDK má vlastní patch verzi, ale řada major.minor odpovídá platformě. Verze platformy:
+        # RELEASE ve vydaném balíku (src/sdk/python i sdk/python), v repozitáři Makefile.
+        # Bez metadat platformy test selže – nesmí se tiše přeskočit.
+        version = platform_version()
+        self.assertIsNotNone(version, "platform version not found (RELEASE in the bundle or Makefile in the repository)")
+        self.assertEqual(version.split(".")[:2], wbxsandbox.__version__.split(".")[:2])
+
+
+def platform_version():
+    """Verze platformy z RELEASE (balík) nebo z Makefile (repozitář); None = nenalezeno."""
+    for rel in (os.path.join(SDK, "..", "..", "RELEASE"), os.path.join(SDK, "..", "..", "..", "RELEASE")):
+        if os.path.exists(rel):
+            m = re.search(r"^version:\s*(\S+)", _read(rel), re.M)
+            if m:
+                return m.group(1)
+    mk = os.path.join(SDK, "..", "..", "Makefile")
+    if os.path.exists(mk):
+        m = re.search(r"^VERSION\s*:=\s*(\S+)", _read(mk), re.M)
+        if m:
+            return m.group(1)
+    return None
+
+
+class PlatformVersionLookupTest(unittest.TestCase):
+    def test_reads_release_then_makefile_and_reports_missing(self):
+        import tempfile
+        global SDK
+        orig = SDK
+        try:
+            with tempfile.TemporaryDirectory() as d:
+                SDK = os.path.join(d, "src", "sdk", "python")
+                os.makedirs(SDK)
+                self.assertIsNone(platform_version())  # nic → None (test výše pak selže)
+                with open(os.path.join(d, "RELEASE"), "w") as f:
+                    f.write("version: 9.8.7\ncommit: x\n")
+                self.assertEqual(platform_version(), "9.8.7")  # src/sdk/python → ../../../RELEASE
+            with tempfile.TemporaryDirectory() as d:
+                SDK = os.path.join(d, "sdk", "python")
+                os.makedirs(SDK)
+                with open(os.path.join(d, "Makefile"), "w") as f:
+                    f.write("VERSION := 1.2.3\n")
+                self.assertEqual(platform_version(), "1.2.3")
+                with open(os.path.join(d, "RELEASE"), "w") as f:
+                    f.write("version: 1.2.4\n")
+                self.assertEqual(platform_version(), "1.2.4")  # RELEASE má přednost
+        finally:
+            SDK = orig
+
+
+class WebhookTest(unittest.TestCase):
+    def sign(self, secret, t, body):
+        return "t=%d,v1=%s" % (t, hmac.new(secret.encode(), b"%d." % t + body, hashlib.sha256).hexdigest())
+
+    def test_valid_tampered_and_old(self):
+        body = b'{"event":"job.finished","id":"job_1"}'
+        now = int(time.time())
+        sig = self.sign("whsec_x", now, body)
+        self.assertTrue(wbxsandbox.verify_webhook("whsec_x", body, sig))
+        self.assertFalse(wbxsandbox.verify_webhook("whsec_x", body + b" ", sig))
+        self.assertFalse(wbxsandbox.verify_webhook("whsec_y", body, sig))
+        self.assertFalse(wbxsandbox.verify_webhook("whsec_x", body, self.sign("whsec_x", now - 3600, body)))
+        self.assertFalse(wbxsandbox.verify_webhook("whsec_x", body, "garbage"))
+
+
+class BudgetTest(unittest.TestCase):
+    def call(self, **kw):
+        with mock.patch.object(wbxsandbox.Client, "request", return_value={"currency": "CZK"}) as req:
+            wbxsandbox.set_budget(url="https://x", api_key="k", **kw)
+        return req.call_args
+
+    def test_limits_in_billing_currency(self):
+        args = self.call(monthly="500", daily=0, alert_pct=90)
+        self.assertEqual(args.args[:2], ("PUT", "/v1/budget"))
+        self.assertEqual(args.kwargs["body"], {"monthly_limit": "500", "daily_limit": "0", "alert_pct": 90})
+
+    def test_old_parameter_names_still_work(self):
+        args = self.call(monthly_eur="12.5", daily_eur="")
+        self.assertEqual(args.kwargs["body"], {"monthly_limit": "12.5", "daily_limit": ""})
+        # kladně: starší pořadí pozičních argumentů (měsíc, den) zůstává
+        with mock.patch.object(wbxsandbox.Client, "request", return_value={}) as req:
+            wbxsandbox.set_budget("7", "1", url="https://x", api_key="k")
+        self.assertEqual(req.call_args.kwargs["body"], {"monthly_limit": "7", "daily_limit": "1"})
+
+
+class PublicURLTest(unittest.TestCase):
+    def test_get_url(self):
+        c = wbxsandbox.Client(url="https://x", api_key="k")
+        sb = wbxsandbox.Sandbox(id="sb_n1_0123456789abcdef", template="base", state="running", _c=c)
+        with mock.patch.object(wbxsandbox.Client, "request", return_value={"url": "https://u/"}) as req:
+            self.assertEqual(sb.get_url("8080")["url"], "https://u/")
+        self.assertEqual(req.call_args.args, ("GET", "/v1/sandboxes/sb_n1_0123456789abcdef/url"))
+        self.assertEqual(req.call_args.kwargs["query"], {"port": 8080})
+
+
+if __name__ == "__main__":
+    unittest.main()

wbxsandbox-0.15.2/tests/test_terminal.py

@@ -0,0 +1,107 @@
+"""Terminál (wbx connect): adresa WebSocketu a minimální klient WebSocketu proti lokálnímu serveru."""
+import base64
+import hashlib
+import os
+import socket
+import struct
+import sys
+import threading
+import unittest
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, os.path.dirname(HERE))
+
+from wbxsandbox import terminal  # noqa: E402
+from wbxsandbox.cli import main  # noqa: E402
+
+
+def _server(handler):
+    srv = socket.socket()
+    srv.bind(("127.0.0.1", 0))
+    srv.listen(1)
+
+    def run():
+        c, _ = srv.accept()
+        req = b""
+        while b"\r\n\r\n" not in req:
+            req += c.recv(4096)
+        handler(c, req.decode())
+        c.close()
+        srv.close()
+
+    threading.Thread(target=run, daemon=True).start()
+    return srv.getsockname()[1]
+
+
+def _frame(opcode, payload):
+    return bytes([0x80 | opcode, len(payload)]) + payload
+
+
+def _read_client_frame(c):
+    b0, b1 = c.recv(2)
+    n = b1 & 0x7F
+    if n == 126:
+        n = struct.unpack("!H", c.recv(2))[0]
+    mask = c.recv(4)
+    data = b""
+    while len(data) < n:
+        data += c.recv(n - len(data))
+    return b0 & 0x0F, bytes(b ^ mask[i % 4] for i, b in enumerate(data))
+
+
+class TerminalTest(unittest.TestCase):
+    def test_url(self):
+        self.assertEqual(terminal.terminal_url("https://sandbox.wbx.cz/", "sb_n01_x", 80, 24),
+                         "wss://sandbox.wbx.cz/v1/sandboxes/sb_n01_x/terminal?cols=80&rows=24")
+        self.assertEqual(terminal.terminal_url("http://10.0.0.1:3000", "sb_n01_x", 1, 2),
+                         "ws://10.0.0.1:3000/v1/sandboxes/sb_n01_x/terminal?cols=1&rows=2")
+
+    def test_websocket_roundtrip(self):
+        got = {}
+
+        def handler(c, req):
+            got["req"] = req
+            key = [l.split(": ", 1)[1] for l in req.split("\r\n") if l.lower().startswith("sec-websocket-key")][0]
+            acc = base64.b64encode(hashlib.sha1((key + terminal._GUID).encode()).digest()).decode()
+            c.sendall(("HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\nConnection: Upgrade\r\n"
+                       f"Sec-WebSocket-Accept: {acc}\r\n\r\n").encode())
+            c.sendall(_frame(0x9, b"hi"))  # ping → klient odpoví pong
+            op, data = _read_client_frame(c)
+            got["pong"] = (op, data)
+            c.sendall(bytes([0x01, 3]) + b'{"a' + _frame(0x0, b'":1}'))  # fragmentovaná zpráva
+            op, data = _read_client_frame(c)
+            got["sent"] = (op, data)
+            c.sendall(_frame(0x8, struct.pack("!H", 1000)))
+            _read_client_frame(c)
+
+        port = _server(handler)
+        ws = terminal.WebSocket(f"ws://127.0.0.1:{port}/v1/sandboxes/sb/terminal?cols=1", {"X-API-Key": "k"})
+        self.assertEqual(ws.recv_text(), '{"a":1}')
+        ws.send_text("x" * 300)  # délka přes 126 bajtů
+        self.assertIsNone(ws.recv_text())
+        ws.close()
+        self.assertIn("GET /v1/sandboxes/sb/terminal?cols=1 HTTP/1.1", got["req"])
+        self.assertIn("X-API-Key: k", got["req"])
+        self.assertEqual(got["pong"], (0xA, b"hi"))
+        self.assertEqual(got["sent"], (0x1, b"x" * 300))
+
+    def test_http_error_is_reported(self):
+        def handler(c, req):
+            c.sendall(b'HTTP/1.1 404 Not Found\r\nContent-Type: application/json\r\n\r\n{"error":"sandbox not found"}')
+
+        port = _server(handler)
+        with self.assertRaises(terminal.WebSocketError) as e:
+            terminal.WebSocket(f"ws://127.0.0.1:{port}/x", {})
+        self.assertIn("sandbox not found", str(e.exception))
+
+    def test_cli_requires_key(self):
+        env = os.environ.pop("WBXSANDBOX_API_KEY", None)
+        try:
+            self.assertEqual(main(["connect", "sb_x", "--url", "http://127.0.0.1:1"]), 2)
+        finally:
+            if env is not None:
+                os.environ["WBXSANDBOX_API_KEY"] = env
+
+
+if __name__ == "__main__":
+    unittest.main()