> ## Documentation Index
> Fetch the complete documentation index at: https://agents.nanonets.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Bash

> Runs shell commands in a secure per-task sandbox with Python 3.12 and data processing tools.

Runs a shell command in the task's secure per-task sandbox (bash + Python 3.12 with pandas, openpyxl, pdftotext, tesseract, unzip, and — after the image rebuild — lxml, pdfplumber, pymupdf, xlsxwriter, python-docx). Work on data with code instead of retyping it between tools. Display name **"Bash"**. Off by default — enable it in the agent's Tools panel.

## Authentication and enablement

No integration. Runs in the platform sandbox (process isolation, storage isolation, HTTP restrictions). **Off by default. Currently internal / POC only** — enable via superadmin per-agent in the Tools panel. Not suggested by the agent-builder.

## Inputs

* `command` (required): the shell command to execute. Runs under `/bin/bash -c`.
* `inputs` (optional): array of task variable names (e.g. `["VAR_27", "VAR_5"]`) to write as JSON files before the command runs. Each name becomes `/workspace/vars/<NAME>.json`.
* `timeout_seconds` (optional): execution timeout. Default `120`, max `600`.

## Workspace contract

Your command runs in `/workspace/` as the working directory:

* `/workspace/inputs/` — task files staged in (e.g. PDFs, CSVs, images uploaded or produced by prior steps).
* `/workspace/vars/` — JSON files corresponding to `inputs` array (e.g. `/workspace/vars/VAR_27.json` contains the variable's value).
* `/workspace/out/` — write downloadable files here. Each file becomes a new task file and a task variable reference (e.g. `/workspace/out/results.csv` → new variable `VAR_N` with mime type inferred from extension).
* `/workspace/.out/<step>.log` — fuller stdout/stderr written here if the in-result output is truncated (see Limits below for its own cap).

## Output

Result object with:

* `exit_code` (integer).
* `stdout` (string, capped \~16 KiB in the returned result; full output in the log file if truncated).
* `stderr` (string, same cap and truncation behavior).
* `truncated` (boolean): `true` if stdout or stderr was capped.
* `log_path` (string, optional): sandbox-internal path to the full output log, present only when `truncated` is `true`.
* `files` (array of objects): one per file written to `/workspace/out/`. Each has `name` (the file's name), `var` (the new `VAR_N` reference other steps can use), and `url` (download URL).

## Limits and side effects

* **Timeout**: 120s default, 600s max. Exceeding it terminates the command and returns a timeout error.
* **Output truncation**: stdout and stderr are each capped at \~16 KiB in the returned result. When truncated, the fuller output is written to `/workspace/.out/<step>.log` inside the sandbox workspace itself — it is **not** exported to any UI (there is no task-detail "Logs" tab view of it), so a later step in the same task must read it back via the bash tool. That log can itself be incomplete: the sandbox shim that runs your command caps stdout at \~1 MiB and stderr at \~256 KiB before Go ever sees the bytes, so a command producing more output than that loses the excess before it reaches `/workspace/.out/<step>.log` too.
* **File export**: up to 20 files per call, max 10 MiB per file. Files exceeding either cap are named in the result's "not exported (too large, over the per-command file limit, or unreadable): …" line; they are never silently dropped.
* **File persistence**: files in `/workspace/out/` are staged as task files for the next step, but **do not persist across independent task runs**. Each new task run re-stages `/workspace/inputs/` from the latest versions.
* **Network**: during the POC the sandbox has open outbound egress and carries no platform credentials — it is enabled on internal workspaces with test data only. Egress lockdown is planned hardening after the POC.
* **Billing**: each call is a billed step visible in the task feed.

## Expected errors

* `"sandbox runner not configured"` — feature not available in this environment (dark-launched feature off).
* Variable name not found in task context (e.g. `VAR_999` doesn't exist).
* `"output truncated"` — stdout or stderr exceeded the cap. `/workspace/.out/<step>.log` inside the sandbox has the fuller output — unless the sandbox shim itself already truncated upstream, in which case the note says so and the log is capped too.
* Exit code non-zero — command failed; inspect stdout/stderr and the log file for details.
* File export error — file too large or over the 20-file limit.