execute(
Execute a shell command directly on the host system.
Commands are executed directly on your host system
using subprocess.Popen() with shell=True. There is no sandboxing,
isolation, or security restrictions. The command runs with
your user's full permissions and can:
virtual_mode)Always use Human-in-the-Loop (HITL) middleware when using this method.
The command is executed using the system shell (/bin/sh or equivalent)
with the working directory set to the backend's root_dir.
Stdout and stderr are combined into a single output stream.
On POSIX systems, each command starts in a new session without sharing
the parent's controlling terminal. A timeout, an interruption such as
KeyboardInterrupt, and async cancellation all terminate the command's
process group with SIGKILL, then wait briefly for the shell process to
exit. A descendant that makes its own session or process group, for
example with setsid, leaves that group and is not killed. nohup alone
does not change the process group or protect against SIGKILL.
Async cancellation cleanup applies only when execute is not overridden.
On Windows, commands do not start in a new process group. Cleanup terminates only the direct shell process, so descendants may continue running after a timeout, an interruption, or async cancellation. A descendant that inherits the output handles also keeps the pipes open, so the command waits for the full timeout even after the shell itself exits.
Shell command string to execute.
Examples: "python script.py", "ls -la", "grep pattern file.txt"
Security: This string is passed directly to the shell. Agents can execute arbitrary commands including pipes, redirects, command substitution, etc.
Maximum time in seconds to wait for this command.
Overrides the default timeout set at init.
If None, uses the default.