This server provides a security-hardened way for AI models to execute a limited, allowlisted set of terminal commands within a sandboxed environment.
run_command: Safe execution of allowlisted commands with optional cwd jailed to a configured root.
explain_command: Dry-run that returns the policy verdict without executing the command.
Structured response: Both return a CommandResult with ok, code (ResultCode like OK, POLICY_DENIED, TIMEOUT, CWD_ESCAPE, AUDIT_UNAVAILABLE), stdout, stderr, exit_code, duration_ms, and policy_reason.
Policy enforcement: Deny-by-default; explicit allowlists, denylists, and argument-specific denials (deny_args).
Sandboxing: No shell execution (preventing metacharacter injection), directory jail with escape prevention, time and output limits, environment scrubbing (only PATH, HOME, LANG).
Secrets redaction: Automatic redaction of common secret patterns with [REDACTED:<kind>] markers.
Auditing: Append-only audit trail with fail‑closed mechanism ensuring no unlogged execution.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@hardened-terminal-mcp list files in the current directory"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A security-hardened MCP server that lets an AI model run a small, explicitly allowlisted set of terminal commands — safely.
Giving a model raw shell access is dangerous: one crafted string can chain commands, read secrets, or escape the working directory. This server turns "let the model run commands" into a bounded, auditable operation instead of an open door. Every command is checked against a deny-by-default policy, run with no shell, jailed to one directory, time- and output-bounded, and logged to an append-only audit trail before it is allowed to run.
Related MCP server: Shell-MCP
Real output, captured from a jail with ls, cat, echo allowlisted and rm denied:
>>> explain_command("ls -la")
{
"ok": true,
"code": "OK",
"stdout": "",
"stderr": "",
"exit_code": null,
"duration_ms": 0,
"policy_reason": "command 'ls' is allowed"
}
>>> run_command("ls -la")
{
"ok": true,
"code": "OK",
"stdout": "total 44\ndrwxrwxr-x 2 asaad asaad 4096 Jul 30 18:36 .\ndrwxrwxrwt 24 root root 36864 Jul 30 18:36 ..\n",
"stderr": "",
"exit_code": 0,
"duration_ms": 4,
"policy_reason": "command 'ls' is allowed"
}
>>> run_command("rm -rf /")
{
"ok": false,
"code": "POLICY_DENIED",
"stdout": "",
"stderr": "",
"exit_code": null,
"duration_ms": 0,
"policy_reason": "command 'rm' is on the denylist"
}
>>> run_command("cat /etc/passwd", cwd="/etc")
{
"ok": false,
"code": "CWD_ESCAPE",
"stdout": "",
"stderr": "",
"exit_code": null,
"duration_ms": 0,
"policy_reason": "cwd escapes jail root: '/etc'"
}Requires Python 3.12+. Install with uv:
uv syncWrite a minimal policy.toml:
jail_root = "/srv/htmcp/sandbox" # commands are jailed here; REQUIRED
[allowlist]
commands = ["ls", "cat", "echo"]
[denylist]
commands = ["rm"]Register it with your MCP client:
{
"mcpServers": {
"hardened-terminal": {
"command": "uv",
"args": ["run", "hardened-terminal-mcp"],
"env": {
"HTMCP_JAIL_ROOT": "/srv/htmcp/sandbox",
"HTMCP_POLICY_FILE": "/srv/htmcp/policy.toml"
}
}
}
}flowchart LR
client([MCP client / model]) -->|run_command / explain_command| server[server.py]
server -->|explain| policy[policy engine<br/>deny-by-default, no shell]
policy -->|deny| result[CommandResult envelope]
policy -->|allow| jail{cwd inside jail?}
jail -->|escape| result
jail -->|ok| exec[executor<br/>shell=False, env scrub, timeout, cap]
exec --> redact[redaction<br/>before truncation]
redact --> result
result --> client
server -. attempt record<br/>BEFORE execution .-> audit[(append-only<br/>audit.jsonl)]
server -. outcome record<br/>AFTER execution .-> auditThe audit log is a side branch, not on the return path: the attempt record is
written before the executor runs, and the outcome record after. explain_command
follows the same path with execution skipped.
Guarantee | How it is enforced |
Deny by default | Command name must be on the allowlist; denylist always wins; a name not listed is denied |
No shell |
|
cwd jail | Requested cwd is resolved (normalising |
Timeout | Wall-clock |
Output caps | stdout/stderr byte-capped with a truncation marker; redaction runs before the cap so a secret can't be split |
Env scrub | Child gets only an allowlisted env ( |
Audit fail-closed | An attempt record is written before execution; if it can't be written under fail-closed, the command does not run ( |
Redaction | Secrets in output and in audit |
Does not defend against (out of scope by design):
A dangerous command you allowlisted. If you allow an interpreter or a
shell-like tool (bash, python, sh, find -exec, awk, env, …), the
model can do anything that tool can. Policy strength is entirely the operator's
allowlist.
Kernel / sandbox escapes. The jail is a path-containment check, not a kernel sandbox — there are no namespaces, cgroups, or seccomp. A local-privilege or kernel exploit reachable from an allowlisted binary is not contained.
Host access to the audit log. The trail is tamper-evident to the server,
not tamper-proof. Anyone with filesystem access to audit.jsonl can read,
alter, or delete it.
Redaction completeness. Redaction is pattern-based and best-effort; a novel secret format the patterns don't recognise can pass through.
Many quick MCP servers wrap subprocess.run(cmd, shell=True). That is convenient
and unsafe. This table is factual, not a claim of perfect security.
Concern |
| hardened-terminal-mcp |
Command surface | Any command the shell can parse | Only allowlisted names; denylist wins |
Shell metacharacters | Interpreted ( | Rejected before evaluation; no shell |
Working directory | Wherever the process is | Pinned to a required jail root; escapes refused |
Environment | Full parent env (secrets included) | Scrubbed to |
Secrets in output/args | Passed through | Pattern-redacted before return and before audit |
Auditability | None by default | Append-only JSONL; fail-closed by default |
Both tools return a CommandResult:
CommandResult {
ok: bool # true only for OK / OUTPUT_TRUNCATED
code: ResultCode # see taxonomy below
stdout: str # redacted; empty for explain / non-executing paths
stderr: str # redacted
exit_code: int | null # process exit code; null when nothing ran
duration_ms: int
policy_reason: str | null # human-readable allow/deny reason
}run_command(command: str, cwd: str | None = None) — evaluate command
against policy and, if allowed, run it sandboxed. cwd (if given) must resolve
inside the jail root, else CWD_ESCAPE. Every call is audited.
explain_command(command: str) — dry run: return the policy verdict only,
with empty stdout/stderr and exit_code = null. It never reaches the
executor.
Each code maps to exactly one condition.
Code | Meaning |
| Executed and returned ( |
| Denied by policy (list, arg rule, shell metacharacter, empty) |
| Command could not be parsed into an argv |
| Wall-clock timeout; the process was killed |
| Ran, but output hit the byte cap |
| Requested cwd escaped the jail root |
| Allowed command couldn't run (not found, permission, etc.) |
| Fail-closed: the audit record couldn't be written; not run |
| Unexpected server error; generic message only, no traceback |
Variable | Meaning | Default |
| Path to |
|
| Jail directory (required via this or | — (refuse if unset) |
| Audit trail path |
|
|
|
|
Env values override the file. Startup fails loudly on a missing/invalid policy, an unset or non-directory jail root, an invalid operator regex, or an audit log located inside the jail root.
# jail_root is REQUIRED (here or via HTMCP_JAIL_ROOT). Keep the audit log OUTSIDE it.
jail_root = "/srv/htmcp/sandbox"
audit_log = "/var/log/htmcp/audit.jsonl"
audit_fail_mode = "closed" # "closed" = don't run if unloggable; "open" = run + warn
[allowlist]
commands = ["ls", "cat", "echo", "git"]
[denylist]
commands = ["rm", "shutdown", "curl"] # denylist always wins
# Allowed in general, denied for specific argument patterns (order-independent).
[[rules]]
command = "git"
deny_args = ["push --force", "push -f"]
reason = "force-push rewrites shared history"
[redaction]
enabled = true
entropy_fallback = false # noisy on hashes/UUIDs/base64 — see Caveats
extra_patterns = [] # e.g. [{ name = "internal_id", regex = "INT-[0-9]{8}" }]This is a hardening layer, not a vault. Read these before deploying.
Redaction is best-effort, not a guarantee. It is regex/pattern-based. It catches common secret shapes (see the pattern list) but a novel or unusual format will pass through. Do not rely on it as your only secret control, and do not allowlist commands that print secrets you can't afford to leak.
The audit log is tamper-evident, not tamper-proof. The server writes
append-only with per-record flush+fsync, so it won't lose records to a crash.
But anyone with host filesystem access can read, edit, or delete audit.jsonl.
Protect it with OS permissions and ship it off-host if you need integrity.
The jail is a path check, not a kernel sandbox. Containment is a resolve +
is_relative_to check on the cwd. There are no namespaces, cgroups, or seccomp.
A process that can escape via a kernel bug or an allowlisted escape hatch is not
contained. For stronger isolation, run the whole server inside a container/VM.
Policy strength is entirely the operator's allowlist. The engine faithfully
enforces what you configure. Allow bash, python, env, find, or any tool
with -exec/eval semantics and you have handed over a general-purpose shell.
Keep the allowlist minimal and argument-scoped.
uv run pytest84 tests, isolated with tmp_path (they never touch a real policy or audit log):
test_policy.py (22) — deny-by-default, denylist-wins, case/spacing bypasses,
metacharacter rejection, argument rules
test_executor.py (7) — shell=False, timeout+kill, output cap, env scrub,
cwd validation, refused commands
test_server.py (16) — one test per ResultCode, both tools, envelope shape,
cwd escapes, explain-never-executes
test_audit.py (15) — attempt/outcome records, fail-closed vs fail-open,
schema, no output content, redacted command_raw/argv, jail-root rules
test_redact.py (23) — one case per pattern, no-false-positives (paths,
SHAs, UUIDs, cp -p), entropy on/off, redaction before truncation
test_smoke.py (1) — import/health smoke
CI runs the suite plus gitleaks on every
push and pull request (see .github/workflows/ci.yml).
Asaad-Suliman/MCP-file-organizer — a companion safe-MCP-server project applying the same deny-by-default, audited, least-privilege approach to filesystem operations.
Asaad-Suliman/safe-mcp-suite — this server's successor: the terminal server and the file organizer rebuilt together on one shared, deny-by-default safety core.
MIT — see LICENSE.
Dry run: return the policy verdict without executing anything.
stdout/stderr are always empty and exit_code is always None. This function does not reference the executor at all, so it is structurally impossible for it to run a command (see test_explain_command_cannot_execute).
| Name | Required | Description | Default |
|---|---|---|---|
| command | Yes |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| code | Yes | |
| stderr | No | |
| stdout | No | |
| exit_code | No | |
| duration_ms | No | |
| policy_reason | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully bears the burden and explicitly states that stdout/stderr are empty, exit_code is None, and it is structurally impossible to run a command, citing a test for evidence.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the key purpose, and each sentence adds essential information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists and the tool has one parameter, the description covers behavior, safety guarantees, and differentiation from the sibling, providing complete context for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema coverage is 0%, and the description does not add any meaning to the 'command' parameter beyond its type. It does not explain its format, constraints, or relationship to the tool's purpose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is a dry run that returns the policy verdict without executing anything, and it distinguishes itself from the likely sibling tool 'run_command' by emphasizing that no execution occurs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for checking policy without execution, and the sibling 'run_command' provides a clear alternative. However, it does not explicitly state when to use it or when not to, relying on the contrast with the sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Evaluate command against policy and, if allowed, run it sandboxed.
Denied commands are never executed. cwd (if given) must resolve inside
the jail root; any traversal/symlink/absolute escape returns CWD_ESCAPE.
Any unexpected error becomes INTERNAL_ERROR with a generic message.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | ||
| command | Yes |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| code | Yes | |
| stderr | No | |
| stdout | No | |
| exit_code | No | |
| duration_ms | No | |
| policy_reason | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses policy evaluation, sandboxed execution, denied commands not run, cwd must resolve inside jail root or return CWD_ESCAPE, and unexpected errors become INTERNAL_ERROR. This is thorough behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loading the main action and constraints. Every sentence adds value without redundancy. It is efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (command execution, two parameters, no annotations, but with output schema as per context), the description covers policy, sandboxing, cwd constraints, and error scenarios. The output schema exists, so return value explanation is not required. Completeness is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must add meaning. It explains that 'command' is evaluated and run after policy check, and 'cwd' must resolve inside jail root with specific escape handling. This adds significant context beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool evaluates command against policy and runs it sandboxed if allowed. It uses specific verbs ('evaluate', 'run') and identifies the resource ('command'). The sibling tool 'explain_command' provides contrast, making the purpose distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context: use when you want to execute a command sandboxed after policy check. It details denied commands are never executed and cwd constraints. However, it does not explicitly state when not to use this tool or directly name alternatives beyond the sibling name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0explain_commandrun_commandScored across 2 tools
The two tools have clearly distinct purposes: one executes commands after policy evaluation, the other only simulates to show the policy verdict. Their descriptions explicitly highlight the difference, making it impossible to confuse them.
Both tools follow a consistent verb_noun pattern with snake_case (run_command, explain_command), which is clear and predictable.
With only 2 tools, the surface is very small. While it might suffice for a minimal sandboxed terminal, the server's name suggests broader functionality, so the count feels slightly lacking but not severely mismatched.
The tools cover execution and policy checking, but there is no ability to manage policies (e.g., view, edit, list) or handle command history. This leaves notable gaps that agents would need to work around.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Security scanner for MCP servers. Detect vulnerabilities, prompt injection, and tool poisoning.
An MCP server for deep research or task groups
MCP server for Superserve sandboxes: create, exec, and manage Firecracker microVMs
