Skip to main content
This guide shows how to capture container logs from a sandbox so you can monitor what your main process does, debug failures, or inspect output after a sandbox stops. Container logs are stdout and stderr from a sandbox’s main process. Stream them with stream_logs(), which captures output from the command passed to Sandbox.run(). Output from exec() commands isn’t included. Use Process.stdout or Process.stderr for that. stream_logs() returns a StreamReader that yields log lines. Iterate synchronously or asynchronously.
When you call Sandbox.run() without a command, the sandbox’s default command doesn’t write to stdout or stderr, so stream_logs() returns no output. Pass a command that writes to stdout or stderr.

​
Retrieve recent logs

Use tail_lines to fetch the most recent log lines without streaming the entire history. This is useful for quick inspection of a running sandbox. 
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. 
for line in sandbox.stream_logs(follow=True):
    print(line, end="")
Press Ctrl+C to stop when iterating in follow mode.

​
Filter by time

Pass since_time to retrieve only logs after a specific timestamp. This narrows output to a window of interest, such as logs since a deployment or incident. 
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

Set timestamps=True to prefix each line with an ISO 8601 timestamp from the server. Server-side timestamps help correlate sandbox events with other systems. 
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

If your application uses asyncio, iterate over the same StreamReader with async for to avoid blocking the event loop. 
async for line in sandbox.stream_logs(follow=True):
    print(line, end="")

​
Retrieve logs from stopped sandboxes

Logs remain available after a sandbox stops, which lets you investigate failures or review output from completed work. Retrieve historical logs from sandboxes that completed, failed, or terminated: 
sb = Sandbox.from_id("sbx-abc123").result()
for line in sb.stream_logs(tail_lines=50):
    print(line, end="")
Stopped sandboxes support only follow=False (the default).

​
See also

Last modified on May 29, 2026