core
API
Generated with
core/org.llm4s/org.llm4s.toolapi/org.llm4s.toolapi.builtin/org.llm4s.toolapi.builtin.shell

org.llm4s.toolapi.builtin.shell

package org.llm4s.toolapi.builtin.shell

Shell tools for executing system commands.

These tools provide safe shell access with configurable command allowlists and execution limits.

== Configuration ==

All shell tools require explicit command allowlisting via ShellConfig:

  • Allowed commands list (required for any execution)
  • Working directory configuration
  • Timeout limits
  • Output size limits

== Available Tools ==

  • ShellTool: Execute shell commands (requires explicit allowlist)

Attributes

Example 
import org.llm4s.toolapi.builtin.shell._
import org.llm4s.toolapi.ToolRegistry
// Read-only shell (ls, cat, etc.)
val readOnlyShell = ShellTool.create(ShellConfig.readOnly())
// Development shell with common dev tools
val devShell = ShellTool.create(ShellConfig.development(
 workingDirectory = Some("/path/to/project")
))
// Custom restricted shell
val customShell = ShellTool.create(ShellConfig(
 allowedCommands = Seq("git", "npm"),
 timeoutMs = 60000
))
val tools = new ToolRegistry(Seq(devShell))

Members list

Type members

Classlikes

case class ShellConfig(allowedCommands: Seq[String], workingDirectory: Option[String], timeoutMs: Long, maxOutputSize: Int, environment: Map[String, String])

Configuration for shell command tool.

Configuration for shell command tool.

Value parameters

allowedCommands

List of allowed command names (e.g., "ls", "cat", "echo"). If empty, no commands are allowed.

environment

Additional environment variables to set.

maxOutputSize

Maximum output size in characters.

timeoutMs

Maximum execution time in milliseconds.

workingDirectory

Optional working directory for command execution.

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object ShellConfig

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
case class ShellResult(command: String, exitCode: Int, stdout: String, stderr: String, executionTimeMs: Long, truncated: Boolean, timedOut: Boolean)

Shell command execution result.

Shell command execution result.

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object ShellResult

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
object ShellTool

Tool for executing shell commands under a strict allowlist.

Tool for executing shell commands under a strict allowlist.

IMPORTANT: This tool requires an explicit allowlist of commands for safety. It will not execute any command whose first token is not in the allowlist.

== Execution model ==

Commands are tokenized with shell-style quoting (see CommandTokenizer) and executed directly via ProcessBuilder '''without invoking a shell'''. As a consequence:

  • No glob expansion (*, ?, [abc] are passed literally to the program).
  • No variable substitution ($VAR, ${VAR}, $(...), backticks).
  • No command chaining or redirection (&&, ;, |, <, >, &).
  • Quoted arguments are honoured: echo "hello world" runs echo with one argument hello world, not two.

Combined with the allowlist, this means LLM-supplied input that contains shell metacharacters cannot escape into a shell — characters such as && survive tokenization as literal argument bytes and are handed to the allowlisted program, which generally treats them as harmless input.

== Features ==

  • Command allowlist for security
  • Configurable working directory
  • Timeout support
  • Output size limits

Attributes

Example 
{
import org.llm4s.toolapi.builtin.shell._
// Read-only shell (safe commands)
val readOnlyShell = ShellTool.create(ShellConfig.readOnly())
// Development shell (common dev tools)
val devShell = ShellTool.create(ShellConfig.development(
 workingDirectory = Some("/home/user/project")
))
val tools = new ToolRegistry(Seq(devShell))
agent.run("List files in the current directory", tools)

}

Supertypes
class Object
trait Matchable
class Any
Self type
ShellTool.type
Generated with