fix: add logs to devboxes, smoke tests & examples

Author: james-rl

examples/devbox_from_blueprint_lifecycle.py

@@ -3,17 +3,20 @@
 ---
 title: Devbox From Blueprint (Run Command, Shutdown)
 slug: devbox-from-blueprint-lifecycle
-use_case: Create a devbox from a blueprint, run a command, validate output, and cleanly tear everything down.
+use_case: Create a devbox from a blueprint, run a command, fetch logs, validate output, and cleanly tear everything down.
 workflow:
   - Create a blueprint
+  - Fetch blueprint build logs
   - Create a devbox from the blueprint
   - Execute a command in the devbox
-  - Validate exit code and stdout
+  - Fetch devbox logs
+  - Validate exit code, stdout, and logs
   - Shutdown devbox and delete blueprint
 tags:
   - devbox
   - blueprint
   - commands
+  - logs
   - cleanup
 prerequisites:
   - RUNLOOP_API_KEY
@@ -34,7 +37,7 @@
 
 
 def recipe(ctx: RecipeContext) -> RecipeOutput:
-    """Create a devbox from a blueprint, run a command, and clean up."""
+    """Create a devbox from a blueprint, run a command, fetch logs, and clean up."""
     cleanup = ctx.cleanup
 
     sdk = RunloopSDK()
@@ -46,6 +49,9 @@ def recipe(ctx: RecipeContext) -> RecipeOutput:
     )
     cleanup.add(f"blueprint:{blueprint.id}", blueprint.delete)
 
+    # Fetch blueprint build logs
+    blueprint_logs = blueprint.logs()
+
     devbox = blueprint.create_devbox(
         name=unique_name("example-devbox"),
         launch_parameters={
@@ -58,6 +64,9 @@ def recipe(ctx: RecipeContext) -> RecipeOutput:
     result = devbox.cmd.exec('echo "Hello from your devbox"')
     stdout = result.stdout()
 
+    # Fetch devbox logs
+    devbox_logs = devbox.logs()
+
     return RecipeOutput(
         resources_created=[f"blueprint:{blueprint.id}", f"devbox:{devbox.id}"],
         checks=[
@@ -71,6 +80,16 @@ def recipe(ctx: RecipeContext) -> RecipeOutput:
                 passed="Hello from your devbox" in stdout,
                 details=stdout.strip(),
             ),
+            ExampleCheck(
+                name="blueprint build logs are retrievable",
+                passed=blueprint_logs is not None and hasattr(blueprint_logs, "logs"),
+                details=f"blueprint_log_count={len(blueprint_logs.logs)}",
+            ),
+            ExampleCheck(
+                name="devbox logs are retrievable",
+                passed=devbox_logs is not None and hasattr(devbox_logs, "logs"),
+                details=f"devbox_log_count={len(devbox_logs.logs)}",
+            ),
         ],
     )
 

src/runloop_api_client/sdk/async_devbox.py

@@ -15,6 +15,7 @@
     DevboxExecutionDetailView,
     DevboxCreateSSHKeyResponse,
 )
+from ..types.devboxes.devbox_logs_list_view import DevboxLogsListView
 from ._types import (
     LogCallback,
     BaseRequestOptions,
@@ -163,6 +164,38 @@ async def get_tunnel_url(
             return None
         return f"https://{port}-{tunnel_view.tunnel_key}.tunnel.runloop.ai"
 
+    async def logs(
+        self,
+        *,
+        execution_id: str | None = None,
+        shell_name: str | None = None,
+        **options: Unpack[BaseRequestOptions],
+    ) -> DevboxLogsListView:
+        """Retrieve logs for the devbox.
+
+        Returns all logs from a running or completed devbox. Optionally filter
+        by execution ID or shell name.
+
+        :param execution_id: Filter logs by execution ID, defaults to None
+        :type execution_id: str | None, optional
+        :param shell_name: Filter logs by shell name, defaults to None
+        :type shell_name: str | None, optional
+        :param options: Optional request configuration
+        :return: Log entries for the devbox
+        :rtype: :class:`~runloop_api_client.types.devboxes.devbox_logs_list_view.DevboxLogsListView`
+
+        Example:
+            >>> logs = await devbox.logs()
+            >>> for log in logs.logs:
+            ...     print(f"[{log.level}] {log.message}")
+        """
+        return await self._client.devboxes.logs.list(
+            self._id,
+            execution_id=execution_id,
+            shell_name=shell_name,
+            **options,
+        )
+
     async def await_running(self, *, polling_config: PollingConfig | None = None) -> DevboxView:
         """Wait for the devbox to reach running state.
 

src/runloop_api_client/sdk/devbox.py

@@ -15,6 +15,7 @@
     DevboxExecutionDetailView,
     DevboxCreateSSHKeyResponse,
 )
+from ..types.devboxes.devbox_logs_list_view import DevboxLogsListView
 from ._types import (
     LogCallback,
     BaseRequestOptions,
@@ -162,6 +163,38 @@ def get_tunnel_url(
             return None
         return f"https://{port}-{tunnel_view.tunnel_key}.tunnel.runloop.ai"
 
+    def logs(
+        self,
+        *,
+        execution_id: str | None = None,
+        shell_name: str | None = None,
+        **options: Unpack[BaseRequestOptions],
+    ) -> DevboxLogsListView:
+        """Retrieve logs for the devbox.
+
+        Returns all logs from a running or completed devbox. Optionally filter
+        by execution ID or shell name.
+
+        :param execution_id: Filter logs by execution ID, defaults to None
+        :type execution_id: str | None, optional
+        :param shell_name: Filter logs by shell name, defaults to None
+        :type shell_name: str | None, optional
+        :param options: Optional request configuration
+        :return: Log entries for the devbox
+        :rtype: :class:`~runloop_api_client.types.devboxes.devbox_logs_list_view.DevboxLogsListView`
+
+        Example:
+            >>> logs = devbox.logs()
+            >>> for log in logs.logs:
+            ...     print(f"[{log.level}] {log.message}")
+        """
+        return self._client.devboxes.logs.list(
+            self._id,
+            execution_id=execution_id,
+            shell_name=shell_name,
+            **options,
+        )
+
     def await_running(self, *, polling_config: PollingConfig | None = None) -> DevboxView:
         """Wait for the devbox to reach running state.
 

tests/smoketests/sdk/test_devbox.py

@@ -1050,3 +1050,47 @@ def test_shell_exec_async_with_both_streams(self, devbox: Devbox) -> None:
         # Verify streaming captured same data as result
         assert stdout_combined == result.stdout()
         assert stderr_combined == result.stderr()
+
+
+class TestDevboxLogs:
+    """Test devbox logs retrieval functionality."""
+
+    @pytest.mark.timeout(THIRTY_SECOND_TIMEOUT)
+    def test_logs_basic(self, shared_devbox: Devbox) -> None:
+        """Test retrieving devbox logs returns valid response structure."""
+        # Fetch logs - the API may return empty logs depending on timing
+        logs = shared_devbox.logs()
+
+        assert logs is not None
+        assert hasattr(logs, "logs")
+        assert isinstance(logs.logs, list)
+
+    @pytest.mark.timeout(THIRTY_SECOND_TIMEOUT)
+    def test_logs_with_execution_filter(self, shared_devbox: Devbox) -> None:
+        """Test retrieving devbox logs filtered by execution ID."""
+        # Run a command and get its execution ID
+        execution = shared_devbox.cmd.exec_async('echo "filtered log test"')
+        result = execution.result()
+        assert result.exit_code == 0
+
+        # Fetch logs filtered by execution ID - verifies API accepts the filter
+        logs = shared_devbox.logs(execution_id=execution.execution_id)
+
+        assert logs is not None
+        assert isinstance(logs.logs, list)
+
+    @pytest.mark.timeout(THIRTY_SECOND_TIMEOUT)
+    def test_logs_with_shell_name_filter(self, shared_devbox: Devbox) -> None:
+        """Test retrieving devbox logs filtered by shell name."""
+        shell_name = "test-logs-shell"
+        shell = shared_devbox.shell(shell_name)
+
+        # Run a command in the named shell
+        result = shell.exec('echo "shell log test"')
+        assert result.exit_code == 0
+
+        # Fetch logs filtered by shell name - verifies API accepts the filter
+        logs = shared_devbox.logs(shell_name=shell_name)
+
+        assert logs is not None
+        assert isinstance(logs.logs, list)