docs: Add logging guide and update references

Add docs/guides/logging.md covering stream_logs() and the
aviato logs CLI command. Add interactive_streaming_sandbox.py
example for log streaming.

Update execution.md, sync-vs-async.md, troubleshooting.md,
mkdocs.yml nav, and AGENTS.md files with new entries.

Author: iiilisan

AGENTS.md

@@ -35,6 +35,11 @@ with Sandbox.run("sleep", "infinity") as sb:
         print(line, end="")
     result = process.result()  # Get final ProcessResult
 
+# Streaming logs
+with Sandbox.run("sleep", "infinity") as sb:
+    for line in sb.stream_logs(follow=True, tail_lines=100):
+        print(line, end="")
+
 # Async context manager
 async with Sandbox.run("sleep", "infinity") as sb:
     result = await sb.exec(["echo", "hello"])
@@ -46,6 +51,7 @@ Key methods:
 - `wait()`: Block until RUNNING status, returns self for chaining
 - `wait_until_complete(timeout=None, raise_on_termination=True)`: Wait until terminal state (COMPLETED, FAILED, TERMINATED), return `OperationRef[Sandbox]`. Call `.result()` to block or `await` in async contexts. Set `raise_on_termination=False` to handle externally-terminated sandboxes without raising `SandboxTerminatedError`.
 - `exec(command, cwd=None, check=False, timeout_seconds=None, stdin=False)`: Execute command, return `Process`. Call `.result()` to block for `ProcessResult`. Iterate `process.stdout` before `.result()` for real-time streaming. Set `check=True` to raise `SandboxExecutionError` on non-zero returncode. Set `cwd` to an absolute path to run the command in a specific working directory (implemented via shell wrapping, requires /bin/sh in container). Set `stdin=True` to enable stdin streaming via `process.stdin`.
+- `stream_logs(follow=False, tail_lines=None, since_time=None, timestamps=False)`: Stream logs from sandbox, return `StreamReader` directly. Iterate synchronously with `for line in reader` or asynchronously with `async for line in reader`. Set `follow=True` for continuous streaming (like `tail -f`). Set `timestamps=True` to prefix lines with ISO 8601 timestamps.
 - `read_file(path)`: Return `OperationRef[bytes]`
 - `write_file(path, content)`: Return `OperationRef[None]`
 - `stop(snapshot_on_stop=False, graceful_shutdown_seconds=10.0, missing_ok=False)`: Stop sandbox and return `OperationRef[None]`. Raises `SandboxError` on failure. Set `snapshot_on_stop=True` to capture sandbox state before shutdown. Set `missing_ok=True` to suppress `SandboxNotFoundError`.
@@ -140,7 +146,7 @@ data = await ref
 **Exec Types** (`_types.py`): Types for command execution, returned by `Sandbox.exec()`:
 
 - `Process`: Handle for running process with `stdout`/`stderr` StreamReaders and optional `stdin` StreamWriter. Properties: `returncode` (exit code or None), `command` (list executed), `stdin` (StreamWriter when `stdin=True`, or None). Methods: `poll()`, `wait(timeout)`, `result(timeout)`, `cancel()`. Awaitable in async contexts.
-- `StreamReader`: Dual sync/async iterable wrapping asyncio.Queue. Supports both `for line in reader` and `async for line in reader`.
+- `StreamReader`: Dual sync/async iterable wrapping asyncio.Queue. Supports both `for line in reader` and `async for line in reader`. Exception instances in the queue are re-raised to the consumer (used by `stream_logs()` to propagate errors).
 - `StreamWriter`: Writable stream for stdin. Methods: `write(data: bytes)`, `writeline(text: str)`, `close()`. All return `OperationRef[None]`. Property: `closed` (bool). Uses bounded queue (16 items, ~1MB with 64KB chunks) for backpressure.
 - `ProcessResult`: Dataclass with `stdout`, `stderr`, `returncode`, `command`, plus raw byte variants (`stdout_bytes`, `stderr_bytes`).
 
@@ -298,12 +304,15 @@ Commands:
 |---------|------|-------------|
 | `aviato exec` | `cli/exec.py` | Execute a command in a sandbox (`--cwd`, `--timeout`) |
 | `aviato list` | `cli/list.py` | List sandboxes with optional filters (`--status`, `--tag`, `--runway-id`, `--tower-id`) |
+| `aviato logs` | `cli/logs.py` | Stream container logs (`--follow`, `--tail`, `--since`, `--timestamps`) |
 
 ```bash
 aviato exec <sandbox-id> echo hello             # Run a command
 aviato exec <sandbox-id> --cwd /app ls -la     # Run with working directory
 aviato list                                    # List all sandboxes
 aviato list --status running --tag my-project  # Filter by status and tag
+aviato logs <sandbox-id> --follow              # Stream logs
+aviato logs <sandbox-id> --tail 50 --timestamps
 ```
 
 Adding new CLI commands:

DEVELOPMENT.md

@@ -151,6 +151,7 @@ aviato --version                           # Show SDK version
 aviato list                                # List sandboxes
 aviato list --status running --tag dev     # Filter sandboxes
 aviato exec <sandbox-id> echo hello        # Run a command in a sandbox
+aviato logs <sandbox-id> --follow          # Stream container logs
 ```
 
 You can also invoke it as a Python module:

docs/guides/AGENTS.md

@@ -18,6 +18,7 @@ Task-oriented guides for common operations. Each guide answers "How do I...?"
 | `environment-variables.md` | Use environment variables in sandboxes |
 | `swebench.md` | Run SWE-bench evaluations with parallel Aviato sandboxes |
 | `rl-training.md` | RL training with code execution rewards, TRL integration |
+| `logging.md` | Stream sandbox container logs with `stream_logs()` and `aviato logs` CLI |
 
 ## Key Patterns
 

docs/guides/execution.md

@@ -313,6 +313,10 @@ aviato exec <sandbox-id> --timeout 30 python script.py
 
 Exits with the command's return code.
 
+!!! note "exec stdout vs container logs"
+    `exec()` streams output from a specific command. For container-level logs (PID 1 stdout/stderr),
+    use [`stream_logs()`](logging.md) instead.
+
 ## Process Control
 
 The `Process` object provides methods for monitoring and control:

docs/guides/logging.md

@@ -0,0 +1,77 @@
+<!--
+SPDX-FileCopyrightText: 2025 CoreWeave, Inc.
+SPDX-License-Identifier: Apache-2.0
+SPDX-PackageName: aviato-client
+-->
+
+# Sandbox Logging
+
+Stream logs from a running sandbox with `stream_logs()`. Returns a `StreamReader` that yields log lines — iterate synchronously or asynchronously.
+
+## Retrieve recent logs
+
+```python
+for line in sandbox.stream_logs(tail_lines=100):
+    print(line, end="")
+```
+
+## Follow mode
+
+Stream logs continuously, like `tail -f`. The iterator blocks until new data arrives.
+
+```python
+for line in sandbox.stream_logs(follow=True):
+    print(line, end="")
+```
+
+Press Ctrl-C to stop when iterating in follow mode.
+
+## Filter by time
+
+Only retrieve logs after a specific timestamp.
+
+```python
+from datetime import datetime, timezone
+
+since = datetime(2026, 2, 20, 14, 0, 0, tzinfo=timezone.utc)
+for line in sandbox.stream_logs(since_time=since):
+    print(line, end="")
+```
+
+## Timestamps
+
+Prefix each line with an ISO 8601 timestamp from the server.
+
+```python
+for line in sandbox.stream_logs(tail_lines=10, timestamps=True):
+    print(line, end="")
+# Output: 2026-02-20T14:30:00Z some log line
+```
+
+## Async iteration
+
+```python
+async for line in sandbox.stream_logs(follow=True):
+    print(line, end="")
+```
+
+## CLI
+
+The `aviato logs` command wraps `stream_logs()` for terminal use:
+
+```bash
+aviato logs <sandbox-id>                    # Recent logs
+aviato logs <sandbox-id> --follow           # Follow mode
+aviato logs <sandbox-id> --tail 50          # Last 50 lines
+aviato logs <sandbox-id> --timestamps       # With timestamps
+aviato logs <sandbox-id> --since "2026-02-20 14:00:00"
+```
+
+## What are container logs?
+
+Container logs capture stdout and stderr from the sandbox's main process (PID 1). Commands run via `exec()` produce output on the exec stream, not container logs. To generate logs visible to `stream_logs()`, your sandbox command must write to stdout or stderr.
+
+## See also
+
+- [Command Execution](execution.md) — running commands with `exec()`
+- [Sync vs Async](sync-vs-async.md) — iteration patterns

docs/guides/sync-vs-async.md

@@ -42,7 +42,7 @@ and stdin.
 `session.sandbox()` returns an unstarted sandbox. The sandbox auto-starts on the first operation
 that needs it:
 
-**Triggers auto-start**: `exec()`, `read_file()`, `write_file()`, `wait()`, `wait_until_complete()`
+**Triggers auto-start**: `exec()`, `read_file()`, `write_file()`, `wait()`, `wait_until_complete()`, `stream_logs()`
 
 **Does not auto-start**: `get_status()` (raises `SandboxNotRunningError`), `stop()` (no-op if never started)
 
@@ -307,6 +307,22 @@ print(f"Sandbox is {status}")  # e.g. SandboxStatus.RUNNING
     result = await sb.exec(["echo", "adopted"])
     ```
 
+### stream_logs()
+
+=== "Sync"
+
+    ```python
+    for line in sandbox.stream_logs(follow=True, tail_lines=100):
+        print(line, end="")
+    ```
+
+=== "Async"
+
+    ```python
+    async for line in sandbox.stream_logs(follow=True, tail_lines=100):
+        print(line, end="")
+    ```
+
 ### Streaming stdout
 
 === "Sync"

docs/guides/troubleshooting.md

@@ -179,6 +179,22 @@ See [Cleanup Patterns - Orphan Management](cleanup-patterns.md#orphan-management
 
 ---
 
+## CLI Issues
+
+### aviato logs: no output
+
+**Issue**: `aviato logs` shows nothing.
+
+**Causes and solutions**:
+
+| Cause | Solution |
+|-------|----------|
+| Sandbox not yet running | Wait for RUNNING status before streaming logs |
+| Container writes to files, not stdout | Logs only capture PID 1 stdout/stderr. Use `exec()` to read files instead |
+| Log data not yet flushed | Use `--follow` to wait for new output |
+
+---
+
 ## Common Error Messages
 
 | Error | Cause | Solution |

mkdocs.yml

@@ -81,6 +81,7 @@ nav:
       - Sessions: guides/sessions.md
       - Remote Functions: guides/remote-functions.md
       - Sandbox Configuration: guides/sandbox-configuration.md
+      - Sandbox Logging: guides/logging.md
       - Cleanup Patterns: guides/cleanup-patterns.md
       - Sync vs Async: guides/sync-vs-async.md
       - Troubleshooting: guides/troubleshooting.md

src/aviato/AGENTS.md

@@ -25,7 +25,8 @@ aviato/
 ├── exceptions.py     # Exception hierarchy
 ├── py.typed          # PEP 561 type information marker
 └── cli/              # CLI subpackage (only loaded when `aviato` command is invoked)
-    └── __init__.py   # Click group, registers commands
+    ├── __init__.py   # Click group, registers commands
+    └── logs.py       # aviato logs command
 ```
 
 ## Naming Conventions

tests/AGENTS.md

@@ -112,6 +112,7 @@ Tests skip gracefully with clear messages when no auth is configured. The `requi
 | `test_cli_main.py` | `__main__` entry point, --help, --version, ImportError fallback |
 | `test_cli_list.py` | CLI list command, filters, empty state, API errors |
 | `test_cli_exec.py` | CLI exec command, stdout, stderr, returncode, cwd, timeout, not-found error |
+| `test_cli_logs.py` | CLI logs command, follow, tail, since, timestamps, error handling |
 
 ### Integration Test Files (`tests/integration/aviato/`)