---
title: Agent Restricted Shell (rshell)
description: >-
  Learn how the Agent Restricted Shell (rshell) executes safe, read-only
  commands on hosts through the Datadog MCP Server.
breadcrumbs: Docs > Agent > Agent Guides > Agent Restricted Shell (rshell)
---

# Agent Restricted Shell (rshell)

## Overview{% #overview %}

The Agent Restricted Shell (rshell) is the command execution layer behind the [`remote-actions` toolset](https://docs.datadoghq.com/mcp_server/tools.md#remote-actions) in the Datadog MCP server. When an AI system or developer CLI calls [`datadog_remote_action_restricted_shell_run_command`](https://docs.datadoghq.com/mcp_server/tools.md#remote-actions), rshell is what runs on the host.

rshell is an open source, POSIX-compatible shell interpreter written in Go and embedded in the Private Action Runner (PAR) process. It is not a real host shell. There is no `bash`, `sh`, or `zsh` process spawned. Every command is a purpose-built Go implementation with explicit safety constraints. You can view the source on [GitHub](https://github.com/DataDog/rshell).

## How it works{% #how-it-works %}

When a command is invoked:

1. The Datadog backend receives the request from the MCP client.
1. The request is forwarded to the PAR running on the target host.
1. rshell, embedded in the PAR process, executes the command as a Go builtin.
1. Output is returned to the backend and surfaced to the MCP client.

The PAR is a customer-installed process. It handles the secure channel between the Datadog backend and the host. rshell runs inside it and never opens a separate shell process on the host.

## Why it is safe{% #why-it-is-safe %}

rshell enforces the following constraints by design:

- **No write access.** rshell has no commands that write to the file system. The only output redirect allowed is `>/dev/null`. Files cannot be created, modified, or deleted.
- **No external binary execution.** rshell cannot call binaries on the host. Every command is a Go builtin inside the PAR process. External commands are blocked unless an explicit ExecHandler is configured.
- **No network egress.** Network diagnostic commands (`ping`, `ss`, `ip`) are read-only. `ping` blocks flood mode, broadcast, and multicast addresses. Background execution (`cmd &`) is not supported.
- **Path allowlisting.** All file access is restricted to directories configured in `AllowedPaths`. You can further restrict this in your Agent configuration.
- **Backend-controlled command allowlist.** The permitted command set is controlled per Agent version from the Datadog backend, using a `rshell:` namespace prefix (for example, `rshell:cat`). Individual commands have a killswitch that can be disabled immediately if a security issue is discovered.
- **Empty environment by default.** No parent environment variables are inherited. rshell starts with an empty environment unless variables are explicitly passed by the caller.

## Supported commands{% #supported-commands %}

The following commands and shell features are available as of Agent 7.79.

### File inspection{% #file-inspection %}

| Command   | Description                                                                                                        |
| --------- | ------------------------------------------------------------------------------------------------------------------ |
| `cat`     | Print file contents; supports line numbering and non-printing character display                                    |
| `ls`      | List directory contents; supports pagination using `--offset` and `--limit`                                        |
| `head`    | Print the first N lines or bytes of a file (default: 10 lines)                                                     |
| `tail`    | Print the last N lines or bytes of a file (default: 10 lines); supports `+N` offset mode; `-f` (follow) is blocked |
| `find`    | Search for files by name, type, size, permissions, and modification time; `-delete` and `-regex` are blocked       |
| `strings` | Print printable character sequences in files (default minimum length: 4)                                           |

### Text processing{% #text-processing %}

| Command  | Description                                                                                               |
| -------- | --------------------------------------------------------------------------------------------------------- |
| `grep`   | Search for patterns; uses RE2 regex engine (linear-time, no backtracking)                                 |
| `sed`    | Filter and transform text; uses RE2 regex engine; `-i` (in-place edit) and `-f` (script file) are blocked |
| `cut`    | Extract fields or byte ranges from lines                                                                  |
| `tr`     | Translate, squeeze, or delete characters                                                                  |
| `sort`   | Sort lines; supports numeric, human-readable, and reverse sorting; `-o` (output to file) is blocked       |
| `uniq`   | Filter or report duplicate lines                                                                          |
| `wc`     | Count lines, words, bytes, characters, or max line length                                                 |
| `printf` | Format and print data to stdout                                                                           |

### Process and system inspection{% #process-and-system-inspection %}

| Command | Description                                                                         |
| ------- | ----------------------------------------------------------------------------------- |
| `ps`    | Report process status; `-e`/`-A` shows all processes; `-f` adds UID/PPID/start time |
| `uname` | Print system information (Linux only)                                               |

### Network diagnostics (read-only){% #network-diagnostics-read-only %}

| Command               | Description                                                                                           |
| --------------------- | ----------------------------------------------------------------------------------------------------- |
| `ping`                | Send ICMP echo requests and report round-trip statistics; flood, broadcast, and multicast are blocked |
| `ss`                  | Display network socket statistics; `-p` (process disclosure) and `-K` (kill) are blocked              |
| `ip addr` / `ip link` | Show network interface addresses and link-layer information                                           |
| `ip route`            | Show IPv4 routing table or resolve a route for a given address (Linux only)                           |

### Shell utilities{% #shell-utilities %}

| Command          | Description                                                                                     |
| ---------------- | ----------------------------------------------------------------------------------------------- |
| `echo`           | Write arguments to stdout                                                                       |
| `test` / `[ ]`   | Evaluate conditional expressions (file tests, string and integer comparison, logical operators) |
| `help`           | Display supported features and available commands                                               |
| `true` / `false` | Return exit code 0 or 1                                                                         |
| `exit`           | Exit the shell with a given status code                                                         |

## Supported shell features{% #supported-shell-features %}

### Control flow{% #control-flow %}

- `for VAR in WORDS; do CMDS; done`
- `if` / `elif` / `else`
- `break` and `continue` for loop control
- `&&` and `||` short-circuit lists
- `!` negation
- `{ CMDS; }` brace groups
- `( CMDS )` subshells (variable changes do not propagate to the parent)

### Pipes and redirections{% #pipes-and-redirections %}

- `|` pipe stdout between commands
- `<` input redirection (read-only, within `AllowedPaths`)
- `>/dev/null`, `2>/dev/null`, `&>/dev/null` discard output
- `2>&1`, `>&2` file descriptor duplication between stdout and stderr
- `<<DELIM` and `<<-DELIM` heredocs

Write redirections to any target other than `/dev/null` are blocked.

### Variables and expansion{% #variables-and-expansion %}

- Variable assignment: `VAR=value`
- Variable expansion: `$VAR`, `${VAR}`
- `$?` last exit code
- Inline assignment: `VAR=value command` (scoped to that command)
- Command substitution: `$(cmd)` and ``cmd``; output capped at 1 MiB
- Single and double quotes
- Globbing: `*`, `?`, `[abc]`, `[a-z]`, `[!a]`
- Line continuation: `\` at end of line
- Comments: `# text`

Arithmetic expansion `$(( ))`, array assignment, append assignment (`+=`), and parameter expansion operations such as `${var:-default}` are not supported.

## Restrict file access{% #restrict-file-access %}

By default, file read commands are gated by a path allowlist managed from the Datadog backend. You can further restrict which paths and commands rshell can access in your Agent configuration.

```yaml
# datadog.yaml
private_action_runner:
  restricted_shell:
    allowed_paths:
      - /etc/datadog-agent/
      - /var/log/datadog/
    allowed_commands:
      - rshell:cat
      - rshell:grep
```

## Further reading{% #further-reading %}

- [Remote Actions toolset](https://docs.datadoghq.com/mcp_server/tools.md#remote-actions)
- [Datadog MCP Server setup](https://docs.datadoghq.com/mcp_server/setup.md)
- [Private Action Runner](https://docs.datadoghq.com/service_management/workflows/private_actions.md)