Run Command

Benchmarked against: Anthropic — Bash tool / Code execution tool Tool: ubi_run_command Server: Local UBI MCP Security: Whitelist-validated, dangerous patterns blocked

The ubi_run_command tool provides sandboxed shell execution for agents. It allows running system commands within controlled boundaries — validated against a whitelist, with dangerous patterns blocked and execution timeouts enforced.

---

When to use

Use case	Example
Version checks	pip show langgraph, node --version
Git operations	git status, git log --oneline -5
File discovery	ls -la /path/to/dir, find . -name "*.py"
Process management	`ps aux
Build/test commands	npm run build, pytest tests/
System diagnostics	df -h, uptime

---

API reference

ubi_run_command

Execute a shell command in an allowed directory.

Parameters:

Parameter	Type	Required	Default	Description
command	string	Yes	—	Shell command to run
working_dir	string	No	First allowed dir	Working directory (must be in allowed list)
timeout	number	No	30	Max seconds (max 120)

Response:

{
  "stdout": "langgraph 1.0.8\n...",
  "stderr": "",
  "exit_code": 0,
  "execution_time_ms": 342
}

Error response:

{
  "error": "Command blocked: contains dangerous pattern 'rm -rf'",
  "blocked_pattern": "rm -rf"
}

---

Security model

Allowed directories

Commands can only execute within designated working directories. Attempting to run commands outside these directories returns an error.

Typical allowed directories:

• /Users/xy2024air15/Documents/SuperPortia — Main project
• /Users/xy2024air15/Documents/SuperPortia/ub — UB system
• Other project-specific directories as configured

Blocked patterns

The following dangerous patterns are automatically blocked:

Pattern	Why blocked
rm -rf	Recursive forced deletion — catastrophic data loss
sudo	Privilege escalation
chmod 777	Overly permissive file permissions
> /dev/	Writing to device files
mkfs	Filesystem formatting
dd if=	Low-level disk operations
:(){ :|:& };:	Fork bomb
curl | sh	Remote code execution

Whitelist validation

Commands are validated against an allowed command whitelist. Common safe commands are permitted; unknown or dangerous commands are blocked. This provides defense-in-depth beyond just pattern blocking.

---

Examples

Check installed package versions

ubi_run_command(command="pip show langgraph | grep Version")

{
  "stdout": "Version: 1.0.8\n",
  "stderr": "",
  "exit_code": 0
}

Git status

ubi_run_command(
    command="git status --short",
    working_dir="/Users/xy2024air15/Documents/SuperPortia"
)

Run tests with timeout

ubi_run_command(
    command="pytest tests/test_mtaaa.py -v",
    working_dir="/Users/xy2024air15/Documents/SuperPortia/ub",
    timeout=60
)

Build check

ubi_run_command(
    command="npm run build 2>&1",
    working_dir="/Users/xy2024air15/Documents/SuperPortia/docs-site",
    timeout=120
)

---

Comparison with Claude Code's Bash tool

SuperPortia agents have access to both ubi_run_command (via Local UBI MCP) and the native Claude Code Bash tool:

Feature	ubi_run_command	Claude Code Bash
Security	Whitelist + pattern blocking	User permission prompt
Sandboxing	Restricted to allowed directories	Full system access (with permission)
Timeout	Max 120 seconds	Max 600 seconds
Output	JSON with exit code	Raw stdout/stderr
Availability	Via MCP (any agent)	Claude Code only
Use when	Automated tasks, dispatch workers	Interactive CLI sessions

Guidance: Use ubi_run_command for automated/dispatch contexts where security sandboxing is critical. Use the native Bash tool for interactive sessions where the Captain can approve commands.

---

Integration with dispatch engine

When a Work Order is dispatched with engine="claude", the dispatch worker uses ubi_run_command to execute shell operations. The sandboxing ensures that even if the dispatch prompt is malformed, dangerous commands cannot execute.

---

Related pages

Page	Relationship
MCP Tools Overview	Full tool catalog
File Tools	File read/write/edit operations
Computer Use	Browser-based automation alternative
Dispatch Engine	Uses run_command for Claude engine WOs