sandbox-shell

# sandbox-shell Use sandbox command tools for authorized task work inside the selected sandbox container. ## Skill loading required - Before using any domain-specific tool, load and follow that tool's matching skill when one exists. - Loading only `sandbox-shell` is not enough for specialized tools such as `agent-browser-cli`, `apktool`, `binwalk`, `checksec`, `dnsx`, `gdb-pwndbg`, `ghidra`, `httpx`, `jadx`, `nmap`, `openssl`, `pwntools`, or `strace-ltrace`. - If no dedicated skill exists for a needed command, use this skill plus the installed command help as the source of truth. ## Usage rules - Prefer the sandbox image's preinstalled tools. Do not install, upgrade, reinstall, or replace a tool that is already available. - Check an existing command with `command -v`, `--version`, or installed help before considering any install step. - Use `uv` only for missing Python dependencies, task-scoped virtual environments, or tools that are not already present and are required for the task. - Treat the preinstalled network inventory as the normal execution boundary. Use its listed tools with small reviewed inputs and conservative rates; do not add network CLIs during ordinary task work. - Keep environment changes task-scoped. Do not use `apt`, global `pip`, curl-piped installers, or language package managers to overwrite bundled tools unless the user explicitly asks. ## Tool contract Command tools return compact JSON metadata; raw output is captured to `output_file`: - `execute_sync_command` returns `status`, `output_file`, `output_bytes`, `output_lines`, and optional `exit_code`. - `execute_async_command` returns only `status` and `run_id`; its terminal `status`, `exit_code`, and `output_file` are delivered later when the runtime resumes you. - 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, `command -v`, `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, bounded network diagnostics, browser automation, missing dependency installs, builds, servers, watchers, REPLs - loops around network, browser, dependency setup, build, diagnostics, 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 Dispatching `execute_async_command` ends the current turn immediately. - After dispatching, do not continue working, run follow-up steps, or take any further action — your turn is over. - The runtime resumes you automatically when the job finishes, delivering its `status`, `exit_code`, and `output_file` as fresh context. - Never poll, read, or check a running job, and never use `sleep`, shell wait loops, or filler progress messages — there is nothing to do but wait to be resumed. - Use `cancel_sandbox_async_job` only when cancellation is requested or the job is no longer useful. ## 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 - Use `uv` only when the required Python package or CLI is not already preinstalled, or when task isolation is necessary. - Create task virtual environments with `uv venv --python /usr/bin/python3 <dir>` when a script needs dependencies outside the bundled toolset. - Install missing Python dependencies with `uv pip install --python <dir>/bin/python ...`. - Run one-off Python commands with missing dependencies using `uv run --python /usr/bin/python3 --with <package> python ...`; avoid this for packages already provided by preinstalled tool environments. - Run temporary CLI tools with `uvx --python /usr/bin/python3 <tool>` or `uv tool run --python /usr/bin/python3 <tool>` only when no preinstalled equivalent exists. - Install persistent Python CLI tools with `uv tool install --python /usr/bin/python3 --no-python-downloads <tool>` only when repeated use is required and the tool is not already in the image. - Prefer the existing `/usr/bin/python3`; `UV_PYTHON_DOWNLOADS=never` is set in the image, and another Python should be downloaded only when the user explicitly asks. - Do not use global `pip install` or assume `pip3` is available unless the user explicitly asks and the reason is recorded. ## Available tools - Archives: `7z`, `unzip`, `tar` - Shell/runtime: `python3`, `uv`, `uvx`, `node`, `npm`, `jq`, `rg`, `git`, `sha256sum` - Network: `curl`, `wget`, `nc`, `dig`, `nslookup`, `whois`, `openssl`, `httpx`, `dnsx`, `nmap` - Android/reversing: `jadx`, `apktool`, `ghidra`, `analyzeHeadless` - Reverse/pwn: `gdb`, `pwndbg`, `strace`, `ltrace`, `pwntools`, `checksec` from `pwntools` - File/firmware: `file`, `binwalk`, `readelf` - Browser: Chrome for Testing (`google-chrome`, `chrome`) and `agent-browser-cli` ## Tool selection boundaries - `checksec` is provided by `pwntools`; do not install a separate checksec package. - Use `dnsx` only for bounded batch DNS validation; use `dns-whois` tools for targeted manual DNS or registration triage. - Use `httpx` for bounded HTTP liveness and normalization, and `nmap` for targeted port or service checks. - Use `gdb`/`pwndbg` for debugger state, `strace`/`ltrace` for runtime traces, and `pwntools` for repeatable binary interaction. ## Skill resource paths Use `.agents/skills/<skill-name>/...` paths in sandbox commands for skill-shipped files: - Ghidra wrapper: `.agents/skills/ghidra/scripts/ghidra-analyze.sh` ## Output Report only meaningful results: changed files, commands run, relevant output, and failures that affect completion.