boxd 0.1.0.dev2__py3-none-any.whl

boxd/types.py

@@ -0,0 +1,142 @@
+"""Data types for the boxd SDK."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class BoxConfig:
+    vcpu: int = 0
+    memory: str = ""
+    disk: str = ""
+    env: dict[str, str] | None = None
+    cmd: list[str] | None = None
+    restart_policy: str = "always"
+    lifecycle: LifecycleConfig | None = None
+    network: NetworkConfig | None = None
+    volumes: list[VolumeMount] | None = None
+
+
+@dataclass
+class LifecycleConfig:
+    auto_suspend_timeout: int = 0
+    auto_destroy_timeout: int = 0
+
+
+@dataclass
+class NetworkConfig:
+    ssh: bool = True
+    proxies: list[ProxyEntry] | None = None
+
+
+@dataclass
+class ProxyEntry:
+    name: str
+    port: int = 0
+
+
+@dataclass
+class VolumeMount:
+    disk_id: str
+    mount_path: str
+    read_only: bool = False
+
+
+@dataclass
+class Proxy:
+    name: str
+    vm_name: str
+    domain: str
+    port: int
+    is_default: bool
+
+
+@dataclass
+class Template:
+    id: str
+    name: str
+    image: str
+    status: str
+    vcpu: int
+    memory_bytes: int
+
+
+@dataclass
+class Disk:
+    id: str
+    name: str
+    size_bytes: int
+    status: str
+    attachments: list[DiskAttachment] = field(default_factory=list)
+
+
+@dataclass
+class DiskAttachment:
+    vm_id: str
+    vm_name: str
+    mount_path: str
+    mount_mode: str
+
+
+@dataclass
+class SuspendResult:
+    suspend_us: int
+
+
+@dataclass
+class ResumeResult:
+    resume_us: int
+
+
+@dataclass
+class PtyInfo:
+    rows: int = 24
+    cols: int = 80
+
+
+@dataclass
+class WhoamiResult:
+    user_id: str
+    fingerprints: list[str]
+    default_network_id: str
+
+
+@dataclass
+class ConfigResult:
+    default_image: str
+    zone: str
+
+
+@dataclass
+class Domain:
+    """An external domain bound to a VM."""
+
+    domain: str
+    vm_id: str
+
+
+@dataclass
+class Network:
+    """A user network."""
+
+    id: str
+    subnet: str
+    status: str
+
+
+@dataclass
+class Token:
+    """A freshly-issued JWT. The raw token is only available at creation time."""
+
+    token: str
+    expires_at: int
+
+
+@dataclass
+class TokenInfo:
+    """A previously-issued token (from list)."""
+
+    jti: str
+    created_at: int
+    expires_at: int

boxd-0.1.0.dev2.dist-info/METADATA

@@ -0,0 +1,329 @@
+Metadata-Version: 2.4
+Name: boxd
+Version: 0.1.0.dev2
+Summary: Python SDK for the boxd cloud VM platform
+Author: Azin
+License-Expression: MIT
+Project-URL: Homepage, https://boxd.sh
+Project-URL: Repository, https://github.com/azin-tech/boxd
+Project-URL: Issues, https://github.com/azin-tech/boxd/issues
+Keywords: boxd,vm,microvm,sandbox,compute,grpc,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Distributed Computing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: grpcio>=1.60
+Requires-Dist: protobuf>=4.25
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: grpcio-tools>=1.60; extra == "dev"
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=4.0; extra == "dev"
+Dynamic: license-file
+
+# boxd Python SDK
+
+Python SDK for the [boxd](https://boxd.sh) cloud VM platform. Sync-first API with full async support.
+
+Requires Python 3.10+.
+
+## Install
+
+```bash
+pip install boxd
+```
+
+## Quick Start
+
+```python
+from boxd import Compute
+
+with Compute(api_key="bxk_...") as c:
+    box = c.box.create(name="my-vm")
+    result = box.exec("echo", "hello")
+    print(result.stdout)
+    box.destroy()
+```
+
+## Authentication
+
+```python
+Compute(api_key="bxk_...")     # API key (recommended)
+Compute(token="eyJ...")        # direct JWT
+Compute()                      # reads BOXD_API_KEY or BOXD_TOKEN
+```
+
+## Configuration
+
+The SDK reads its endpoint configuration from constructor arguments or env vars:
+
+```python
+Compute(
+    api_key="bxk_...",
+    api_url="http://boxd.sh:9443",                     # default
+    exchange_url="https://boxd.sh/api/v1/auth/token",  # default
+)
+```
+
+Equivalent env vars: `BOXD_API_KEY`, `BOXD_TOKEN`, `BOXD_API_URL`, `BOXD_EXCHANGE_URL`.
+
+`api_url` accepts an optional URL scheme that controls TLS:
+
+| `api_url` value | Transport |
+|---|---|
+| `http://host:port` | plaintext (scheme stripped before connecting) |
+| `https://host:port` | TLS (scheme stripped before connecting) |
+| bare `host:port` | TLS, except `localhost` / `127.*` which stay plaintext |
+
+The default `http://boxd.sh:9443` matches production. Self-hosted clusters can pass `api_url="http://my-cluster:9443"` to opt into plaintext.
+
+## VM Lifecycle
+
+```python
+box = c.box.create(name="my-vm")
+boxes = c.box.list()
+found = c.box.get("my-vm")                             # by name or id
+forked = c.box.fork("my-vm", name="f1")
+
+box.start()
+box.stop()
+box.reboot()
+box.destroy()
+s = box.suspend()    # SuspendResult
+r = box.resume()     # ResumeResult
+```
+
+`Box` exposes the server-returned fields: `id`, `name`, `image`, `public_ip`, `status`, `url`, `boot_time_ms`. Forked VMs additionally carry `forked_from`. VMs returned by `c.box.get(...)` also expose `restart_policy`, `disk_bytes`, and `auto_suspend_timeout_secs`.
+
+## Exec
+
+```python
+# Simple — collect all output
+r = box.exec("python", "script.py")
+r.stdout       # str
+r.stderr       # str
+r.exit_code    # int
+r.success      # bool
+
+# With env vars and timeout
+box.exec("sh", "-c", "echo $FOO", env={"FOO": "bar"}, timeout=30)
+
+# Streaming
+proc = box.exec("tail", "-f", "/var/log/syslog", stream=True)
+for chunk in proc.iter_stdout():
+    print(chunk.decode(), end="")
+exit_code = proc.wait()
+
+# Interactive (PTY + stdin)
+sh = box.exec("bash", interactive=True)   # interactive implies pty
+```
+
+## Files
+
+```python
+from pathlib import Path
+
+box.write_file(b"binary content", "/app/file.bin")
+box.write_file("text content", "/app/file.txt")
+box.write_file(Path("local/file.py"), "/app/file.py")
+data = box.read_file("/app/output.json")    # bytes
+```
+
+## Proxies
+
+```python
+box.proxies()                              # list[Proxy]
+proxy = box.create_proxy("api", port=3001) # api.<vm>.boxd.sh -> port 3001
+box.set_proxy_port(port=3000)              # change default proxy port
+box.set_proxy_port(port=3001, name="api")  # change a named proxy
+box.delete_proxy("api")
+```
+
+## Logs
+
+```python
+# Snapshot of available console output
+for chunk in box.stream_logs():
+    print(chunk.decode(errors="replace"), end="")
+
+# Follow (keeps the stream open for new chunks)
+for chunk in box.stream_logs(follow=True):
+    print(chunk.decode(errors="replace"), end="")
+```
+
+## Templates
+
+```python
+from boxd import BoxConfig
+
+t = c.template.create(
+    name="t1",
+    image="ghcr.io/org/img:tag",
+    config=BoxConfig(vcpu=2, memory="4G"),
+)
+c.template.list()
+box = c.template.create_vm(template=t, name="from-t")
+c.template.delete(t.id)
+```
+
+## Disks
+
+```python
+d = c.disk.create("data", size="10G")
+d.attach(box, mount_path="/mnt/data")
+d.attach(box, mount_path="/mnt/data", read_only=True)
+d.detach(box)
+d.destroy()
+```
+
+## Domains
+
+Bind an external domain (DNS must already point at the boxd proxy).
+
+```python
+c.domain.bind("app.example.com", box)            # accepts a Box, name, or id
+c.domain.bind("app.example.com", "my-vm")
+for d in c.domain.list():
+    print(d.domain, "->", d.vm_id)
+c.domain.unbind("app.example.com")
+```
+
+## Networks
+
+```python
+n = c.network.create()                          # server assigns id
+named = c.network.create(name="staging")
+for net in c.network.list():
+    print(net.id, net.subnet, net.status)
+```
+
+## Tokens
+
+Issue scoped JWTs for delegated access. The raw token string is only returned at creation — store it then.
+
+```python
+t = c.token.create(expires_in=3600)             # 0 = server default
+t.token         # "eyJ..." — save this; list() will not return it
+t.expires_at    # unix seconds
+
+for info in c.token.list():
+    print(info.jti, info.created_at, info.expires_at)
+c.token.revoke(info.jti)
+
+# Use the token to authenticate a new client
+c2 = Compute(token=t.token)
+```
+
+## Identity
+
+```python
+me = c.whoami()
+me.user_id              # "gh-username"
+me.fingerprints         # ["SHA256:..."]
+me.default_network_id   # "net-..."
+
+cfg = c.config()
+cfg.default_image       # "ubuntu:latest"
+cfg.zone                # "boxd.sh"
+```
+
+## Errors
+
+```python
+from boxd import (
+    BoxdError,            # base class
+    AuthenticationError,
+    NotFoundError,
+    QuotaExceededError,
+    InvalidArgumentError,
+    TimeoutError,
+    ConnectionError,
+    InternalError,
+)
+
+try:
+    box = c.box.get("nope")
+except NotFoundError:
+    ...
+```
+
+| Class | gRPC status |
+|---|---|
+| `AuthenticationError` | `UNAUTHENTICATED`, `PERMISSION_DENIED` |
+| `NotFoundError` | `NOT_FOUND` |
+| `QuotaExceededError` | `RESOURCE_EXHAUSTED` |
+| `InvalidArgumentError` | `INVALID_ARGUMENT`, `ALREADY_EXISTS` |
+| `TimeoutError` | `DEADLINE_EXCEEDED` |
+| `ConnectionError` | `UNAVAILABLE` |
+| `InternalError` | `INTERNAL`, `UNKNOWN` |
+
+Each error carries the underlying `grpc_code` for finer-grained handling.
+
+## Sync vs Async
+
+The default import is the **sync API**, which wraps the async implementation using a dedicated event loop:
+
+```python
+from boxd import Compute             # sync — recommended for scripts and notebooks
+```
+
+For async code, import from `boxd.aio`:
+
+```python
+from boxd.aio import Compute
+
+async with Compute(api_key="bxk_...") as c:
+    box = await c.box.create(name="my-vm")
+    result = await box.exec("echo", "hello")
+```
+
+The two APIs are surface-equivalent — only the call style (sync vs `await`) differs.
+
+## Development
+
+```bash
+cd sdk/python
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+
+pytest tests/                              # unit tests (e2e marker excluded by default)
+pytest tests/ -m e2e                       # e2e tests (creates/destroys VMs)
+pytest tests/ -m ""                        # everything
+bash scripts/compile_proto.sh              # regenerate _generated/ after changing api.proto
+```
+
+## Architecture
+
+```
+sdk/python/
+├── src/boxd/
+│   ├── __init__.py       # public sync API exports (default import)
+│   ├── aio.py            # public async API exports
+│   ├── _sync.py          # sync wrappers (run_until_complete)
+│   ├── client.py         # async Compute (entry point) + auth/transport
+│   ├── auth.py           # API key → JWT exchange + refresh
+│   ├── boxes.py          # async BoxService (create/list/get/fork)
+│   ├── box.py            # async Box (lifecycle/exec/files/proxies/logs)
+│   ├── exec.py           # ExecResult, ExecProcess, stream readers/writers
+│   ├── templates.py      # async TemplateService
+│   ├── disks.py          # async DiskService + DiskHandle
+│   ├── domains.py        # async DomainService
+│   ├── networks.py       # async NetworkService
+│   ├── tokens.py         # async TokenService
+│   ├── types.py          # public dataclasses (BoxConfig, Proxy, etc.)
+│   ├── errors.py         # BoxdError hierarchy + gRPC mapping
+│   ├── _utils.py         # GrpcCaller mixin, parse_size, resolve_endpoint
+│   └── _generated/       # protoc-grpc-python output (committed)
+└── tests/                # pytest unit + gated e2e
+```

boxd-0.1.0.dev2.dist-info/RECORD

@@ -0,0 +1,24 @@
+boxd/__init__.py,sha256=2ef6pCn3mAVYXIpDYLdBifaCjMapYK64gQV9yJ0qyHA,2221
+boxd/_sync.py,sha256=iQdtUkEAoykoFihiVDvoO2yTEJDcR7y8YUrYBxlUPW8,14482
+boxd/_utils.py,sha256=Dh9pdq6ZM_7Yw0wsSP679USb1tRj74WQaIFflchIFyY,2287
+boxd/aio.py,sha256=Ojl0NqnpZjILz18APNUbQoTYWHEnqFxdyvVUTcM_JHM,1950
+boxd/auth.py,sha256=RXXrnZcJEt9Uho2a5CggfvY-PKoZ-epGCXyzk7Qbi1g,4353
+boxd/box.py,sha256=CKGsqF3ovLBZodg5MXI1iieNlVgT4BU1TsK7o4Ky-_g,11046
+boxd/boxes.py,sha256=8pFe0Fb2gUsN2WW4RLo5VJrOmj7NPqXI4Bl5RdhecdM,5342
+boxd/client.py,sha256=OIXy3GgstbOJyx9HBYGlQaPBs7nSNoJN69-TnT21Cr8,4327
+boxd/disks.py,sha256=L7IzyNdwKKSAWjoBdO3iHi7dHzfEWfU8XMeJw_AZ_5U,3110
+boxd/domains.py,sha256=tSoXpgBZILsfZz6owjBRa_a2oTEFCc8jZDqIxpfNnzA,1695
+boxd/errors.py,sha256=nXEsq6BJNEz2WienaHvY4fTi9NvZ7Ifl_jIZ65U6NB0,1659
+boxd/exec.py,sha256=Bu451UtanSx5Rssmg3gR-ZQQGOQCXBhfS2Qz2y1ggTU,3409
+boxd/networks.py,sha256=T5SZ6kVWJZVTcOl7VNajYuxmiNntZ7NgYmGo-chvyaI,1191
+boxd/templates.py,sha256=B7F8andarXwLwnp3Bk6T6rAib9xun3HlRf-MoiJCTBQ,3369
+boxd/tokens.py,sha256=9whIjTyBHBwBci_oSShHteqJFGBhBZniEAbqmv7nsxY,1621
+boxd/types.py,sha256=XEYxDAN4yYO-w9AEIslCQewDYMP8Zhqmfgzb7Qp-BWE,2120
+boxd/_generated/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+boxd/_generated/api_pb2.py,sha256=eC6-gyBTOAammi1xDKDdCf1IyESv9a-yMhCFFxcSgdQ,25061
+boxd/_generated/api_pb2_grpc.py,sha256=gx4ztNqCCShdwEUruDQ95HXrfjDVG83t02gXere5UVg,68255
+boxd-0.1.0.dev2.dist-info/licenses/LICENSE,sha256=rD8_32iKSf_QarUkwB8tTujEORtC3uYs4KIggm6cFKg,1061
+boxd-0.1.0.dev2.dist-info/METADATA,sha256=pKObr2Uxd8ro8rejkpRqlKL0qX2JVmJemQDtWNPK-P0,9417
+boxd-0.1.0.dev2.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+boxd-0.1.0.dev2.dist-info/top_level.txt,sha256=lJFbtvnDUx23dMMfX5hqRWPjtUhgrLpNJ9qdCPwON30,5
+boxd-0.1.0.dev2.dist-info/RECORD,,

boxd-0.1.0.dev2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

boxd-0.1.0.dev2.dist-info/licenses/LICENSE

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

boxd-0.1.0.dev2.dist-info/top_level.txt

@@ -0,0 +1 @@
+boxd