Log Search Tool
The search_sandbox_logs tool finds specific events in large log volumes
without loading the entire log into context.
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
sandbox_id | string | required | Target sandbox ID |
query | string | required | FTS5 search query (e.g., "ERROR", "connection refused") |
stream | string | both | Log stream: "stdout" or "stderr". If omitted, both streams are searched. |
max_results | number | 20 | Maximum number of matching lines to return |
since | string | optional | ISO 8601 timestamp — only return lines at or after this time |
level | string | optional | Filter by severity: "ERROR", "WARN", "INFO", "DEBUG" |
Output Format
Returns a JSON object with a matches array. Each match contains the matched
line, surrounding context lines, and the line number in the original log file.
How It Reduces Log Volume
A 50 MB nginx access log contains roughly 500,000 lines. Rather than
returning the raw tail (still dozens of KB), the agent issues a targeted
FTS5 query and receives at most max_results x 5 lines (match + 2 context
lines on each side). For max_results = 20 that is at most 100 lines —
typically under 5 KB.
When to Use This vs. get_sandbox_logs
Prefer search_sandbox_logs when looking for specific errors or events in
large log volumes. Fall back to get_sandbox_logs only when you need the
raw tail (e.g. to see startup sequence or recent activity without a keyword).