boxd 0.1.1.dev7__tar.gz → 0.1.2__tar.gz

{boxd-0.1.1.dev7/src/boxd.egg-info → boxd-0.1.2}/PKG-INFO

@@ -1,12 +1,10 @@
 Metadata-Version: 2.4
 Name: boxd
-Version: 0.1.1.dev7
+Version: 0.1.2
 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
@@ -84,9 +82,17 @@ Compute(
 )
 ```
 
-Env vars `BOXD_API_URL` / `BOXD_EXCHANGE_URL` override the preset too.
+### Environment variables
 
-Equivalent env vars: `BOXD_API_KEY`, `BOXD_TOKEN`, `BOXD_API_URL`, `BOXD_EXCHANGE_URL`.
+All `Compute` arguments can be supplied via env vars. Constructor args win over env vars; env vars win over the `environment` preset.
+
+| Variable | Sets | Default |
+|---|---|---|
+| `BOXD_API_KEY` | API key (long-lived, recommended) | — |
+| `BOXD_TOKEN` | Direct JWT (short-lived) | — |
+| `BOXD_ENVIRONMENT` | Preset name (`production` or `staging`) | `production` |
+| `BOXD_API_URL` | gRPC endpoint, overrides preset | `http://boxd.sh:9443` |
+| `BOXD_EXCHANGE_URL` | Token-exchange URL, overrides preset | `https://boxd.sh/api/v1/auth/token` |
 
 `api_url` accepts an optional URL scheme that controls TLS:
 
@@ -114,7 +120,39 @@ 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`.
+### Box fields
+
+`Box` always carries server-returned fields, but which ones are populated depends on how it was obtained:
+
+| Field | `create` | `fork` | `list` | `get` |
+|---|---|---|---|---|
+| `id`, `name`, `image`, `public_ip`, `status` | ✓ | ✓ | ✓ | ✓ |
+| `url`, `boot_time_ms` | ✓ | ✓ | `None` | `None` |
+| `forked_from` | `None` | ✓ | `None` | `None` |
+| `restart_policy`, `disk_bytes`, `auto_suspend_timeout_secs` | `None` | `None` | `None` | ✓ |
+
+If you need the URL or boot time after a `list` / `get` round-trip, the `https://<name>.boxd.sh` form is stable, or call `box.proxies()` for the full set. If you need the lifecycle fields off a `Box` from `list` / `create` / `fork`, re-fetch via `c.box.get(box.name)`.
+
+### BoxConfig
+
+`create`, `fork`, and `template.create_vm` all take an optional `config`:
+
+```python
+from boxd import BoxConfig, LifecycleConfig
+
+config = BoxConfig(
+    vcpu=2,                           # default 2
+    memory="4G",                      # default "8G"
+    env={"API_KEY": "secret"},        # env vars exposed to the VM
+    restart_policy="always",          # "always" | "never"
+    lifecycle=LifecycleConfig(
+        auto_suspend_timeout=300,     # idle network secs; 0 disables
+        auto_destroy_timeout=0,       # total lifetime secs; 0 disables
+    ),
+)
+
+box = c.box.create(name="my-vm", config=config)
+```
 
 ## Exec
 
@@ -124,19 +162,25 @@ r = box.exec("python", "script.py")
 r.stdout       # str
 r.stderr       # str
 r.exit_code    # int
-r.success      # bool
+r.success      # bool — exit_code == 0
 
 # With env vars and timeout
 box.exec("sh", "-c", "echo $FOO", env={"FOO": "bar"}, timeout=30)
 
-# Streaming
+# Streaming — proc is an ExecProcess. Use iter_stdout / iter_stderr
+# (sync generators that block until the next chunk arrives), then wait()
+# for the exit code. close() force-terminates the stream.
 proc = box.exec("tail", "-f", "/var/log/syslog", stream=True)
 for chunk in proc.iter_stdout():
     print(chunk.decode(), end="")
 exit_code = proc.wait()
+proc.close()                               # idempotent
 
-# Interactive (PTY + stdin)
-sh = box.exec("bash", interactive=True)   # interactive implies pty
+# Interactive (PTY + stdin) — write to proc.stdin, end with write_eof
+sh = box.exec("bash", interactive=True)    # interactive implies pty
+sh.stdin.write(b"echo hello\n")
+sh.stdin.write_eof()
+print(sh.wait())
 ```
 
 ## Files
@@ -174,6 +218,8 @@ for chunk in box.stream_logs(follow=True):
 
 ## Templates
 
+Reusable image + `BoxConfig` frozen together.
+
 ```python
 from boxd import BoxConfig
 
@@ -183,7 +229,16 @@ t = c.template.create(
     config=BoxConfig(vcpu=2, memory="4G"),
 )
 c.template.list()
+
+# create_vm accepts a Template object OR a template ID string. Pass an
+# optional `config` to override the template's defaults (e.g. bump
+# memory for one specific VM).
 box = c.template.create_vm(template=t, name="from-t")
+big = c.template.create_vm(
+    template=t.id,
+    name="from-t-big",
+    config=BoxConfig(memory="16G"),
+)
 c.template.delete(t.id)
 ```
 
@@ -191,10 +246,18 @@ c.template.delete(t.id)
 
 ```python
 d = c.disk.create("data", size="10G")
+d.id; d.name; d.size_bytes; d.status
+
+# attach / detach take a Box instance OR a name/id string
 d.attach(box, mount_path="/mnt/data")
-d.attach(box, mount_path="/mnt/data", read_only=True)
-d.detach(box)
+d.attach("my-vm", mount_path="/mnt/data", read_only=True)
+d.detach("my-vm")
+
 d.destroy()
+
+# list returns DiskHandle instances — same methods as above
+for d in c.disk.list():
+    print(d.name, d.status)
 ```
 
 ## Domains
@@ -212,8 +275,11 @@ c.domain.unbind("app.example.com")
 ## Networks
 
 ```python
-n = c.network.create()                          # server assigns id
+n = c.network.create()              # server assigns id
 named = c.network.create(name="staging")
+
+# `create` returns the new network's id only — `subnet` and `status` come
+# back populated once provisioning settles. Re-fetch via `list` to read them.
 for net in c.network.list():
     print(net.id, net.subnet, net.status)
 ```
@@ -223,13 +289,18 @@ for net in c.network.list():
 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
+t = c.token.create(expires_in=3600)   # 0 = server default
+t.token         # str — "eyJ..."  save this; list() will not return it again
+t.expires_at    # int — unix seconds
 
+# list() returns TokenInfo (no raw token; listing-safe metadata).
+# The `jti` field here is what revoke() takes — there's no jti on
+# the freshly-created Token, so revoke goes through list().
 for info in c.token.list():
-    print(info.jti, info.created_at, info.expires_at)
-c.token.revoke(info.jti)
+    info.jti          # str — used by revoke()
+    info.created_at   # int — unix seconds
+    info.expires_at   # int — unix seconds
+    c.token.revoke(info.jti)
 
 # Use the token to authenticate a new client
 c2 = Compute(token=t.token)
@@ -248,6 +319,13 @@ cfg.default_image       # "ubuntu:latest"
 cfg.zone                # "boxd.sh"
 ```
 
+The package also exposes its installed version:
+
+```python
+import boxd
+print("on", boxd.__version__)
+```
+
 ## Errors
 
 ```python
@@ -278,17 +356,39 @@ except NotFoundError:
 | `ConnectionError` | `UNAVAILABLE` |
 | `InternalError` | `INTERNAL`, `UNKNOWN` |
 
-Each error carries the underlying `grpc_code` for finer-grained handling.
+Each error carries the underlying `grpc_code` (numeric gRPC status — see [grpc.StatusCode](https://grpc.github.io/grpc/core/md_doc_statuscodes.html)) for finer-grained handling:
+
+```python
+import grpc
+
+try:
+    c.box.create(name="my-vm")
+except BoxdError as e:
+    if e.grpc_code == grpc.StatusCode.RESOURCE_EXHAUSTED.value[0]:
+        ...   # hit per-user quota
+    raise
+```
+
+## Update notifications
+
+Every gRPC response carries an `x-boxd-py-sdk-latest` header set by the boxd proxy. The SDK's interceptor compares it to the installed version and prints a one-time `sys.stderr` line if a newer release is available:
+
+```
+A new version of boxd is available (v0.1.2, you have v0.1.1). Update with:
+  pip install --upgrade boxd
+```
+
+The notice fires at most once per process, never causes a request to fail, and is silent if the proxy isn't advertising a newer version. Compares as PEP 440-ish (numeric prefix, then per-component compare on `.devN` suffixes).
 
 ## Sync vs Async
 
-The default import is the **sync API**, which wraps the async implementation using a dedicated event loop:
+The default `boxd.Compute` is the **sync API** — fully blocking, safe for scripts, REPLs, notebooks, Django views, anywhere you don't already have an event loop. It wraps the async implementation behind a dedicated background loop, so you don't pay for `asyncio` setup yourself.
 
 ```python
-from boxd import Compute             # sync — recommended for scripts and notebooks
+from boxd import Compute             # sync — recommended default
 ```
 
-For async code, import from `boxd.aio`:
+`boxd.aio.Compute` is the **async API** — use it from inside an existing event loop (FastAPI, asyncio scripts, Quart, anyio):
 
 ```python
 from boxd.aio import Compute
@@ -298,7 +398,7 @@ async with Compute(api_key="bxk_...") as c:
     result = await box.exec("echo", "hello")
 ```
 
-The two APIs are surface-equivalent — only the call style (sync vs `await`) differs.
+The two are surface-equivalent: same method names, same arguments, same return types. The only differences are `with` vs `async with` and the `await` keyword on every call. **Pick `boxd` unless you already have an event loop.**
 
 ## Development
 

{boxd-0.1.1.dev7 → boxd-0.1.2}/README.md

@@ -51,9 +51,17 @@ Compute(
 )
 ```
 
-Env vars `BOXD_API_URL` / `BOXD_EXCHANGE_URL` override the preset too.
+### Environment variables
 
-Equivalent env vars: `BOXD_API_KEY`, `BOXD_TOKEN`, `BOXD_API_URL`, `BOXD_EXCHANGE_URL`.
+All `Compute` arguments can be supplied via env vars. Constructor args win over env vars; env vars win over the `environment` preset.
+
+| Variable | Sets | Default |
+|---|---|---|
+| `BOXD_API_KEY` | API key (long-lived, recommended) | — |
+| `BOXD_TOKEN` | Direct JWT (short-lived) | — |
+| `BOXD_ENVIRONMENT` | Preset name (`production` or `staging`) | `production` |
+| `BOXD_API_URL` | gRPC endpoint, overrides preset | `http://boxd.sh:9443` |
+| `BOXD_EXCHANGE_URL` | Token-exchange URL, overrides preset | `https://boxd.sh/api/v1/auth/token` |
 
 `api_url` accepts an optional URL scheme that controls TLS:
 
@@ -81,7 +89,39 @@ 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`.
+### Box fields
+
+`Box` always carries server-returned fields, but which ones are populated depends on how it was obtained:
+
+| Field | `create` | `fork` | `list` | `get` |
+|---|---|---|---|---|
+| `id`, `name`, `image`, `public_ip`, `status` | ✓ | ✓ | ✓ | ✓ |
+| `url`, `boot_time_ms` | ✓ | ✓ | `None` | `None` |
+| `forked_from` | `None` | ✓ | `None` | `None` |
+| `restart_policy`, `disk_bytes`, `auto_suspend_timeout_secs` | `None` | `None` | `None` | ✓ |
+
+If you need the URL or boot time after a `list` / `get` round-trip, the `https://<name>.boxd.sh` form is stable, or call `box.proxies()` for the full set. If you need the lifecycle fields off a `Box` from `list` / `create` / `fork`, re-fetch via `c.box.get(box.name)`.
+
+### BoxConfig
+
+`create`, `fork`, and `template.create_vm` all take an optional `config`:
+
+```python
+from boxd import BoxConfig, LifecycleConfig
+
+config = BoxConfig(
+    vcpu=2,                           # default 2
+    memory="4G",                      # default "8G"
+    env={"API_KEY": "secret"},        # env vars exposed to the VM
+    restart_policy="always",          # "always" | "never"
+    lifecycle=LifecycleConfig(
+        auto_suspend_timeout=300,     # idle network secs; 0 disables
+        auto_destroy_timeout=0,       # total lifetime secs; 0 disables
+    ),
+)
+
+box = c.box.create(name="my-vm", config=config)
+```
 
 ## Exec
 
@@ -91,19 +131,25 @@ r = box.exec("python", "script.py")
 r.stdout       # str
 r.stderr       # str
 r.exit_code    # int
-r.success      # bool
+r.success      # bool — exit_code == 0
 
 # With env vars and timeout
 box.exec("sh", "-c", "echo $FOO", env={"FOO": "bar"}, timeout=30)
 
-# Streaming
+# Streaming — proc is an ExecProcess. Use iter_stdout / iter_stderr
+# (sync generators that block until the next chunk arrives), then wait()
+# for the exit code. close() force-terminates the stream.
 proc = box.exec("tail", "-f", "/var/log/syslog", stream=True)
 for chunk in proc.iter_stdout():
     print(chunk.decode(), end="")
 exit_code = proc.wait()
+proc.close()                               # idempotent
 
-# Interactive (PTY + stdin)
-sh = box.exec("bash", interactive=True)   # interactive implies pty
+# Interactive (PTY + stdin) — write to proc.stdin, end with write_eof
+sh = box.exec("bash", interactive=True)    # interactive implies pty
+sh.stdin.write(b"echo hello\n")
+sh.stdin.write_eof()
+print(sh.wait())
 ```
 
 ## Files
@@ -141,6 +187,8 @@ for chunk in box.stream_logs(follow=True):
 
 ## Templates
 
+Reusable image + `BoxConfig` frozen together.
+
 ```python
 from boxd import BoxConfig
 
@@ -150,7 +198,16 @@ t = c.template.create(
     config=BoxConfig(vcpu=2, memory="4G"),
 )
 c.template.list()
+
+# create_vm accepts a Template object OR a template ID string. Pass an
+# optional `config` to override the template's defaults (e.g. bump
+# memory for one specific VM).
 box = c.template.create_vm(template=t, name="from-t")
+big = c.template.create_vm(
+    template=t.id,
+    name="from-t-big",
+    config=BoxConfig(memory="16G"),
+)
 c.template.delete(t.id)
 ```
 
@@ -158,10 +215,18 @@ c.template.delete(t.id)
 
 ```python
 d = c.disk.create("data", size="10G")
+d.id; d.name; d.size_bytes; d.status
+
+# attach / detach take a Box instance OR a name/id string
 d.attach(box, mount_path="/mnt/data")
-d.attach(box, mount_path="/mnt/data", read_only=True)
-d.detach(box)
+d.attach("my-vm", mount_path="/mnt/data", read_only=True)
+d.detach("my-vm")
+
 d.destroy()
+
+# list returns DiskHandle instances — same methods as above
+for d in c.disk.list():
+    print(d.name, d.status)
 ```
 
 ## Domains
@@ -179,8 +244,11 @@ c.domain.unbind("app.example.com")
 ## Networks
 
 ```python
-n = c.network.create()                          # server assigns id
+n = c.network.create()              # server assigns id
 named = c.network.create(name="staging")
+
+# `create` returns the new network's id only — `subnet` and `status` come
+# back populated once provisioning settles. Re-fetch via `list` to read them.
 for net in c.network.list():
     print(net.id, net.subnet, net.status)
 ```
@@ -190,13 +258,18 @@ for net in c.network.list():
 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
+t = c.token.create(expires_in=3600)   # 0 = server default
+t.token         # str — "eyJ..."  save this; list() will not return it again
+t.expires_at    # int — unix seconds
 
+# list() returns TokenInfo (no raw token; listing-safe metadata).
+# The `jti` field here is what revoke() takes — there's no jti on
+# the freshly-created Token, so revoke goes through list().
 for info in c.token.list():
-    print(info.jti, info.created_at, info.expires_at)
-c.token.revoke(info.jti)
+    info.jti          # str — used by revoke()
+    info.created_at   # int — unix seconds
+    info.expires_at   # int — unix seconds
+    c.token.revoke(info.jti)
 
 # Use the token to authenticate a new client
 c2 = Compute(token=t.token)
@@ -215,6 +288,13 @@ cfg.default_image       # "ubuntu:latest"
 cfg.zone                # "boxd.sh"
 ```
 
+The package also exposes its installed version:
+
+```python
+import boxd
+print("on", boxd.__version__)
+```
+
 ## Errors
 
 ```python
@@ -245,17 +325,39 @@ except NotFoundError:
 | `ConnectionError` | `UNAVAILABLE` |
 | `InternalError` | `INTERNAL`, `UNKNOWN` |
 
-Each error carries the underlying `grpc_code` for finer-grained handling.
+Each error carries the underlying `grpc_code` (numeric gRPC status — see [grpc.StatusCode](https://grpc.github.io/grpc/core/md_doc_statuscodes.html)) for finer-grained handling:
+
+```python
+import grpc
+
+try:
+    c.box.create(name="my-vm")
+except BoxdError as e:
+    if e.grpc_code == grpc.StatusCode.RESOURCE_EXHAUSTED.value[0]:
+        ...   # hit per-user quota
+    raise
+```
+
+## Update notifications
+
+Every gRPC response carries an `x-boxd-py-sdk-latest` header set by the boxd proxy. The SDK's interceptor compares it to the installed version and prints a one-time `sys.stderr` line if a newer release is available:
+
+```
+A new version of boxd is available (v0.1.2, you have v0.1.1). Update with:
+  pip install --upgrade boxd
+```
+
+The notice fires at most once per process, never causes a request to fail, and is silent if the proxy isn't advertising a newer version. Compares as PEP 440-ish (numeric prefix, then per-component compare on `.devN` suffixes).
 
 ## Sync vs Async
 
-The default import is the **sync API**, which wraps the async implementation using a dedicated event loop:
+The default `boxd.Compute` is the **sync API** — fully blocking, safe for scripts, REPLs, notebooks, Django views, anywhere you don't already have an event loop. It wraps the async implementation behind a dedicated background loop, so you don't pay for `asyncio` setup yourself.
 
 ```python
-from boxd import Compute             # sync — recommended for scripts and notebooks
+from boxd import Compute             # sync — recommended default
 ```
 
-For async code, import from `boxd.aio`:
+`boxd.aio.Compute` is the **async API** — use it from inside an existing event loop (FastAPI, asyncio scripts, Quart, anyio):
 
 ```python
 from boxd.aio import Compute
@@ -265,7 +367,7 @@ async with Compute(api_key="bxk_...") as c:
     result = await box.exec("echo", "hello")
 ```
 
-The two APIs are surface-equivalent — only the call style (sync vs `await`) differs.
+The two are surface-equivalent: same method names, same arguments, same return types. The only differences are `with` vs `async with` and the `await` keyword on every call. **Pick `boxd` unless you already have an event loop.**
 
 ## Development
 

{boxd-0.1.1.dev7 → boxd-0.1.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "boxd"
-version = "0.1.1.dev7"
+version = "0.1.2"
 description = "Python SDK for the boxd cloud VM platform"
 readme = "README.md"
 license = "MIT"
@@ -33,8 +33,6 @@ dependencies = [
 
 [project.urls]
 Homepage = "https://boxd.sh"
-Repository = "https://github.com/azin-tech/boxd"
-Issues = "https://github.com/azin-tech/boxd/issues"
 
 [project.optional-dependencies]
 dev = [

{boxd-0.1.1.dev7 → boxd-0.1.2/src/boxd.egg-info}/PKG-INFO

@@ -1,12 +1,10 @@
 Metadata-Version: 2.4
 Name: boxd
-Version: 0.1.1.dev7
+Version: 0.1.2
 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
@@ -84,9 +82,17 @@ Compute(
 )
 ```
 
-Env vars `BOXD_API_URL` / `BOXD_EXCHANGE_URL` override the preset too.
+### Environment variables
 
-Equivalent env vars: `BOXD_API_KEY`, `BOXD_TOKEN`, `BOXD_API_URL`, `BOXD_EXCHANGE_URL`.
+All `Compute` arguments can be supplied via env vars. Constructor args win over env vars; env vars win over the `environment` preset.
+
+| Variable | Sets | Default |
+|---|---|---|
+| `BOXD_API_KEY` | API key (long-lived, recommended) | — |
+| `BOXD_TOKEN` | Direct JWT (short-lived) | — |
+| `BOXD_ENVIRONMENT` | Preset name (`production` or `staging`) | `production` |
+| `BOXD_API_URL` | gRPC endpoint, overrides preset | `http://boxd.sh:9443` |
+| `BOXD_EXCHANGE_URL` | Token-exchange URL, overrides preset | `https://boxd.sh/api/v1/auth/token` |
 
 `api_url` accepts an optional URL scheme that controls TLS:
 
@@ -114,7 +120,39 @@ 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`.
+### Box fields
+
+`Box` always carries server-returned fields, but which ones are populated depends on how it was obtained:
+
+| Field | `create` | `fork` | `list` | `get` |
+|---|---|---|---|---|
+| `id`, `name`, `image`, `public_ip`, `status` | ✓ | ✓ | ✓ | ✓ |
+| `url`, `boot_time_ms` | ✓ | ✓ | `None` | `None` |
+| `forked_from` | `None` | ✓ | `None` | `None` |
+| `restart_policy`, `disk_bytes`, `auto_suspend_timeout_secs` | `None` | `None` | `None` | ✓ |
+
+If you need the URL or boot time after a `list` / `get` round-trip, the `https://<name>.boxd.sh` form is stable, or call `box.proxies()` for the full set. If you need the lifecycle fields off a `Box` from `list` / `create` / `fork`, re-fetch via `c.box.get(box.name)`.
+
+### BoxConfig
+
+`create`, `fork`, and `template.create_vm` all take an optional `config`:
+
+```python
+from boxd import BoxConfig, LifecycleConfig
+
+config = BoxConfig(
+    vcpu=2,                           # default 2
+    memory="4G",                      # default "8G"
+    env={"API_KEY": "secret"},        # env vars exposed to the VM
+    restart_policy="always",          # "always" | "never"
+    lifecycle=LifecycleConfig(
+        auto_suspend_timeout=300,     # idle network secs; 0 disables
+        auto_destroy_timeout=0,       # total lifetime secs; 0 disables
+    ),
+)
+
+box = c.box.create(name="my-vm", config=config)
+```
 
 ## Exec
 
@@ -124,19 +162,25 @@ r = box.exec("python", "script.py")
 r.stdout       # str
 r.stderr       # str
 r.exit_code    # int
-r.success      # bool
+r.success      # bool — exit_code == 0
 
 # With env vars and timeout
 box.exec("sh", "-c", "echo $FOO", env={"FOO": "bar"}, timeout=30)
 
-# Streaming
+# Streaming — proc is an ExecProcess. Use iter_stdout / iter_stderr
+# (sync generators that block until the next chunk arrives), then wait()
+# for the exit code. close() force-terminates the stream.
 proc = box.exec("tail", "-f", "/var/log/syslog", stream=True)
 for chunk in proc.iter_stdout():
     print(chunk.decode(), end="")
 exit_code = proc.wait()
+proc.close()                               # idempotent
 
-# Interactive (PTY + stdin)
-sh = box.exec("bash", interactive=True)   # interactive implies pty
+# Interactive (PTY + stdin) — write to proc.stdin, end with write_eof
+sh = box.exec("bash", interactive=True)    # interactive implies pty
+sh.stdin.write(b"echo hello\n")
+sh.stdin.write_eof()
+print(sh.wait())
 ```
 
 ## Files
@@ -174,6 +218,8 @@ for chunk in box.stream_logs(follow=True):
 
 ## Templates
 
+Reusable image + `BoxConfig` frozen together.
+
 ```python
 from boxd import BoxConfig
 
@@ -183,7 +229,16 @@ t = c.template.create(
     config=BoxConfig(vcpu=2, memory="4G"),
 )
 c.template.list()
+
+# create_vm accepts a Template object OR a template ID string. Pass an
+# optional `config` to override the template's defaults (e.g. bump
+# memory for one specific VM).
 box = c.template.create_vm(template=t, name="from-t")
+big = c.template.create_vm(
+    template=t.id,
+    name="from-t-big",
+    config=BoxConfig(memory="16G"),
+)
 c.template.delete(t.id)
 ```
 
@@ -191,10 +246,18 @@ c.template.delete(t.id)
 
 ```python
 d = c.disk.create("data", size="10G")
+d.id; d.name; d.size_bytes; d.status
+
+# attach / detach take a Box instance OR a name/id string
 d.attach(box, mount_path="/mnt/data")
-d.attach(box, mount_path="/mnt/data", read_only=True)
-d.detach(box)
+d.attach("my-vm", mount_path="/mnt/data", read_only=True)
+d.detach("my-vm")
+
 d.destroy()
+
+# list returns DiskHandle instances — same methods as above
+for d in c.disk.list():
+    print(d.name, d.status)
 ```
 
 ## Domains
@@ -212,8 +275,11 @@ c.domain.unbind("app.example.com")
 ## Networks
 
 ```python
-n = c.network.create()                          # server assigns id
+n = c.network.create()              # server assigns id
 named = c.network.create(name="staging")
+
+# `create` returns the new network's id only — `subnet` and `status` come
+# back populated once provisioning settles. Re-fetch via `list` to read them.
 for net in c.network.list():
     print(net.id, net.subnet, net.status)
 ```
@@ -223,13 +289,18 @@ for net in c.network.list():
 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
+t = c.token.create(expires_in=3600)   # 0 = server default
+t.token         # str — "eyJ..."  save this; list() will not return it again
+t.expires_at    # int — unix seconds
 
+# list() returns TokenInfo (no raw token; listing-safe metadata).
+# The `jti` field here is what revoke() takes — there's no jti on
+# the freshly-created Token, so revoke goes through list().
 for info in c.token.list():
-    print(info.jti, info.created_at, info.expires_at)
-c.token.revoke(info.jti)
+    info.jti          # str — used by revoke()
+    info.created_at   # int — unix seconds
+    info.expires_at   # int — unix seconds
+    c.token.revoke(info.jti)
 
 # Use the token to authenticate a new client
 c2 = Compute(token=t.token)
@@ -248,6 +319,13 @@ cfg.default_image       # "ubuntu:latest"
 cfg.zone                # "boxd.sh"
 ```
 
+The package also exposes its installed version:
+
+```python
+import boxd
+print("on", boxd.__version__)
+```
+
 ## Errors
 
 ```python
@@ -278,17 +356,39 @@ except NotFoundError:
 | `ConnectionError` | `UNAVAILABLE` |
 | `InternalError` | `INTERNAL`, `UNKNOWN` |
 
-Each error carries the underlying `grpc_code` for finer-grained handling.
+Each error carries the underlying `grpc_code` (numeric gRPC status — see [grpc.StatusCode](https://grpc.github.io/grpc/core/md_doc_statuscodes.html)) for finer-grained handling:
+
+```python
+import grpc
+
+try:
+    c.box.create(name="my-vm")
+except BoxdError as e:
+    if e.grpc_code == grpc.StatusCode.RESOURCE_EXHAUSTED.value[0]:
+        ...   # hit per-user quota
+    raise
+```
+
+## Update notifications
+
+Every gRPC response carries an `x-boxd-py-sdk-latest` header set by the boxd proxy. The SDK's interceptor compares it to the installed version and prints a one-time `sys.stderr` line if a newer release is available:
+
+```
+A new version of boxd is available (v0.1.2, you have v0.1.1). Update with:
+  pip install --upgrade boxd
+```
+
+The notice fires at most once per process, never causes a request to fail, and is silent if the proxy isn't advertising a newer version. Compares as PEP 440-ish (numeric prefix, then per-component compare on `.devN` suffixes).
 
 ## Sync vs Async
 
-The default import is the **sync API**, which wraps the async implementation using a dedicated event loop:
+The default `boxd.Compute` is the **sync API** — fully blocking, safe for scripts, REPLs, notebooks, Django views, anywhere you don't already have an event loop. It wraps the async implementation behind a dedicated background loop, so you don't pay for `asyncio` setup yourself.
 
 ```python
-from boxd import Compute             # sync — recommended for scripts and notebooks
+from boxd import Compute             # sync — recommended default
 ```
 
-For async code, import from `boxd.aio`:
+`boxd.aio.Compute` is the **async API** — use it from inside an existing event loop (FastAPI, asyncio scripts, Quart, anyio):
 
 ```python
 from boxd.aio import Compute
@@ -298,7 +398,7 @@ async with Compute(api_key="bxk_...") as c:
     result = await box.exec("echo", "hello")
 ```
 
-The two APIs are surface-equivalent — only the call style (sync vs `await`) differs.
+The two are surface-equivalent: same method names, same arguments, same return types. The only differences are `with` vs `async with` and the `await` keyword on every call. **Pick `boxd` unless you already have an event loop.**
 
 ## Development