CAMEL - Build Multi-Agent AI Systems

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.

Default
Custom Workspace
Cloned Environment

from camel.toolkits import TerminalToolkit

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

from camel.toolkits import TerminalToolkit

# Specify a custom sandboxed working directory
terminal_toolkit = TerminalToolkit(
    working_directory="./my_safe_workspace"
)

from camel.toolkits import TerminalToolkit

# Clone the current python environment into the workspace
# for the agent to use without affecting the original.
terminal_toolkit = TerminalToolkit(clone_current_env=True)

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. How it works

block=True (default): waits for completion and returns combined stdout/stderr.
block=False: starts a background session for interactive/long-running tasks.
The id is how you later view output or terminate the session.

Listing Files
Running a Python Script

# Execute the 'ls -l' command in 'session_1'
output = terminal_toolkit.shell_exec(id='session_1', command='ls -l')
print(output)

# First, create a python script inside the workspace
write_script_cmd = """
echo 'print("Hello from a sandboxed CAMEL environment!")' > hello.py
"""
terminal_toolkit.shell_exec(id='session_1', command=write_script_cmd)

# Now, execute the script
output = terminal_toolkit.shell_exec(id='session_1', command='python hello.py')
print(output)

Interacting with Processes

You can manage long-running or interactive processes. Tip: shell_view returns only new output since the last call. Call it periodically to stream logs.

Writing to a Process
Killing a Process

You can write to a process’s standard input using shell_write_to_process. Start the process in non-blocking mode, then send input and read output.

# Start a python REPL in a new session
terminal_toolkit.shell_exec(id='interactive_session', command='python', block=False)

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

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

Forcibly terminate a running process using shell_kill_process.

# Start a long-running process
terminal_toolkit.shell_exec(id='long_process', command='sleep 100', block=False)

# Kill the process before it finishes
result = terminal_toolkit.shell_kill_process(id='long_process')
print(result)

Advanced Usage

Non-blocking Sessions and Timeouts

Blocking commands that exceed timeout are converted into background sessions. You can then view output or terminate them. This is useful for long tasks where you still want a quick response, but need to keep the process alive in the background.

# If this exceeds timeout, it becomes a background session automatically
output = terminal_toolkit.shell_exec(
    id='long_task',
    command='python long_running_job.py',
    block=True,
    timeout=5,
)
print(output)

# Later, check output or terminate
print(terminal_toolkit.shell_view(id='long_task'))
print(terminal_toolkit.shell_kill_process(id='long_task'))

Safe Mode Allowlist

When safe_mode=True, you can restrict execution to an explicit allowlist. This is helpful for production deployments where only specific commands should be allowed.

terminal_toolkit = TerminalToolkit(
    safe_mode=True,
    allowed_commands=["ls", "cat", "python", "pip", "uv"]
)

Docker Backend

Run commands inside a pre-existing Docker container for stronger isolation. The container must already exist and be running.

terminal_toolkit = TerminalToolkit(
    use_docker_backend=True,
    docker_container_name="camel-runtime",
    working_directory="/workspace",
)

Environment and Dependencies

Clone the current environment or preinstall dependencies into the sandboxed workspace. Use this to ensure tools like python, pip, or uv are available inside the sandboxed workspace.

terminal_toolkit = TerminalToolkit(
    working_directory="./workspace",
    clone_current_env=True,
    install_dependencies=["python-pptx", "pandas"],
)

Write Files Directly

Use shell_write_content_to_file to write large files without shell escaping issues. Relative paths are resolved under working_directory. In safe mode, the path must stay inside that directory.

content = "line1\nline2\nline3\n"
result = terminal_toolkit.shell_write_content_to_file(
    content=content,
    file_path="notes/demo.txt",
)
print(result)

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 shell_ask_user_for_help to request human intervention. This call blocks and waits for a human response in the console, then returns the user’s input or the resulting command output.

Asking for Human Help

# The agent is stuck, so it asks for help in 'session_1'
help_result = terminal_toolkit.shell_ask_user_for_help(
    id='session_1',
    prompt="The tool is asking for a filename. Please type 'config.json'.",
)

# The script will now pause and wait for the user to type a response
# in the console. It will then resume with the user's input.
print(help_result)

References

camel/toolkits/terminal_toolkit/terminal_toolkit.py
examples/toolkits/terminal_toolkit.py
examples/runtimes/shared_runtime_multi_toolkit.py

Get Started

Key Modules

Awesome Toolkits

CAMEL with MCP

Cookbooks

Terminal Toolkit

Secure Sandboxed Execution

Multi-Session Management

Virtual Environment Management

Human-in-the-Loop

Initialization

Usage Examples

Executing Commands

Interacting with Processes

Advanced Usage

Non-blocking Sessions and Timeouts

Safe Mode Allowlist

Docker Backend

Environment and Dependencies

Write Files Directly

Safe Mode

Example of a Blocked Command

Human-in-the-Loop

Asking for Human Help

References

Secure Sandboxed Execution

Multi-Session Management

Virtual Environment Management

Human-in-the-Loop

​Initialization

​Usage Examples

​Executing Commands

​Interacting with Processes

​Advanced Usage

​Non-blocking Sessions and Timeouts

​Safe Mode Allowlist

​Docker Backend

​Environment and Dependencies

​Write Files Directly

​Safe Mode

Example of a Blocked Command

​Human-in-the-Loop

Asking for Human Help

​References

Initialization

Usage Examples

Executing Commands

Interacting with Processes

Advanced Usage

Non-blocking Sessions and Timeouts

Safe Mode Allowlist

Docker Backend

Environment and Dependencies

Write Files Directly

Safe Mode

Human-in-the-Loop

References