The Terminal Toolkit provides a secure and powerful way for CAMEL agents to interact with a terminal. It allows agents to execute shell commands, manage files, and even ask for human help, all within a controlled, sandboxed environment.

Secure Sandboxed Execution

All file-writing and execution commands are restricted to a designated working_directory to prevent unintended system modifications. Dangerous commands are blocked by default.

Multi-Session Management

Run multiple, independent terminal sessions concurrently. Each session maintains its own state and history, allowing for complex, parallel workflows.

Virtual Environment Management

Automatically create and manage isolated Python virtual environments, ensuring that package installations and script executions don’t conflict with your system setup.

Human-in-the-Loop

When an agent gets stuck, it can pause its execution and request human assistance. A human can then take over the terminal session to resolve the issue before handing control back.

​
Initialization

To get started, initialize the TerminalToolkit. You can configure its behavior, such as the working directory and environment settings. 
from camel.toolkits import TerminalToolkit

# Initialize with default settings.
# Safe mode is ON and working_directory is './workspace'
terminal_toolkit = TerminalToolkit()

​
Usage Examples

​
Executing Commands

The shell_exec function is the primary way to execute commands. Each command is run within a session, identified by a unique id. 
# Execute the 'ls -l' command in 'session_1'
output = terminal_toolkit.shell_exec(id='session_1', command='ls -l')
print(output)

​
Interacting with Processes

You can manage long-running or interactive processes.
You can write to a process’s standard input using shell_write_to_process. This is useful for interactive command-line tools.
# Start a python REPL in a new session
terminal_toolkit.shell_exec(id='interactive_session', command='python')

# Write code to the python process
terminal_toolkit.shell_write_to_process(
    id='interactive_session',
    input='print("Hello, interactive world!")',
    press_enter=True
)

# View the output
output = terminal_toolkit.shell_view(id='interactive_session')
print(output)

​
Safe Mode

When safe_mode is enabled (default), the toolkit blocks commands that could be harmful to your system.

Example of a Blocked Command

# This command attempts to delete a file outside the workspace.
# The toolkit will block it and return an error message.
output = terminal_toolkit.shell_exec(id='session_1', command='rm /etc/hosts')

print(output)
# Expected Output:
# Command rejected: Safety restriction: Cannot delete files outside of working directory ...

​
Human-in-the-Loop

When an agent gets stuck, it can use ask_user_for_help to request human intervention.

Asking for Human Help

# The agent is stuck, so it asks for help in 'session_1'
help_result = terminal_toolkit.ask_user_for_help(id='session_1')

# The script will now pause and wait for the user to type commands
# in the console. After the user types '/exit', the script will resume.
print(help_result)