README
¶
rshell - A Restricted Shell for AI Agents
A restricted shell interpreter for Go. Designed for AI agents that need to run shell commands safely.
Install
go get github.com/DataDog/rshell
Quick Start
package main
import (
"context"
"os"
"strings"
"github.com/DataDog/rshell/interp"
"mvdan.cc/sh/v3/syntax"
)
func main() {
script := `echo "hello from rshell"`
prog, _ := syntax.NewParser().Parse(strings.NewReader(script), "")
runner, _ := interp.New(
interp.StdIO(nil, os.Stdout, os.Stderr),
)
defer runner.Close()
runner.Run(context.Background(), prog)
}
Security Model
Every access path is default-deny:
| Resource | Default | Opt-in |
|---|---|---|
| External commands | Blocked (exit code 127) | Provide an ExecHandler |
| Filesystem access | Blocked | Configure AllowedPaths with directory list |
| Environment variables | Empty (no host env inherited) | Pass variables via the Env option |
| Output redirections | Blocked at validation (exit code 2) | Not configurable — always blocked |
AllowedPaths restricts all file operations to specified directories using Go's os.Root API (openat syscalls), making it immune to symlink traversal, TOCTOU races, and .. escape attacks.
Shell Features
See SHELL_FEATURES.md for the complete list of supported and blocked features.
Platform Support
Linux, macOS, and Windows.
Testing
900+ YAML-driven test scenarios cover builtins, shell features, and security restrictions.
tests/scenarios/
├── cmd/ # builtin command tests (echo, cat, grep, head, tail, uniq, wc, ...)
└── shell/ # shell feature tests (pipes, variables, control flow, ...)
By default, each scenario is executed twice: once in rshell and once in a real bash shell, ensuring output parity with POSIX behavior. Scenarios that test rshell-specific restrictions (blocked commands, readonly enforcement, etc.) opt out of the bash comparison.
go test ./...
Publishing Changes
After merging changes to main create a release by:
-
Navigate to the Releases page
-
Click "Draft a new release"
-
You can "Select a tag" using the dropdown or "Create a new tag"
When creating a new tag, make sure to include the
vprefix. For example, if the last release was v0.1.29, your release should be v0.1.30. -
The release title should be the same as the version tag
-
Use "Generate release notes" to fill in the release description
-
Click "Publish release"
This will create a git tag that can now be referenced in other repos. This will trigger go-releaser that will add installable artifacts to the release.
License
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
rshell
command
Package main provides the rshell CLI — a restricted shell interpreter.
|
Package main provides the rshell CLI — a restricted shell interpreter. |
|
Package interp implements a restricted shell interpreter designed for safe, sandboxed execution.
|
Package interp implements a restricted shell interpreter designed for safe, sandboxed execution. |
|
builtins/break
Package breakcmd implements the break builtin command.
|
Package breakcmd implements the break builtin command. |
|
builtins/cat
Package cat implements the cat builtin command.
|
Package cat implements the cat builtin command. |
|
builtins/continue
Package continuecmd implements the continue builtin command.
|
Package continuecmd implements the continue builtin command. |
|
builtins/cut
Package cut implements the cut builtin command.
|
Package cut implements the cut builtin command. |
|
builtins/echo
Package echo implements the echo builtin command.
|
Package echo implements the echo builtin command. |
|
builtins/exit
Package exit implements the exit builtin command.
|
Package exit implements the exit builtin command. |
|
builtins/false
Package falsecmd implements the false builtin command.
|
Package falsecmd implements the false builtin command. |
|
builtins/grep
Package grep implements the grep builtin command.
|
Package grep implements the grep builtin command. |
|
builtins/head
Package head implements the head builtin command.
|
Package head implements the head builtin command. |
|
builtins/ls
Package ls implements the ls builtin command.
|
Package ls implements the ls builtin command. |
|
builtins/strings_cmd
Package strings_cmd implements the strings builtin command.
|
Package strings_cmd implements the strings builtin command. |
|
builtins/tail
Package tail implements the tail builtin command.
|
Package tail implements the tail builtin command. |
|
builtins/testcmd
Package testcmd implements the POSIX test and [ builtin commands.
|
Package testcmd implements the POSIX test and [ builtin commands. |
|
builtins/testutil
Package testutil provides shared test helpers for builtin command tests.
|
Package testutil provides shared test helpers for builtin command tests. |
|
builtins/true
Package truecmd implements the true builtin command.
|
Package truecmd implements the true builtin command. |
|
builtins/uniq
Package uniq implements the uniq builtin command.
|
Package uniq implements the uniq builtin command. |
|
builtins/wc
Package wc implements the wc builtin command.
|
Package wc implements the wc builtin command. |