# Bash

Canonical: https://auggy.dev/docs/augment-bash
Status: Preview
Package: auggy 0.5.0

Run explicitly configured host commands or operator-authored scripts.

## Outcome

**What it enables:** Give a creator-scoped turn the ability to inspect or operate on the **Auggy** host.

- **Status:** Preview
- **Availability:** Install with ``auggy augment add` bash`.
- **Contributes:** `tools`

Bash executes child processes on the host. It is useful for bounded inspection and operator-authored maintenance scripts, but it does not create a sandbox.

## Install and configure

1. Run ``auggy augment add` bash` in the agent project and confirm the Preview prompt.
2. Review `augments/bash/augment.yaml`; the bundled skill is copied to `skills/bash/SKILL.md`.
3. Run ``auggy doctor``, then restart the agent after changing this file.

**augments/bash/augment.yaml**

```yaml
type: bash
config:
  risk: restricted
  allowedCommands:
    - echo
    - ls
    - cat
    - pwd
    - date
```

This is the catalog default. `restricted` requires `allowedCommands`; adding an allowlist forces exec mode, so shell pipes, redirects, chaining, and command substitution are not interpreted.

## Use it

A creator can inspect the agent workspace without enabling unrestricted shell features. The tool receives a command and, in restricted mode, an argument array.

**shell_exec input**

```json
{
  "command": "ls",
  "args": ["-la"]
}
```

The result is JSON with `stdout`, `stderr`, `exitCode`, `durationMs`, and `truncated`. Keep commands read-only unless the host and trust policy are deliberately controlled.

## Runtime surfaces

| Surface | Exact behavior |
| --- | --- |
| `shell_exec` | Input `{ command, args? }`; executes one command and returns JSON process results. |
| `run_script` | Available when `scripts` is non-empty; input `{ name }`; runs one operator-authored script. |
| Trust gate | ``shell_exec`` and ``run_script`` are hidden from `public` and `agent` peers by default; creator gets them. |
| Limits | Default timeout 30,000 ms, 262,144 bytes per output stream, and 10 tool calls per turn. |

## Boundaries

| Area | Current boundary |
| --- | --- |
| Trust | Host execution is creator-only by default. An explicit `perTrustLevel` override can expose tools to an agent peer; do not expose them to public traffic. |
| Persistence | Bash has no execution-state store. Commands can read or mutate the host filesystem and processes; only the current tool result returns to the turn. |
| Deployment | The child runs in the same host or container boundary as **Auggy**. A container is an operational boundary, not a Bash sandbox. |
| Limitations | `standard` enables shell syntax, `unrestricted` also inherits the full environment, and blocklists are not a complete security policy. Timeouts kill the process group; output is capped and can be truncated. |

> **Warning: Not a sandbox**
>
> Bash is host process execution, not a sandbox. Use a separate hardened execution service when commands or data are not fully trusted.

## Verify

1. Run ``auggy doctor`` and confirm the Bash config parses with `risk: restricted` and the five default commands.
2. Start the agent and, as Creator, call ``shell_exec`` with `{ "command": "pwd" }`; confirm a JSON result with `exitCode: 0`.
3. Call ``shell_exec`` with `{ "command": "printf", "args": ["no"] }`; confirm the allowlist rejects it.
4. Inspect the runtime capability view as an agent or public peer; confirm neither Bash tool is exposed by default.

## Related

- [Add an augment](https://auggy.dev/docs/add-augment/markdown)
- [Skills](https://auggy.dev/docs/add-skills/markdown)
- [Security](https://auggy.dev/docs/security/markdown)
- [Deploy and verify](https://auggy.dev/docs/deploy/markdown)