zipbox 0.1.0__tar.gz

zipbox-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/

zipbox-0.1.0/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.5
+Name: zipbox
+Version: 0.1.0
+Summary: Drive Zipbox boxes from Python: create, exec, files, PTY, previews.
+Project-URL: Homepage, https://zipbox.ai
+Project-URL: Documentation, https://zipbox.ai/docs/sdk-python
+Project-URL: Repository, https://github.com/tribes-protocol/zipbox-sdks
+Author: Tribes Protocol
+License-Expression: Apache-2.0
+Keywords: agents,mcp,sandbox,vm,zipbox
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: websockets>=13.0
+Description-Content-Type: text/markdown
+
+# zipbox
+
+Drive [Zipbox](https://zipbox.ai) boxes from Python: create a box, run commands, move
+files, open a terminal, publish a port. Boxes are long-lived machines — nothing on a box
+stops on a clock, and no SDK call has a default timeout.
+
+```sh
+pip install zipbox
+export ZIPBOX_API_KEY=zb_…   # zipbox.ai → Settings → API keys
+```
+
+## Quickstart
+
+```python
+from zipbox import Zipbox
+
+zb = Zipbox()
+box = zb.sandboxes.get_or_create("demo")
+result = box.exec("echo hello from $(hostname)")
+print(result.exit_code, result.stdout)
+box.files.write("notes/hello.txt", "hi")
+print(box.preview.create(3000).url)
+```
+
+Async is the same surface with `await`:
+
+```python
+from zipbox import AsyncZipbox
+
+async with AsyncZipbox() as zb:
+    box = await zb.sandboxes.get_or_create("demo")
+    print((await box.exec("uname -a")).stdout)
+```
+
+## What is in it
+
+| Area      | Calls                                                                                                                                             |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Lifecycle | `zb.sandboxes.create(name=, tier=)`, `get_or_create`, `list`, `get`, `start`, `stop`, `restart`, `delete`, `set_tier`; `zb.sandbox(id)`           |
+| Exec      | `box.exec(cmd)` → `ExecResult(id, exit_code, stdout, stderr)`; `exec_stream(cmd)`; `exec_background(cmd)` → `Command`; `run_code("python", code)` |
+| Commands  | `Command.get()`, `events(since=)`, `wait()`, `stdin(data)`, `close_stdin()`, `signal("TERM")`; `box.commands.list/get/events/stdin/signal`        |
+| Files     | `box.files.read`, `read_text`, `write`, `list`, `stat`, `mkdir`, `move`, `delete`, `upload`, `download`                                           |
+| PTY       | `box.pty.create(cols=, rows=)` / `attach(session_id)` → `write`, `resize`, `on_data`, iterate, `detach`, `close`, `wait`                          |
+| Previews  | `box.preview.create(port, label=)` → `Preview(url, label)`; `remove(label)`                                                                       |
+| Other     | `box.logs(since=)`, `box.ssh_info()`, `box.screenshot()`, `zb.account.balance()`, `usage()`                                                       |
+
+A string command runs under `bash -lc` (your PATH, nvm, pyenv); a list is spawned as argv.
+A command that exits non-zero is a result: check `exit_code`. Relative paths resolve
+against `/root/workspace`.
+
+`exec` and `exec_stream` kill the command if you disconnect before it exits. A command
+started with `exec_background` keeps running with nobody attached — re-attach any time
+with `box.commands.handle(id).events(since=cursor)`.
+
+## Errors
+
+Every failure raises `ZipboxError` with `code` (`invalid_request`, `unauthorized`,
+`forbidden`, `not_found`, `insufficient_credits`, `conflict`, `rate_limited`,
+`box_not_running`, `unavailable`), `status`, `message`, `request_id`, `retryable`,
+`retry_after_ms` and `docs_url`. `rate_limited` and `unavailable` are retried
+automatically on reads and on `create` (`max_retries`, default 3).
+
+## Configuration
+
+`Zipbox(api_key=None, base_url=None, max_retries=3, http_client=None)`. The key and URL
+default to `ZIPBOX_API_KEY` and `ZIPBOX_API_URL` (else `https://api.tribes.xyz`).
+
+Docs: [zipbox.ai/docs/sdk-python](https://zipbox.ai/docs/sdk-python) · Agent index:
+[zipbox.ai/llms.txt](https://zipbox.ai/llms.txt) · Apache-2.0.

zipbox-0.1.0/README.md

@@ -0,0 +1,69 @@
+# zipbox
+
+Drive [Zipbox](https://zipbox.ai) boxes from Python: create a box, run commands, move
+files, open a terminal, publish a port. Boxes are long-lived machines — nothing on a box
+stops on a clock, and no SDK call has a default timeout.
+
+```sh
+pip install zipbox
+export ZIPBOX_API_KEY=zb_…   # zipbox.ai → Settings → API keys
+```
+
+## Quickstart
+
+```python
+from zipbox import Zipbox
+
+zb = Zipbox()
+box = zb.sandboxes.get_or_create("demo")
+result = box.exec("echo hello from $(hostname)")
+print(result.exit_code, result.stdout)
+box.files.write("notes/hello.txt", "hi")
+print(box.preview.create(3000).url)
+```
+
+Async is the same surface with `await`:
+
+```python
+from zipbox import AsyncZipbox
+
+async with AsyncZipbox() as zb:
+    box = await zb.sandboxes.get_or_create("demo")
+    print((await box.exec("uname -a")).stdout)
+```
+
+## What is in it
+
+| Area      | Calls                                                                                                                                             |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Lifecycle | `zb.sandboxes.create(name=, tier=)`, `get_or_create`, `list`, `get`, `start`, `stop`, `restart`, `delete`, `set_tier`; `zb.sandbox(id)`           |
+| Exec      | `box.exec(cmd)` → `ExecResult(id, exit_code, stdout, stderr)`; `exec_stream(cmd)`; `exec_background(cmd)` → `Command`; `run_code("python", code)` |
+| Commands  | `Command.get()`, `events(since=)`, `wait()`, `stdin(data)`, `close_stdin()`, `signal("TERM")`; `box.commands.list/get/events/stdin/signal`        |
+| Files     | `box.files.read`, `read_text`, `write`, `list`, `stat`, `mkdir`, `move`, `delete`, `upload`, `download`                                           |
+| PTY       | `box.pty.create(cols=, rows=)` / `attach(session_id)` → `write`, `resize`, `on_data`, iterate, `detach`, `close`, `wait`                          |
+| Previews  | `box.preview.create(port, label=)` → `Preview(url, label)`; `remove(label)`                                                                       |
+| Other     | `box.logs(since=)`, `box.ssh_info()`, `box.screenshot()`, `zb.account.balance()`, `usage()`                                                       |
+
+A string command runs under `bash -lc` (your PATH, nvm, pyenv); a list is spawned as argv.
+A command that exits non-zero is a result: check `exit_code`. Relative paths resolve
+against `/root/workspace`.
+
+`exec` and `exec_stream` kill the command if you disconnect before it exits. A command
+started with `exec_background` keeps running with nobody attached — re-attach any time
+with `box.commands.handle(id).events(since=cursor)`.
+
+## Errors
+
+Every failure raises `ZipboxError` with `code` (`invalid_request`, `unauthorized`,
+`forbidden`, `not_found`, `insufficient_credits`, `conflict`, `rate_limited`,
+`box_not_running`, `unavailable`), `status`, `message`, `request_id`, `retryable`,
+`retry_after_ms` and `docs_url`. `rate_limited` and `unavailable` are retried
+automatically on reads and on `create` (`max_retries`, default 3).
+
+## Configuration
+
+`Zipbox(api_key=None, base_url=None, max_retries=3, http_client=None)`. The key and URL
+default to `ZIPBOX_API_KEY` and `ZIPBOX_API_URL` (else `https://api.tribes.xyz`).
+
+Docs: [zipbox.ai/docs/sdk-python](https://zipbox.ai/docs/sdk-python) · Agent index:
+[zipbox.ai/llms.txt](https://zipbox.ai/llms.txt) · Apache-2.0.

zipbox-0.1.0/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "zipbox"
+version = "0.1.0"
+description = "Drive Zipbox boxes from Python: create, exec, files, PTY, previews."
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.10"
+authors = [{ name = "Tribes Protocol" }]
+keywords = ["zipbox", "sandbox", "vm", "agents", "mcp"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Typing :: Typed",
+  "Operating System :: OS Independent",
+]
+dependencies = ["httpx>=0.27", "websockets>=13.0"]
+
+[project.urls]
+Homepage = "https://zipbox.ai"
+Documentation = "https://zipbox.ai/docs/sdk-python"
+Repository = "https://github.com/tribes-protocol/zipbox-sdks"
+
+[dependency-groups]
+dev = ["pytest>=8", "pytest-asyncio>=0.24", "mypy>=1.11", "ruff>=0.6"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/zipbox"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+
+[tool.mypy]
+strict = true
+python_version = "3.10"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "SIM", "RUF"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["zipbox", "mock_server"]
+
+[[tool.mypy.overrides]]
+module = ["langchain_core.*", "langchain_openai.*", "langgraph.*"]
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = ["langchain_tool", "langgraph_agent"]
+disallow_untyped_decorators = false
+disallow_any_unimported = false
+warn_return_any = false

zipbox-0.1.0/src/zipbox/__init__.py

@@ -0,0 +1,91 @@
+"""Zipbox SDK: drive Zipbox boxes from Python.
+
+>>> from zipbox import Zipbox
+>>> zb = Zipbox()  # reads ZIPBOX_API_KEY
+>>> box = zb.sandboxes.get_or_create("demo")
+>>> print(box.exec("echo hello").stdout)
+"""
+
+from zipbox._async_client import (
+    AsyncAccount,
+    AsyncCommand,
+    AsyncCommands,
+    AsyncFiles,
+    AsyncPreviews,
+    AsyncPtyApi,
+    AsyncSandbox,
+    AsyncSandboxes,
+    AsyncZipbox,
+)
+from zipbox._client import (
+    Account,
+    Command,
+    Commands,
+    Files,
+    Previews,
+    PtyApi,
+    Sandbox,
+    Sandboxes,
+    Zipbox,
+)
+from zipbox._core import DEFAULT_API_URL, VERSION, WORKSPACE
+from zipbox._errors import ErrorCode, ZipboxError
+from zipbox._models import (
+    CommandInfo,
+    CommandState,
+    ExecEvent,
+    ExecResult,
+    FileEntry,
+    FileKind,
+    Language,
+    Preview,
+    SandboxDetail,
+    SandboxInfo,
+    Signal,
+    SshInfo,
+    Tier,
+)
+from zipbox._pty import AsyncPty, Pty
+
+__version__ = VERSION
+
+__all__ = [
+    "DEFAULT_API_URL",
+    "WORKSPACE",
+    "Account",
+    "AsyncAccount",
+    "AsyncCommand",
+    "AsyncCommands",
+    "AsyncFiles",
+    "AsyncPreviews",
+    "AsyncPty",
+    "AsyncPtyApi",
+    "AsyncSandbox",
+    "AsyncSandboxes",
+    "AsyncZipbox",
+    "Command",
+    "CommandInfo",
+    "CommandState",
+    "Commands",
+    "ErrorCode",
+    "ExecEvent",
+    "ExecResult",
+    "FileEntry",
+    "FileKind",
+    "Files",
+    "Language",
+    "Preview",
+    "Previews",
+    "Pty",
+    "PtyApi",
+    "Sandbox",
+    "SandboxDetail",
+    "SandboxInfo",
+    "Sandboxes",
+    "Signal",
+    "SshInfo",
+    "Tier",
+    "Zipbox",
+    "ZipboxError",
+    "__version__",
+]