sandbox-shell

name	sandbox-shell
description	Use when a task requires shell-level work inside the sandbox, including environment setup, script writing, code execution, running programs, downloads, package installs, scanning, or browser/tool CLIs.

Sandbox Shell

Use sandbox command tools for authorized task work inside the selected sandbox container.

Tool Contract

Command tools return compact JSON metadata; raw output is captured to output_file:

• Fields: status, output_file, output_bytes, output_lines, optional exit_code, run_id, error.
• Status values: running, completed, failed, canceled.
• Read output with read_sandbox_command_output using output_file and start_line: 1, at most 200 lines per call. Do not use cat.

Choosing Execution

Use execute_sync_command for short, local, bounded commands expected to finish within 30 seconds:

• file inspection, small scripts, local parsing, which, test, sed -n, head, tail, wc, bounded grep
• one sync command per assistant response unless the previous result requires an immediate bounded read

Use execute_async_command for anything slow, remote, stateful, or externally dependent:

• HTTP requests, downloads, scans, probes, brute-force checks, browser automation, package installs, builds, servers, watchers, REPLs
• loops around network, browser, install, build, scan, or other external resources
• consolidated scripts that run several slow checks and write structured output

Always pass timing arguments explicitly via timeout_seconds.

Async Jobs

After execute_async_command, keep the returned run_id and output_file.

• Continue independent work while the async job runs.
• The runtime automatically resumes the agent with completion context when the job finishes; no polling or waiting is needed.
• Use list_sandbox_async_jobs only for inspection or capacity checks.
• Use cancel_sandbox_async_job only when cancellation is requested or the job is no longer useful.
• Never use sleep, shell wait loops, repeated status polling, or filler progress messages.

At most 3 async commands may run for one agent instance.

Output Handling

• When metadata has terminal status and output_lines > 0, read needed chunks with read_sandbox_command_output.
• Continue with the next start_line only when the next chunk is needed.
• Do not re-run a command just to inspect an existing output_file.
• Use a new bounded command only when file-side filtering/counting is more efficient than reading chunks.
• Keep generated files and installed packages scoped to the task.

Python Packages

• Prefer uv for Python environments, package installs, and temporary tool execution.
• Use uv run, uvx, or uv pip inside a task-scoped virtual environment.
• Do not use global pip install or assume pip3 is available in the sandbox.

Available Tools

• Archives: 7z, unzip
• Shell/runtime: python3, uv, node, npm, nc, jq, rg, git
• Network: curl, wget, dig, nslookup, whois, openssl, httpx, nmap, sqlmap
• Fingerprinting: observer_ward
• Android/reversing: jadx, apktool, analyzeHeadless
• File/firmware: file, binwalk
• Browser: agent-browser-cli

Custom Scripts

Call custom skill scripts by absolute path:

• Ghidra wrapper: /root/.agents/skills/ghidra/scripts/ghidra-analyze.sh

Report only meaningful results: changed files, commands run, relevant output, and failures that affect completion.