Skip to content

Added documentation for the node tool shell #749

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
AditM99 wants to merge 1 commit into from
Closed

Added documentation for the node tool shell #749

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 49 additions & 0 deletions nodes/src/nodes/tool_shell/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
---
title: Shell
date: 2026-04-30
sidebar_position: 1
---

<head>
<title>Shell - RocketRide Documentation</title>
</head>

## What it does

Tool node that runs a shell command on the host and returns stdout, stderr, and exit code. Useful for build scripts, package managers, file operations, and host-installed git.

## As a tool

When connected to an agent, exposes one function under the configured server name (default: `shell`):

| Function | Description |
| --------------- | ------------------------------------------------------------ |
| `shell.execute` | Run a shell command and return stdout, stderr, and exit code |

**`shell.execute` parameters:**

| Parameter | Required | Description |
| ------------- | -------- | ----------------------------------------------------------- |
| `command` | yes | Shell command to execute (interpreted by the host shell) |
| `working_dir` | no | Working directory for this call. Overrides the node default |
| `env` | no | Object of environment variables to inject for this call |
| `timeout` | no | Per-call timeout in seconds (capped by node configuration) |

`exit_code` is the process return code. `-1` indicates a timeout kill; `127` indicates the host shell could not be launched.

## Configuration

| Field | Default | Description |
| ----------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------- |
| Default working directory | host CWD | Working directory used when the agent does not provide one |
| Execution timeout (seconds) | `30` | Max seconds a command may run (max 1800). On timeout the entire process tree is killed |
| Max output size (bytes) | `1048576` | Per-stream cap on stdout and stderr; output beyond this is streamed and discarded so memory stays bounded |
| Allow agent-supplied env vars | off | Whether the agent may inject env vars per call. Off by default — `LD_PRELOAD`/`PATH`/`NODE_OPTIONS` can redirect execution |
| Environment variables | — | Variables injected into every command. Override agent-supplied vars of the same name |
| Command allowlist | — | Regex patterns. If non-empty, the full command must match at least one (`re.fullmatch`). Use `.*` for substring matches |

Comment on lines +23 to +44
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot May 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick | 🔵 Trivial | ⚡ Quick win

Add one concrete request/response + allowlist example.

A minimal example for shell.execute payload and allowlist patterns would make this safer and faster to adopt.

✍️ Suggested doc addition 
 ## As a tool
@@
 `exit_code` is the process return code. `-1` indicates a timeout kill; `127` indicates the host shell could not be launched.
+
+**Example call:**
+
+```json
+{
+  "command": "npm ci && npm test",
+  "working_dir": "/workspace/app",
+  "env": { "NODE_ENV": "test" },
+  "timeout": 120
+}
+```
+
+**Example response shape:**
+
+```json
+{
+  "stdout": "...",
+  "stderr": "",
+  "exit_code": 0
+}
+```
@@
 | Command allowlist             | —         | Regex patterns. If non-empty, the full command must match at least one (`re.fullmatch`). Use `.*` for substring matches    |
+
+Examples:
+- `^npm\\s+(ci|test)(\\s+.*)?$` allows npm ci/test commands
+- `^python\\s+scripts/[-\\w./]+$` allows script execution under `scripts/`
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@nodes/src/nodes/tool_shell/README.md` around lines 23 - 44, The README's
shell.execute section needs a concrete request/response example and allowlist
patterns to show safe usage: add a minimal JSON request payload (fields:
command, working_dir, env, timeout) and the example response shape (stdout,
stderr, exit_code) under the "shell.execute parameters" section, and add sample
allowlist regexes (e.g. ^npm\\s+(ci|test)(\\s+.*)?$,
^python\\s+scripts/[-\\w./]+$ and a note about using .* for substring matches)
to the "Command allowlist" description so readers can copy/paste a working
example; update references to shell.execute and the Command allowlist text
accordingly.

## Notes

- Commands run directly on the host with the privileges of the running process — no sandbox. Use the allowlist to restrict commands and avoid deploying in untrusted environments.
- An allowlist whose patterns all fail to compile is rejected at startup (fail-closed); individual invalid patterns are dropped with a warning.
- For portable git operations that don't require git on the host, prefer the Git node.
Loading