runloop_api_client 1.10.2__tar.gz → 1.11.0__tar.gz

runloop_api_client-1.11.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "1.11.0"
+}

{runloop_api_client-1.10.2 → runloop_api_client-1.11.0}/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## 1.11.0 (2026-03-10)
+
+Full Changelog: [v1.10.3...v1.11.0](https://github.com/runloopai/api-client-python/compare/v1.10.3...v1.11.0)
+
+### Features
+
+* add snapshots example ([#753](https://github.com/runloopai/api-client-python/issues/753)) ([f13916a](https://github.com/runloopai/api-client-python/commit/f13916a570fe708aef56c6fbfd5c06b9e0dc158e))
+* **documentation:** added llms.txt, examples and referenced these artifacts via README ([#748](https://github.com/runloopai/api-client-python/issues/748)) ([bceb953](https://github.com/runloopai/api-client-python/commit/bceb953c8486bec6bbe5bca1276ed54d625eda5d))
+
+
+### Bug Fixes
+
+* add logs to devboxes, smoke tests & examples ([#755](https://github.com/runloopai/api-client-python/issues/755)) ([da5faa4](https://github.com/runloopai/api-client-python/commit/da5faa4e69348dd6f034a538046ab9ff2ff4831b))
+
+
+### Chores
+
+* **ci:** skip uploading artifacts on stainless-internal branches ([6874252](https://github.com/runloopai/api-client-python/commit/6874252fe355ac8a44be6bc57cd6bb15a3f035be))
+* **documentation:** correct exec advice ([#752](https://github.com/runloopai/api-client-python/issues/752)) ([fa16c1d](https://github.com/runloopai/api-client-python/commit/fa16c1d602ec301200e82a48fe23c2218ae82a08))
+* **test:** do not count install time for mock server timeout ([f6fde05](https://github.com/runloopai/api-client-python/commit/f6fde050a5f4b985c01003cd7593c1619ede028f))
+* update placeholder string ([5dfcd93](https://github.com/runloopai/api-client-python/commit/5dfcd93bb05cda783901377ee7fc03a6acffe0ae))
+
+## 1.10.3 (2026-02-27)
+
+Full Changelog: [v1.10.2...v1.10.3](https://github.com/runloopai/api-client-python/compare/v1.10.2...v1.10.3)
+
+### Bug Fixes
+
+* switching to MCP definition to specify a secret name per MCP server ([#7715](https://github.com/runloopai/api-client-python/issues/7715)) ([01f4b3d](https://github.com/runloopai/api-client-python/commit/01f4b3dc66f20126adf6737554e42ce1a1b19fe0))
+
+
+### Chores
+
+* **ci:** bump uv version ([b0fad50](https://github.com/runloopai/api-client-python/commit/b0fad503bde3ad7c472e6aac71073a01e92b7a6a))
+
 ## 1.10.2 (2026-02-26)
 
 Full Changelog: [v1.10.1...v1.10.2](https://github.com/runloopai/api-client-python/compare/v1.10.1...v1.10.2)

runloop_api_client-1.11.0/EXAMPLES.md

@@ -0,0 +1,137 @@
+# Examples
+
+> This file is auto-generated from metadata in `examples/*.py`.
+> Do not edit this file manually. Run `uv run python scripts/generate_examples_md.py` instead.
+
+Runnable examples live in [`examples/`](./examples).
+
+## Table of Contents
+
+- [Blueprint with Build Context](#blueprint-with-build-context)
+- [Devbox From Blueprint (Run Command, Shutdown)](#devbox-from-blueprint-lifecycle)
+- [Devbox Snapshot and Resume](#devbox-snapshot-resume)
+- [MCP Hub + Claude Code + GitHub](#mcp-github-tools)
+
+<a id="blueprint-with-build-context"></a>
+## Blueprint with Build Context
+
+**Use case:** Create a blueprint using the object store to provide docker build context files, then verify files are copied into the image. Uses the async SDK.
+
+**Tags:** `blueprint`, `object-store`, `build-context`, `devbox`, `cleanup`, `async`
+
+### Workflow
+- Create a temporary directory with sample application files
+- Upload the directory to object storage as build context
+- Create a blueprint with a Dockerfile that copies the context files
+- Create a devbox from the blueprint
+- Verify the files were copied into the image
+- Shutdown devbox and delete blueprint and storage object
+
+### Prerequisites
+- `RUNLOOP_API_KEY`
+
+### Run
+```sh
+uv run python -m examples.blueprint_with_build_context
+```
+
+### Test
+```sh
+uv run pytest -m smoketest tests/smoketests/examples/
+```
+
+**Source:** [`examples/blueprint_with_build_context.py`](./examples/blueprint_with_build_context.py)
+
+<a id="devbox-from-blueprint-lifecycle"></a>
+## Devbox From Blueprint (Run Command, Shutdown)
+
+**Use case:** Create a devbox from a blueprint, run a command, fetch logs, validate output, and cleanly tear everything down.
+
+**Tags:** `devbox`, `blueprint`, `commands`, `logs`, `cleanup`
+
+### Workflow
+- Create a blueprint
+- Fetch blueprint build logs
+- Create a devbox from the blueprint
+- Execute a command in the devbox
+- Fetch devbox logs
+- Validate exit code, stdout, and logs
+- Shutdown devbox and delete blueprint
+
+### Prerequisites
+- `RUNLOOP_API_KEY`
+
+### Run
+```sh
+uv run python -m examples.devbox_from_blueprint_lifecycle
+```
+
+### Test
+```sh
+uv run pytest -m smoketest tests/smoketests/examples/
+```
+
+**Source:** [`examples/devbox_from_blueprint_lifecycle.py`](./examples/devbox_from_blueprint_lifecycle.py)
+
+<a id="devbox-snapshot-resume"></a>
+## Devbox Snapshot and Resume
+
+**Use case:** Create a devbox, snapshot its disk, resume from the snapshot, and demonstrate that changes in the original devbox do not affect the clone. Uses the async SDK.
+
+**Tags:** `devbox`, `snapshot`, `resume`, `cleanup`, `async`
+
+### Workflow
+- Create a devbox
+- Write a file to the devbox
+- Create a disk snapshot
+- Create a new devbox from the snapshot
+- Modify the file on the original devbox
+- Verify the clone has the original content
+- Shutdown both devboxes and delete the snapshot
+
+### Prerequisites
+- `RUNLOOP_API_KEY`
+
+### Run
+```sh
+uv run python -m examples.devbox_snapshot_resume
+```
+
+### Test
+```sh
+uv run pytest -m smoketest tests/smoketests/examples/
+```
+
+**Source:** [`examples/devbox_snapshot_resume.py`](./examples/devbox_snapshot_resume.py)
+
+<a id="mcp-github-tools"></a>
+## MCP Hub + Claude Code + GitHub
+
+**Use case:** Connect Claude Code running in a devbox to GitHub tools through MCP Hub without exposing raw GitHub credentials to the devbox.
+
+**Tags:** `mcp`, `devbox`, `github`, `commands`, `cleanup`
+
+### Workflow
+- Create an MCP config for GitHub
+- Store GitHub token as a Runloop secret
+- Launch a devbox with MCP Hub wiring
+- Install Claude Code and register MCP endpoint
+- Run a Claude prompt through MCP tools
+- Shutdown devbox and clean up cloud resources
+
+### Prerequisites
+- `RUNLOOP_API_KEY`
+- `GITHUB_TOKEN (GitHub PAT with repo scope)`
+- `ANTHROPIC_API_KEY`
+
+### Run
+```sh
+GITHUB_TOKEN=ghp_xxx ANTHROPIC_API_KEY=sk-ant-xxx uv run python -m examples.mcp_github_tools
+```
+
+### Test
+```sh
+uv run pytest -m smoketest tests/smoketests/examples/
+```
+
+**Source:** [`examples/mcp_github_tools.py`](./examples/mcp_github_tools.py)

{runloop_api_client-1.10.2 → runloop_api_client-1.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: runloop_api_client
-Version: 1.10.2
+Version: 1.11.0
 Summary: The official Python library for the runloop API
 Project-URL: Homepage, https://github.com/runloopai/api-client-python
 Project-URL: Repository, https://github.com/runloopai/api-client-python
@@ -125,6 +125,23 @@ asyncio.run(main())
 
 Functionality between the synchronous and asynchronous clients is otherwise identical.
 
+## Examples
+
+Workflow-oriented runnable examples are documented in [`EXAMPLES.md`](./EXAMPLES.md).
+
+`EXAMPLES.md` is generated from metadata in `examples/*.py` and should not be edited manually.
+Regenerate it with:
+
+```sh
+uv run python scripts/generate_examples_md.py
+```
+
+## Agent Guidance
+
+Detailed agent-specific instructions for developing using this package live in [`llms.txt`](./llms.txt). Consolidated recipes for frequent tasks are in [`EXAMPLES.md`](./EXAMPLES.md).
+
+After completing any modifications to this project, ensure `llms.txt` and `README.md` are kept in sync.
+
 ### With aiohttp
 
 By default, the async client uses `httpx` for HTTP requests. However, for improved concurrency performance you may also use `aiohttp` as the HTTP backend.
@@ -517,6 +534,17 @@ print(runloop_api_client.__version__)
 
 Python 3.9 or higher.
 
+## Development
+
+After cloning the repository, run the bootstrap script and install git hooks:
+
+```sh
+./scripts/bootstrap
+./scripts/install-hooks
+```
+
+This installs pre-push hooks that run linting and verify generated files are up to date.
+
 ## Contributing
 
 See [the contributing documentation](./CONTRIBUTING.md).

{runloop_api_client-1.10.2 → runloop_api_client-1.11.0}/README-SDK.md

@@ -160,13 +160,13 @@ print(f"Devbox {info.name} is {info.status}")
 Execute commands synchronously or asynchronously:
 
 ```python
-# Synchronous command execution (waits for completion)
+# exec blocks until completion - use for commands that return immediately
 result = devbox.cmd.exec("ls -la")
 print("Output:", result.stdout())
 print("Exit code:", result.exit_code)
 print("Success:", result.success)
 
-# Asynchronous command execution (returns immediately)
+# exec_async returns immediately - use for long-running processes
 execution = devbox.cmd.exec_async("npm run dev")
 
 # Check execution status
@@ -393,11 +393,30 @@ async with await runloop.devbox.create(name="temp-devbox") as devbox:
 # devbox is automatically shutdown when exiting the context
 ```
 
+#### Devbox Logs
+
+Retrieve logs from a devbox, optionally filtered by execution ID or shell name:
+
+```python
+# Get all devbox logs
+logs = devbox.logs()
+for log in logs.logs:
+    print(f"[{log.level}] {log.message}")
+
+# Filter logs by execution ID
+result = devbox.cmd.exec('echo "hello"')
+exec_logs = devbox.logs(execution_id=result.execution_id)
+
+# Filter logs by shell name
+shell_logs = devbox.logs(shell_name="my-shell")
+```
+
 **Key methods:**
 
 - `devbox.get_info()` - Get devbox details and status
 - `devbox.cmd.exec()` - Execute commands synchronously
 - `devbox.cmd.exec_async()` - Execute commands asynchronously
+- `devbox.logs()` - Retrieve devbox logs (optionally filter by execution_id or shell_name)
 - `devbox.file.read()` - Read file contents
 - `devbox.file.write()` - Write file contents
 - `devbox.file.upload()` - Upload files

{runloop_api_client-1.10.2 → runloop_api_client-1.11.0}/README.md

@@ -88,6 +88,23 @@ asyncio.run(main())
 
 Functionality between the synchronous and asynchronous clients is otherwise identical.
 
+## Examples
+
+Workflow-oriented runnable examples are documented in [`EXAMPLES.md`](./EXAMPLES.md).
+
+`EXAMPLES.md` is generated from metadata in `examples/*.py` and should not be edited manually.
+Regenerate it with:
+
+```sh
+uv run python scripts/generate_examples_md.py
+```
+
+## Agent Guidance
+
+Detailed agent-specific instructions for developing using this package live in [`llms.txt`](./llms.txt). Consolidated recipes for frequent tasks are in [`EXAMPLES.md`](./EXAMPLES.md).
+
+After completing any modifications to this project, ensure `llms.txt` and `README.md` are kept in sync.
+
 ### With aiohttp
 
 By default, the async client uses `httpx` for HTTP requests. However, for improved concurrency performance you may also use `aiohttp` as the HTTP backend.
@@ -480,6 +497,17 @@ print(runloop_api_client.__version__)
 
 Python 3.9 or higher.
 
+## Development
+
+After cloning the repository, run the bootstrap script and install git hooks:
+
+```sh
+./scripts/bootstrap
+./scripts/install-hooks
+```
+
+This installs pre-push hooks that run linting and verify generated files are up to date.
+
 ## Contributing
 
 See [the contributing documentation](./CONTRIBUTING.md).

runloop_api_client-1.11.0/examples/__init__.py

@@ -0,0 +1 @@
+# Examples package for Runloop Python SDK

runloop_api_client-1.11.0/examples/_harness.py

@@ -0,0 +1,172 @@
+from __future__ import annotations
+
+import sys
+import json
+import time
+import asyncio
+from typing import Any, TypeVar, Callable, Awaitable
+from dataclasses import asdict
+
+from .example_types import (
+    ExampleCheck,
+    RecipeOutput,
+    ExampleResult,
+    RecipeContext,
+    ExampleCleanupStatus,
+    ExampleCleanupFailure,
+)
+
+T = TypeVar("T")
+
+
+def unique_name(prefix: str) -> str:
+    """Generate a unique name with timestamp and random suffix."""
+    return f"{prefix}-{int(time.time())}-{hex(int(time.time() * 1000) % 0xFFFFFF)[2:]}"
+
+
+class _CleanupTracker:
+    """Tracks cleanup actions and executes them in LIFO order."""
+
+    def __init__(self, status: ExampleCleanupStatus) -> None:
+        self._status = status
+        self._actions: list[tuple[str, Callable[[], Any]]] = []
+
+    def add(self, resource: str, action: Callable[[], Any]) -> None:
+        """Register a cleanup action for a resource."""
+        self._actions.append((resource, action))
+
+    async def run(self) -> None:
+        """Execute all cleanup actions in reverse order."""
+        while self._actions:
+            resource, action = self._actions.pop()
+            self._status.attempted.append(resource)
+            try:
+                result = action()
+                if asyncio.iscoroutine(result):
+                    await result
+                self._status.succeeded.append(resource)
+            except Exception as e:
+                self._status.failed.append(ExampleCleanupFailure(resource, str(e)))
+
+        if self._status.attempted:
+            if not self._status.failed:
+                print("Cleanup completed.")  # noqa: T201
+            else:
+                print("Cleanup finished with errors.")  # noqa: T201
+
+
+def _should_fail_process(result: ExampleResult) -> bool:
+    """Determine if the process should exit with failure."""
+    has_failed_checks = any(not check.passed for check in result.checks)
+    return result.skipped or has_failed_checks or len(result.cleanup_status.failed) > 0
+
+
+def _run_recipe_impl(
+    recipe_call: Callable[[], RecipeOutput | Awaitable[RecipeOutput]],
+    cleanup: _CleanupTracker,
+    cleanup_status: ExampleCleanupStatus,
+) -> ExampleResult:
+    """Shared implementation for running recipes with cleanup."""
+
+    async def _run_async() -> RecipeOutput:
+        try:
+            result = recipe_call()
+            if asyncio.iscoroutine(result):
+                output: RecipeOutput = await result
+                return output
+            return result  # type: ignore[return-value]
+        finally:
+            await cleanup.run()
+
+    loop = asyncio.new_event_loop()
+    try:
+        output = loop.run_until_complete(_run_async())
+        return ExampleResult(
+            resources_created=output.resources_created,
+            checks=output.checks,
+            cleanup_status=cleanup_status,
+        )
+    finally:
+        loop.close()
+
+
+def wrap_recipe(
+    recipe: Callable[[RecipeContext], RecipeOutput] | Callable[[RecipeContext], Awaitable[RecipeOutput]],
+    validate_env: Callable[[], tuple[bool, list[ExampleCheck]]] | None = None,
+) -> Callable[[], ExampleResult]:
+    """Wrap a recipe function with cleanup tracking and result handling.
+
+    Args:
+        recipe: The recipe function to wrap. Can be sync or async.
+        validate_env: Optional function to validate environment before running.
+                      Returns (skip, checks) tuple.
+
+    Returns:
+        A callable that runs the recipe and returns ExampleResult.
+    """
+
+    def run() -> ExampleResult:
+        cleanup_status = ExampleCleanupStatus()
+        cleanup = _CleanupTracker(cleanup_status)
+
+        if validate_env is not None:
+            skip, checks = validate_env()
+            if skip:
+                return ExampleResult(
+                    resources_created=[],
+                    checks=checks,
+                    cleanup_status=cleanup_status,
+                    skipped=True,
+                )
+
+        ctx = RecipeContext(cleanup=cleanup)
+        return _run_recipe_impl(lambda: recipe(ctx), cleanup, cleanup_status)
+
+    return run
+
+
+def wrap_recipe_with_options(
+    recipe: Callable[[RecipeContext, T], RecipeOutput] | Callable[[RecipeContext, T], Awaitable[RecipeOutput]],
+    validate_env: Callable[[T], tuple[bool, list[ExampleCheck]]] | None = None,
+) -> Callable[[T], ExampleResult]:
+    """Wrap a recipe function that takes options with cleanup tracking.
+
+    Args:
+        recipe: The recipe function to wrap. Can be sync or async. Takes options parameter.
+        validate_env: Optional function to validate environment before running.
+                      Takes options and returns (skip, checks) tuple.
+
+    Returns:
+        A callable that runs the recipe with options and returns ExampleResult.
+    """
+
+    def run(options: T) -> ExampleResult:
+        cleanup_status = ExampleCleanupStatus()
+        cleanup = _CleanupTracker(cleanup_status)
+
+        if validate_env is not None:
+            skip, checks = validate_env(options)
+            if skip:
+                return ExampleResult(
+                    resources_created=[],
+                    checks=checks,
+                    cleanup_status=cleanup_status,
+                    skipped=True,
+                )
+
+        ctx = RecipeContext(cleanup=cleanup)
+        return _run_recipe_impl(lambda: recipe(ctx, options), cleanup, cleanup_status)
+
+    return run
+
+
+def run_as_cli(run: Callable[[], ExampleResult]) -> None:
+    """Run an example and exit with appropriate status code."""
+    try:
+        result = run()
+        print(json.dumps(asdict(result), indent=2))  # noqa: T201
+        if _should_fail_process(result):
+            sys.exit(1)
+    except Exception as e:
+        print(f"Error: {e}")  # noqa: T201
+        sys.exit(1)

runloop_api_client-1.11.0/examples/blueprint_with_build_context.py

@@ -0,0 +1,130 @@
+#!/usr/bin/env -S uv run python
+"""
+---
+title: Blueprint with Build Context
+slug: blueprint-with-build-context
+use_case: Create a blueprint using the object store to provide docker build context files, then verify files are copied into the image. Uses the async SDK.
+workflow:
+  - Create a temporary directory with sample application files
+  - Upload the directory to object storage as build context
+  - Create a blueprint with a Dockerfile that copies the context files
+  - Create a devbox from the blueprint
+  - Verify the files were copied into the image
+  - Shutdown devbox and delete blueprint and storage object
+tags:
+  - blueprint
+  - object-store
+  - build-context
+  - devbox
+  - cleanup
+  - async
+prerequisites:
+  - RUNLOOP_API_KEY
+run: uv run python -m examples.blueprint_with_build_context
+test: uv run pytest -m smoketest tests/smoketests/examples/
+---
+"""
+
+from __future__ import annotations
+
+import tempfile
+from pathlib import Path
+from datetime import timedelta
+
+from runloop_api_client import AsyncRunloopSDK
+from runloop_api_client.lib.polling import PollingConfig
+
+from ._harness import run_as_cli, unique_name, wrap_recipe
+from .example_types import ExampleCheck, RecipeOutput, RecipeContext
+
+# building can take time: make sure to set a long blueprint build timeout
+BLUEPRINT_POLL_TIMEOUT_S = 10 * 60
+BLUEPRINT_POLL_MAX_ATTEMPTS = 600
+
+# configure object storage ttl for the build context
+BUILD_CONTEXT_TTL = timedelta(hours=1)
+
+
+async def recipe(ctx: RecipeContext) -> RecipeOutput:
+    """Create a blueprint with build context from object storage, then verify files in a devbox."""
+    cleanup = ctx.cleanup
+
+    sdk = AsyncRunloopSDK()
+
+    # setup: create a temporary directory with sample application files to use as build context
+    with tempfile.TemporaryDirectory() as tmp_dir:
+        tmp_path = Path(tmp_dir)
+        (tmp_path / "app.py").write_text('print("Hello from app")')
+        (tmp_path / "config.txt").write_text("key=value")
+
+        # upload the build context to object storage
+        storage_obj = await sdk.storage_object.upload_from_dir(
+            tmp_path,
+            name=unique_name("example-build-context"),
+            ttl=BUILD_CONTEXT_TTL,
+        )
+        cleanup.add(f"storage_object:{storage_obj.id}", storage_obj.delete)
+
+        # create a blueprint with the build context
+        blueprint = await sdk.blueprint.create(
+            name=unique_name("example-blueprint-context"),
+            dockerfile="FROM ubuntu:22.04\nWORKDIR /app\nCOPY . .",
+            build_context=storage_obj.as_build_context(),
+            polling_config=PollingConfig(
+                timeout_seconds=BLUEPRINT_POLL_TIMEOUT_S,
+                max_attempts=BLUEPRINT_POLL_MAX_ATTEMPTS,
+            ),
+        )
+        cleanup.add(f"blueprint:{blueprint.id}", blueprint.delete)
+
+        devbox = await blueprint.create_devbox(
+            name=unique_name("example-devbox"),
+            launch_parameters={
+                "resource_size_request": "X_SMALL",
+                "keep_alive_time_seconds": 60 * 5,
+            },
+        )
+        cleanup.add(f"devbox:{devbox.id}", devbox.shutdown)
+
+        app_result = await devbox.cmd.exec("cat /app/app.py")
+        app_stdout = await app_result.stdout()
+
+        config_result = await devbox.cmd.exec("cat /app/config.txt")
+        config_stdout = await config_result.stdout()
+
+        return RecipeOutput(
+            resources_created=[
+                f"storage_object:{storage_obj.id}",
+                f"blueprint:{blueprint.id}",
+                f"devbox:{devbox.id}",
+            ],
+            checks=[
+                ExampleCheck(
+                    name="app.py exists and readable",
+                    passed=app_result.exit_code == 0,
+                    details=f"exitCode={app_result.exit_code}",
+                ),
+                ExampleCheck(
+                    name="app.py contains expected content",
+                    passed='print("Hello from app")' in app_stdout,
+                    details=app_stdout.strip(),
+                ),
+                ExampleCheck(
+                    name="config.txt exists and readable",
+                    passed=config_result.exit_code == 0,
+                    details=f"exitCode={config_result.exit_code}",
+                ),
+                ExampleCheck(
+                    name="config.txt contains expected content",
+                    passed="key=value" in config_stdout,
+                    details=config_stdout.strip(),
+                ),
+            ],
+        )
+
+
+run_blueprint_with_build_context_example = wrap_recipe(recipe)
+
+
+if __name__ == "__main__":
+    run_as_cli(run_blueprint_with_build_context_example)