Use the bash tool

The Bash tool gives an agent a shell for running built-in commands and explicitly registered host programs. The shell uses the agent's filesystem and network policy, while the tool block controls its working directory, host programs, environment, execution limits, and interpreter lifecycle.

Add the tool

Declare a tool with kind = "bash":

tool "shell" {
  kind = "bash"
}

The agent must hold the built-in bash capability to invoke it:

agent "assistant" {
  capabilities = ["bash"]

  graph {
    type = "react"
  }

  model {
    provider = "anthropic"
    name     = "claude-haiku-4-5"
  }
}

See Control tool access with capabilities for capability matching and per-session policy.

Set the working directory

cwd is the shell's initial directory in the agent filesystem. It defaults to /home/agent and always uses a POSIX path, including when the agent runs on Windows.

Mount the directory through the top-level filesystem block, then set cwd to its virtual path:

filesystem {
  mounts = [
    {
      path = "/workspace"
      backend = {
        kind = "host"
        root = "./workspace"
      }
    }
  ]
}

tool "shell" {
  kind = "bash"
  cwd  = "/workspace"
}

All components use the same agent filesystem. Files created by one Bash invocation remain visible to later invocations according to the configured filesystem backend. See Give your agent a filesystem for mounts, read-only views, overlays, and runtime binds.

Add host programs

Bash includes its own shell commands. Use commands to register additional programs from the host, such as git:

tool "shell" {
  kind     = "bash"
  commands = ["git"]
}

Each listed program must be available on the host when the agent runs. Omitting commands registers no additional host programs.

Control the environment

The env block controls which host environment variables enter the shell. The default empty policy forwards none.

Use allow to forward only named variables:

tool "shell" {
  kind = "bash"

  env {
    kind = "allow"
    vars = ["HOME", "PATH"]
  }
}

The available policies are:

• empty forwards no variables.
• inherit forwards all variables.
• allow forwards only variables in vars.
• deny forwards all variables except those in vars.

Choose the interpreter lifecycle

Each invocation gets a fresh interpreter by default. Variables, functions, aliases, and working directory changes do not carry into the next invocation. Filesystem changes can still persist because the filesystem is shared independently of the interpreter.

Set shared = true when shell-local state must persist:

tool "shell" {
  kind   = "bash"
  shared = true
}

Shared mode retains variables, functions, aliases, and working directory changes between invocations. Invocations through that tool are serialized so they do not execute concurrently in the same interpreter.

Set execution limits

Use limits to restrict one invocation:

tool "shell" {
  kind = "bash"

  limits {
    max_execution_time_secs = 30
    max_output_size         = 10485760
    max_command_count       = 10000
    max_loop_iterations     = 10000
  }
}

Omitted fields use the defaults shown above.

Control curl access

The built-in curl command uses the agent's HTTP client and follows the top-level network policy. Configure its allowed destinations, methods, address classes, and limits through the network block. Curl compatibility flags cannot weaken that policy or bypass its limits.

See Control network egress for the configuration steps.

Where to go next

• tool reference: Bash fields and defaults.
• filesystem reference: the filesystem used by Bash.
• network reference: the policy used by built-in curl.
• Tools and capabilities: how tools become available to an agent.