shell_exec

Runs the command in the session's persistent shell. cd and export carry over between calls. The shell starts in /workspace, and browser downloads are in ./downloads.

Inputs

sessionId is the id that session_create returned. The server keeps no default session. If that session is stopped, this tool resumes it first, as it was (a resume starts a machine again, and billing with it).

Example call

This is what an MCP client sends. You do not write it yourself: ask the model in plain words and it calls the tool.

{  "name": "shell_exec",  "arguments": {    "sessionId": "6c1f3c9e-1d2a-4f67-9b0e-1b2c3d4e5f60",    "command": "python3 -c 'print(6*7)'"  }}

What it returns

The command's output (stdout, then stderr) and its exit code.

42[exit code 0]

When a call fails, the result is marked as an error. Its text starts with the API’s error code, such as unauthorized or session_not_running, followed by its message.

Annotations

The server tells every client what this tool does to the world, so a client can decide what to ask you about before it runs.

Good to know

• Needs a session with a shell. Without one the call answers shell_disabled.
• A command stopped by its time limit ends with [exit code timeout].
• For a job that takes longer than the time limit, start it in the background with nohup … > job.log 2>&1 &, which returns at once, and read job.log later with files_read or tail job.log. A background job stops when the session stops.

The same thing with the API