Bash

This document details the Bash agent, which allows for the secure execution of shell scripts and command-line tools within an agentic workflow. You will learn how to configure its sandboxed environment, manage command permissions, and integrate it into your applications for system-level operations.

Overview#

The Bash agent is designed to execute bash scripts within a controlled and secure environment. It leverages Anthropic's Sandbox Runtime to provide an isolated execution space, offering fine-grained control over system access, including network and filesystem operations. This makes it an ideal tool for tasks requiring file manipulation, process management, and automation of shell commands without compromising system security.

Key features include:

• Sandboxed Execution: Scripts are run in an isolated environment with configurable access controls for network and filesystem resources.
• Command Permissions: A robust permission system allows you to whitelist, blacklist, or require approval for specific commands, preventing unauthorized operations.
• Real-time Output: Standard output (stdout) and standard error (stderr) are streamed in real-time as the script executes.
• Guard Agents: For commands requiring approval, you can designate another agent (an "AI guard") to dynamically approve or deny execution based on custom logic.

Architecture#

The agent processes a script and, depending on whether the sandbox is enabled, either runs it directly or within the sandboxed environment. The output, including stdout, stderr, and the final exitCode, is streamed back to the caller.

Basic Usage#

The most straightforward way to use the Bash Agent is by defining it in a YAML file. This allows you to configure its behavior declaratively.

Standard Sandboxed Mode#

By default, the Bash agent runs in a secure, sandboxed environment.

type: "@aigne/agent-library/bash"
name: Bash

# The input schema defines the 'script' parameter
input_schema:
  type: object
  properties:
    script:
      type: string
      description: The bash script to execute.
  required:
    - script

You can then execute a script using the AIGNE CLI:

aigne run . Bash --script 'echo "Hello from the Bash Agent!"'

Disabling the Sandbox#

For development, trusted environments, or on Windows, you can disable the sandbox.

type: "@aigne/agent-library/bash"
name: Bash
sandbox: false # Disable the sandbox

input_schema:
  type: object
  properties:
    script:
      type: string
      description: The bash script to execute.
  required:
    - script

Configuration#

The Bash agent can be configured with several options to control its execution environment and security settings.

Input and Output#

The agent accepts a simple input object and produces a detailed output object.

Input Schema#

Output Schema#

Sandbox Configuration#

The sandbox provides a secure layer for script execution by restricting access to network and filesystem resources.

Network Control#

You can specify which domains a script is allowed or forbidden to access.

sandbox:
  network:
    # A list of allowed domains. Wildcards are supported.
    allowedDomains:
      - "api.github.com"
      - "*.example.com"
    # A list of denied domains, which takes precedence over the allow list.
    deniedDomains:
      - "*.ads.com"

Filesystem Control#

Define read and write permissions for specific paths or patterns.

sandbox:
  filesystem:
    # A list of paths where writing is permitted.
    allowWrite:
      - "./output"
      - "/tmp"
    # A list of paths where writing is forbidden.
    denyWrite:
      - "/etc"
      - "/usr"
    # A list of paths where reading is forbidden.
    denyRead:
      - "~/.ssh"
      - "*.key"

Permissions Configuration#

The permissions system controls which commands can be executed. It operates with a clear priority: deny rules override allow rules, and allow rules override the defaultMode.

Permission Properties#

Example with a Guard Agent#

When defaultMode is set to ask, you must provide a guard agent to approve or reject commands. The guard agent receives the script as input and must return an object containing an approved boolean and an optional reason string.

type: "@aigne/agent-library/bash"
name: Bash
permissions:
  allow:
    - "echo:*"
    - "ls:*"
  deny:
    - "rm:*"
    - "sudo:*"
  defaultMode: "ask"
  guard:
    type: "ai"
    model: "anthropic/claude-3-5-sonnet-20241022"
    instructions: |
      You are a security guard for bash command execution.
      Analyze the requested script and decide whether to approve it.

      Script to evaluate:
      ```bash
      {{script}}
      ```

      Approve safe, read-only operations. Deny any command that
      could modify or delete files, or alter system state.
    output_schema:

Best Practices#

• Use the Sandbox: Always enable the sandbox in production environments to mitigate security risks.
• Principle of Least Privilege: Configure sandbox and permission rules to grant only the minimum access necessary for the task.
• Deny Dangerous Commands: Explicitly add destructive commands like rm, sudo, and dd to the deny list.
• Handle Exit Codes: Check the exitCode in the agent's output to detect and handle script failures. An exit code other than 0 usually indicates an error, and details can be found in stderr.
• Protect Sensitive Files: Use denyRead to prevent access to sensitive files and directories such as ~/.ssh, .env files, and private keys.