PreviewDocs / Augments

Bash

Run explicitly configured host commands or operator-authored scripts.

Preview capability

This capability is usable, but its API and operational boundaries may change before 1.0. Pin exact versions and validate it deliberately before production use.

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

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

augments/bash/augment.yamlyaml

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 inputjson

{
  "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.

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

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

Add an augmentInstall layeredMemory, inspect what the CLI adds, and verify peer-scoped memory in Console.SkillsTeach the model when and how to use an augment without loading every instruction into context on every turn.SecurityAuggy's security boundaries, the prompt-injection threat model, and how to report a vulnerability privately.Deploy and verifyDeploy the agent to Railway and verify its health, route, console, and application client.