quivvo 0.1.0__tar.gz

quivvo-0.1.0/.gitignore

@@ -0,0 +1,4 @@
+__pycache__/
+*.egg-info/
+build/
+dist/

quivvo-0.1.0/LICENSE

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

quivvo-0.1.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.5
+Name: quivvo
+Version: 0.1.0
+Summary: Python SDK for Quivvo: Linux machines for AI agents.
+Project-URL: Homepage, https://tryquivvo.com
+Project-URL: Documentation, https://tryquivvo.com/docs/sdks
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,cloud-machines,firecracker,sandbox,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# quivvo
+
+The Python SDK for [Quivvo](https://tryquivvo.com): Linux machines for AI agents, each a Firecracker VM with root, Docker and a persistent disk at `/data`. Python 3.9 or later, no dependencies.
+
+```bash
+pip install quivvo            # or, from this repo: pip install ./sdk/python
+```
+
+```python
+from quivvo import Quivvo
+
+q = Quivvo()                          # reads QUIVVO_API_KEY
+m = q.machines.create(name="dev")
+r = m.exec("uname -a")
+print(r["exit_code"], r["stdout"])
+m.delete()
+```
+
+## Auth
+
+Pass a `qvk_` key as `Quivvo(api_key=...)` or set `QUIVVO_API_KEY`. Get one with `quivvo login --agent` or from the dashboard. It's sent as `Authorization: Bearer`. `base_url` falls back to `QUIVVO_API_URL`, then `https://tryquivvo.com`. `q.whoami()` shows the key's scopes and limits.
+
+```python
+Quivvo(api_key=None, base_url=None, max_retries=4, timeout=60.0)
+```
+
+## What comes back
+
+The API's JSON, as plain dicts. Machines are `Machine`, a dict with methods (`m["state"]`, `m.exec(...)`, `m.stop()`). Calls that list return the list. `quivvo.types` has a TypedDict for each object, for your type checker. A machine is given by its id, its name, or the `Machine` itself.
+
+## Errors
+
+```python
+from quivvo import QuivvoError, QuivvoNetworkError
+
+try:
+    q.machines.start("dev")
+except QuivvoError as e:          # the API answered with an error
+    print(e.status, e.code, e.message, e.request_id)
+    if e.owner_action:            # only the workspace's owner can fix this
+        print(e.owner_action["message"], e.owner_action["url"])
+except QuivvoNetworkError as e:   # nothing answered
+    print(e.message, e.maybe_acted)
+```
+
+`QuivvoError` carries `status`, `code`, `message`, `retryable`, `retry_after_seconds`, `docs_url`, `request_id` and `owner_action`. Branch on `code`; [errors](https://tryquivvo.com/docs/errors) lists them. A command that exits non-zero is a result, not an error.
+
+Retryable errors are retried up to `max_retries` times, after `retry_after_seconds` (or 0.5 s doubling to 8 s), never waiting more than 60 s. Reads, deletes, and lifecycle POSTs are retried, and lifecycle POSTs (create, start, stop, suspend, resume, restart, snapshot, fork, restore) send one `Idempotency-Key` for every attempt, so a retry can't act twice. Pass `idempotency_key=` to choose it. Exec and other POSTs are only repeated when the server says nothing ran: `rate_limited`, or `machine_not_running` while it boots.
+
+## Streaming
+
+```python
+with q.machines.exec_stream("dev", "make test") as events:
+    for ev in events:
+        if ev["event"] in ("stdout", "stderr"):
+            print(ev["data"], end="")
+        elif ev["event"] == "exit":
+            print("exit", ev["exit_code"])
+```
+
+There's no output cap. A chunk that isn't valid UTF-8 also has `data_base64`. Leaving the loop hangs up, which stops the command. A stream cut before `exit` raises `StreamLostError`.
+
+For work longer than 280 seconds, start a job and follow it:
+
+```python
+import sys
+
+job = q.jobs.start("dev", "make build")["job"]
+for chunk in q.jobs.follow("dev", job["id"]):
+    sys.stdout.buffer.write(chunk)
+print(q.jobs.wait("dev", job["id"])["exit_code"])
+```
+
+## Webhooks
+
+```python
+from quivvo import verify_webhook
+
+ok = verify_webhook(secret, raw_body, headers["Quivvo-Signature"])  # rejects a t over 5 minutes old
+```
+
+## Methods
+
+| Method | API |
+| --- | --- |
+| `q.whoami()` | `GET /whoami` |
+| `q.catalog()` | `GET /catalog` |
+| `q.usage()` | `GET /usage` |
+| `q.queue()` | `GET /queue` |
+| `q.feedback(message, machine=, context=)` | `POST /feedback` |
+| `q.machines.list(state=, all=)` | `GET /machines` |
+| `q.machines.create(name, template=, size=, vcpus=, memory_mib=, disk_gib=, region=, snapshot=, setup=, env=, auto_suspend_minutes=, delete_after_minutes=, wait=)` | `POST /machines` |
+| `q.machines.get(m)` | `GET /machines/:id` |
+| `q.machines.update(m, name=, auto_suspend_minutes=, vcpus=, memory_mib=, disk_gib=, delete_after_minutes=)` | `PATCH /machines/:id` |
+| `q.machines.delete(m, confirm=)` | `DELETE /machines/:id` |
+| `q.machines.start/resume/restart(m, wait=True)`, `stop(m)`, `suspend(m)` | `POST /machines/:id/<action>` |
+| `q.machines.exec(m, cmd, argv=, cwd=, env=, timeout_ms=, stdin=, tail_bytes=)` | `POST /machines/:id/exec` |
+| `q.machines.exec_stream(m, cmd, ...)` | `POST /machines/:id/exec`, `Accept: text/event-stream` |
+| `q.machines.status(m)`, `ps(m)` | `GET /machines/:id/status`, `/ps` |
+| `q.machines.logs(m, lines=, format=)` | `GET /machines/:id/logs` |
+| `q.machines.history(m, limit=)`, `exec_output(m, exec_id)` | `GET /machines/:id/history`, `/history/:exec/output` |
+| `q.machines.connect(m)` | `POST /machines/:id/connect` |
+| `q.machines.fork(m, count=, name=)` | `POST /machines/:id/fork` |
+| `q.machines.restore(m, snapshot)` | `POST /machines/:id/restore` |
+| `q.jobs.start(m, cmd, argv=, cwd=, env=, timeout_ms=)` | `POST /machines/:id/exec` with `background` |
+| `q.jobs.list(m)`, `get(m, job, wait=)`, `wait(m, job, timeout=)` | `GET /machines/:id/jobs`, `/jobs/:job` |
+| `q.jobs.logs(m, job, offset=, tail_bytes=)`, `follow(m, job, offset=)` | `GET /machines/:id/jobs/:job/logs` |
+| `q.jobs.kill(m, job, signal=)` | `POST /machines/:id/jobs/:job/kill` |
+| `q.files.read(m, path)`, `list(m, path)` | `GET /machines/:id/files` |
+| `q.files.write(m, path, data, mode=, append=)` | `PUT /machines/:id/files` |
+| `q.files.delete(m, path, recursive=)` | `DELETE /machines/:id/files` |
+| `q.ports.list(m)`, `publish(m, port, public=)`, `unpublish(m, port)` | `/machines/:id/ports` |
+| `q.snapshots.create(m, name)` | `POST /machines/:id/snapshots` |
+| `q.snapshots.list()`, `get(snapshot)`, `delete(snapshot, confirm=)` | `GET /snapshots`, `DELETE /snapshots/:id` |
+| `q.keys.list()`, `create(name, scopes=)`, `revoke(key)` | `/keys` |
+| `q.webhooks.list()`, `create(url, events=)`, `delete(webhook)` | `/webhooks` |
+
+A `Machine` has `refresh()`, `start()`, `stop()`, `suspend()`, `resume()`, `restart()`, `delete()`, `exec()` and `exec_stream()`. Start a machine from a snapshot with `q.machines.create(snapshot="base")`. `q.snapshots.get()` reads the list, as the API has no route for one snapshot.
+
+## Tests
+
+```bash
+cd sdk/python && PYTHONPATH=src python3 -m unittest discover -s tests
+```
+
+[REST API reference](https://tryquivvo.com/docs/api) · [OpenAPI](https://tryquivvo.com/api/v1/openapi.json)
+
+## License
+
+MIT. See [LICENSE](LICENSE).

quivvo-0.1.0/README.md

@@ -0,0 +1,130 @@
+# quivvo
+
+The Python SDK for [Quivvo](https://tryquivvo.com): Linux machines for AI agents, each a Firecracker VM with root, Docker and a persistent disk at `/data`. Python 3.9 or later, no dependencies.
+
+```bash
+pip install quivvo            # or, from this repo: pip install ./sdk/python
+```
+
+```python
+from quivvo import Quivvo
+
+q = Quivvo()                          # reads QUIVVO_API_KEY
+m = q.machines.create(name="dev")
+r = m.exec("uname -a")
+print(r["exit_code"], r["stdout"])
+m.delete()
+```
+
+## Auth
+
+Pass a `qvk_` key as `Quivvo(api_key=...)` or set `QUIVVO_API_KEY`. Get one with `quivvo login --agent` or from the dashboard. It's sent as `Authorization: Bearer`. `base_url` falls back to `QUIVVO_API_URL`, then `https://tryquivvo.com`. `q.whoami()` shows the key's scopes and limits.
+
+```python
+Quivvo(api_key=None, base_url=None, max_retries=4, timeout=60.0)
+```
+
+## What comes back
+
+The API's JSON, as plain dicts. Machines are `Machine`, a dict with methods (`m["state"]`, `m.exec(...)`, `m.stop()`). Calls that list return the list. `quivvo.types` has a TypedDict for each object, for your type checker. A machine is given by its id, its name, or the `Machine` itself.
+
+## Errors
+
+```python
+from quivvo import QuivvoError, QuivvoNetworkError
+
+try:
+    q.machines.start("dev")
+except QuivvoError as e:          # the API answered with an error
+    print(e.status, e.code, e.message, e.request_id)
+    if e.owner_action:            # only the workspace's owner can fix this
+        print(e.owner_action["message"], e.owner_action["url"])
+except QuivvoNetworkError as e:   # nothing answered
+    print(e.message, e.maybe_acted)
+```
+
+`QuivvoError` carries `status`, `code`, `message`, `retryable`, `retry_after_seconds`, `docs_url`, `request_id` and `owner_action`. Branch on `code`; [errors](https://tryquivvo.com/docs/errors) lists them. A command that exits non-zero is a result, not an error.
+
+Retryable errors are retried up to `max_retries` times, after `retry_after_seconds` (or 0.5 s doubling to 8 s), never waiting more than 60 s. Reads, deletes, and lifecycle POSTs are retried, and lifecycle POSTs (create, start, stop, suspend, resume, restart, snapshot, fork, restore) send one `Idempotency-Key` for every attempt, so a retry can't act twice. Pass `idempotency_key=` to choose it. Exec and other POSTs are only repeated when the server says nothing ran: `rate_limited`, or `machine_not_running` while it boots.
+
+## Streaming
+
+```python
+with q.machines.exec_stream("dev", "make test") as events:
+    for ev in events:
+        if ev["event"] in ("stdout", "stderr"):
+            print(ev["data"], end="")
+        elif ev["event"] == "exit":
+            print("exit", ev["exit_code"])
+```
+
+There's no output cap. A chunk that isn't valid UTF-8 also has `data_base64`. Leaving the loop hangs up, which stops the command. A stream cut before `exit` raises `StreamLostError`.
+
+For work longer than 280 seconds, start a job and follow it:
+
+```python
+import sys
+
+job = q.jobs.start("dev", "make build")["job"]
+for chunk in q.jobs.follow("dev", job["id"]):
+    sys.stdout.buffer.write(chunk)
+print(q.jobs.wait("dev", job["id"])["exit_code"])
+```
+
+## Webhooks
+
+```python
+from quivvo import verify_webhook
+
+ok = verify_webhook(secret, raw_body, headers["Quivvo-Signature"])  # rejects a t over 5 minutes old
+```
+
+## Methods
+
+| Method | API |
+| --- | --- |
+| `q.whoami()` | `GET /whoami` |
+| `q.catalog()` | `GET /catalog` |
+| `q.usage()` | `GET /usage` |
+| `q.queue()` | `GET /queue` |
+| `q.feedback(message, machine=, context=)` | `POST /feedback` |
+| `q.machines.list(state=, all=)` | `GET /machines` |
+| `q.machines.create(name, template=, size=, vcpus=, memory_mib=, disk_gib=, region=, snapshot=, setup=, env=, auto_suspend_minutes=, delete_after_minutes=, wait=)` | `POST /machines` |
+| `q.machines.get(m)` | `GET /machines/:id` |
+| `q.machines.update(m, name=, auto_suspend_minutes=, vcpus=, memory_mib=, disk_gib=, delete_after_minutes=)` | `PATCH /machines/:id` |
+| `q.machines.delete(m, confirm=)` | `DELETE /machines/:id` |
+| `q.machines.start/resume/restart(m, wait=True)`, `stop(m)`, `suspend(m)` | `POST /machines/:id/<action>` |
+| `q.machines.exec(m, cmd, argv=, cwd=, env=, timeout_ms=, stdin=, tail_bytes=)` | `POST /machines/:id/exec` |
+| `q.machines.exec_stream(m, cmd, ...)` | `POST /machines/:id/exec`, `Accept: text/event-stream` |
+| `q.machines.status(m)`, `ps(m)` | `GET /machines/:id/status`, `/ps` |
+| `q.machines.logs(m, lines=, format=)` | `GET /machines/:id/logs` |
+| `q.machines.history(m, limit=)`, `exec_output(m, exec_id)` | `GET /machines/:id/history`, `/history/:exec/output` |
+| `q.machines.connect(m)` | `POST /machines/:id/connect` |
+| `q.machines.fork(m, count=, name=)` | `POST /machines/:id/fork` |
+| `q.machines.restore(m, snapshot)` | `POST /machines/:id/restore` |
+| `q.jobs.start(m, cmd, argv=, cwd=, env=, timeout_ms=)` | `POST /machines/:id/exec` with `background` |
+| `q.jobs.list(m)`, `get(m, job, wait=)`, `wait(m, job, timeout=)` | `GET /machines/:id/jobs`, `/jobs/:job` |
+| `q.jobs.logs(m, job, offset=, tail_bytes=)`, `follow(m, job, offset=)` | `GET /machines/:id/jobs/:job/logs` |
+| `q.jobs.kill(m, job, signal=)` | `POST /machines/:id/jobs/:job/kill` |
+| `q.files.read(m, path)`, `list(m, path)` | `GET /machines/:id/files` |
+| `q.files.write(m, path, data, mode=, append=)` | `PUT /machines/:id/files` |
+| `q.files.delete(m, path, recursive=)` | `DELETE /machines/:id/files` |
+| `q.ports.list(m)`, `publish(m, port, public=)`, `unpublish(m, port)` | `/machines/:id/ports` |
+| `q.snapshots.create(m, name)` | `POST /machines/:id/snapshots` |
+| `q.snapshots.list()`, `get(snapshot)`, `delete(snapshot, confirm=)` | `GET /snapshots`, `DELETE /snapshots/:id` |
+| `q.keys.list()`, `create(name, scopes=)`, `revoke(key)` | `/keys` |
+| `q.webhooks.list()`, `create(url, events=)`, `delete(webhook)` | `/webhooks` |
+
+A `Machine` has `refresh()`, `start()`, `stop()`, `suspend()`, `resume()`, `restart()`, `delete()`, `exec()` and `exec_stream()`. Start a machine from a snapshot with `q.machines.create(snapshot="base")`. `q.snapshots.get()` reads the list, as the API has no route for one snapshot.
+
+## Tests
+
+```bash
+cd sdk/python && PYTHONPATH=src python3 -m unittest discover -s tests
+```
+
+[REST API reference](https://tryquivvo.com/docs/api) · [OpenAPI](https://tryquivvo.com/api/v1/openapi.json)
+
+## License
+
+MIT. See [LICENSE](LICENSE).

quivvo-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "quivvo"
+dynamic = ["version"]
+description = "Python SDK for Quivvo: Linux machines for AI agents."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = []
+keywords = ["ai-agents", "sandbox", "cloud-machines", "firecracker", "sdk"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://tryquivvo.com"
+Documentation = "https://tryquivvo.com/docs/sdks"
+
+[tool.hatch.version]
+path = "src/quivvo/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/quivvo"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/quivvo", "tests", "README.md", "LICENSE", "pyproject.toml"]
+
+[tool.mypy]
+strict = true
+# The API's answers are JSON, typed by the TypedDicts in quivvo.types where they're returned.
+warn_return_any = false

quivvo-0.1.0/src/quivvo/__init__.py

@@ -0,0 +1,26 @@
+"""Python SDK for Quivvo: Linux machines for AI agents.
+
+    from quivvo import Quivvo
+
+    q = Quivvo()  # QUIVVO_API_KEY
+    m = q.machines.create(name="dev")
+    print(m.exec("uname -a")["stdout"])
+"""
+
+from ._client import Quivvo
+from ._errors import QuivvoError, QuivvoNetworkError, StreamLostError
+from ._resources import ExecStream, JobLogs, Machine
+from ._version import __version__
+from ._webhooks import verify_webhook
+
+__all__ = [
+    "ExecStream",
+    "JobLogs",
+    "Machine",
+    "Quivvo",
+    "QuivvoError",
+    "QuivvoNetworkError",
+    "StreamLostError",
+    "__version__",
+    "verify_webhook",
+]

quivvo-0.1.0/src/quivvo/_client.py

@@ -0,0 +1,78 @@
+"""The client."""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Optional
+
+from ._resources import Files, Jobs, Keys, Machines, Ports, Snapshots, Webhooks, _compact, _ref
+from ._transport import DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT, Transport
+from .types import Catalog, Feedback, QueueState, Usage, Whoami
+
+
+class Quivvo:
+    """A client for the Quivvo REST API (``{base_url}/api/v1``).
+
+    - ``api_key``: a ``qvk_`` key, sent as ``Authorization: Bearer``. Defaults to ``QUIVVO_API_KEY``.
+    - ``base_url``: defaults to ``QUIVVO_API_URL``, then ``https://tryquivvo.com``.
+    - ``max_retries``: extra attempts after the first, for retryable errors and dropped connections, where the docs
+      allow it. Default 4.
+    - ``timeout``: seconds a request may wait for the server, 60 by default. Calls the server holds open while it works
+      (exec, create, lifecycle, snapshots, job waits) get as long as they need on top.
+    """
+
+    machines: Machines
+    jobs: Jobs
+    files: Files
+    ports: Ports
+    snapshots: Snapshots
+    keys: Keys
+    webhooks: Webhooks
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> None:
+        key = api_key if api_key is not None else os.environ.get("QUIVVO_API_KEY")
+        url = base_url or os.environ.get("QUIVVO_API_URL") or DEFAULT_BASE_URL
+        self._transport = Transport(key or None, url, max_retries, timeout)
+        self.machines = Machines(self)
+        self.jobs = Jobs(self)
+        self.files = Files(self)
+        self.ports = Ports(self)
+        self.snapshots = Snapshots(self)
+        self.keys = Keys(self)
+        self.webhooks = Webhooks(self)
+
+    @property
+    def base_url(self) -> str:
+        return self._transport.base_url
+
+    def __repr__(self) -> str:
+        return f"Quivvo(base_url={self.base_url!r})"
+
+    def whoami(self) -> Whoami:
+        """What this key may do: ``kind``, ``key``, ``email``, ``scopes``, ``workspace``, ``limits``, ``exec``,
+        ``machines`` and ``queue``. Needs no scope."""
+        return self._transport.json("GET", "/whoami")
+
+    def catalog(self) -> Catalog:
+        """Templates, sizes, regions, plans, prices and exec limits. Needs no key."""
+        return self._transport.json("GET", "/catalog")
+
+    def usage(self) -> Usage:
+        """This month's cost by machine and day, and the credit balance. US dollars."""
+        return self._transport.json("GET", "/usage")
+
+    def queue(self) -> QueueState:
+        """This workspace's place in the queue and its invite link: ``{"waiting": False}`` once it's let in."""
+        return self._transport.json("GET", "/queue")
+
+    def feedback(self, message: str, *, machine: Any = None, context: Any = None) -> Feedback:
+        """Reports a problem to Quivvo: up to 4000 bytes, optionally the machine and any JSON ``context`` (a
+        ``request_id`` helps). Leave out secrets."""
+        body = _compact(message=message, machine=_ref(machine) if machine is not None else None, context=context)
+        return self._transport.json("POST", "/feedback", json=body)

quivvo-0.1.0/src/quivvo/_errors.py

@@ -0,0 +1,88 @@
+"""The two ways a call fails: the API answered with an error, or nothing answered at all."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+
+class QuivvoError(Exception):
+    """The API answered with an error object.
+
+    ``{"error": {"code", "message", "retryable", "retry_after_seconds", "docs_url", "request_id", "owner_action"}}``
+
+    Branch on ``code``: the message can change. When ``retryable`` is true, the same request can be sent again after
+    ``retry_after_seconds`` (the client has already done that, up to ``max_retries``). ``owner_action``, when present, is
+    ``{"url", "message"}``: something only the workspace's owner can do, signed in on the dashboard. Pass it on.
+    """
+
+    status: int
+    code: str
+    message: str
+    retryable: bool
+    retry_after_seconds: Optional[float]
+    docs_url: Optional[str]
+    request_id: Optional[str]
+    owner_action: Optional[Dict[str, Any]]
+
+    def __init__(
+        self,
+        status: int,
+        code: str,
+        message: str,
+        *,
+        retryable: bool = False,
+        retry_after_seconds: Optional[float] = None,
+        docs_url: Optional[str] = None,
+        request_id: Optional[str] = None,
+        owner_action: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.message = message
+        self.retryable = retryable
+        self.retry_after_seconds = retry_after_seconds
+        self.docs_url = docs_url
+        self.request_id = request_id
+        self.owner_action = owner_action
+
+    def __str__(self) -> str:
+        out = f"{self.code}: {self.message}"
+        if self.request_id:
+            out += f" (request {self.request_id})"
+        return out
+
+    def __repr__(self) -> str:
+        return f"QuivvoError(status={self.status}, code={self.code!r}, message={self.message!r}, request_id={self.request_id!r})"
+
+
+class QuivvoNetworkError(Exception):
+    """The API couldn't be reached, or stopped answering: DNS, connection refused or reset, a timeout.
+
+    ``maybe_acted`` is true when the request may have reached the server and done something first, so sending it again
+    isn't automatically safe (an exec, say). Reads, deletes and lifecycle calls carrying an Idempotency-Key are retried
+    by the client before this is raised.
+    """
+
+    message: str
+    maybe_acted: bool
+
+    def __init__(self, message: str, *, maybe_acted: bool = False) -> None:
+        super().__init__(message)
+        self.message = message
+        self.maybe_acted = maybe_acted
+
+    @property
+    def retryable(self) -> bool:
+        """True when nothing can have happened, so repeating the call is safe."""
+        return not self.maybe_acted
+
+
+class StreamLostError(QuivvoNetworkError):
+    """A stream from ``exec_stream`` ended before its ``exit`` event, so the command's result is unknown.
+
+    ``machines.history()`` shows what's known about it.
+    """
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message, maybe_acted=True)