memsh

memsh

A virtual bash shell implemented in Go. memsh executes bash-like commands against an in-memory filesystem — the real OS filesystem is never touched, and external OS commands are blocked by default.

Shell parsing and interpretation is handled by mvdan.cc/sh/v3. Every command is a native Go plugin or WASM plugin — there is no reliance on host system binaries.

Features

• Sandboxed execution — external OS commands are blocked; only registered plugins can run
• In-memory filesystem — all file operations target afero.MemMapFs; nothing touches your disk
• Bash-like syntax — pipes, redirects (>, >>), &&, ;, subshells, aliases
• 60+ built-in commands — file ops, text processing, archiving, networking, scripting, and more
• Combined short flags — -rf, -la, -jrc etc. work on all commands
• Scripting languages — Lua (gopher-lua), JavaScript (goja ES2020+), JSON/YAML (jq/yq), SQLite
• WASM plugin system — extend with WASI-compiled plugins (Python, Ruby, PHP runtimes)
• Native Go plugins — register custom commands via a simple Plugin interface
• Interactive REPL — tab completion, command history, .memshrc startup script
• HTTP server — expose the shell over HTTP with session-scoped virtual filesystems
• Library usage — embed memsh in Go programs for safe, sandboxed shell scripting

Installation

Homebrew

brew tap amjadjibon/memsh
brew install memsh

Go Install

go install github.com/amjadjibon/memsh@latest

Pre-built Binaries

Download pre-built binaries from the GitHub Releases page.

Linux (amd64):

curl -Lo memsh.tar.gz https://github.com/amjadjibon/memsh/releases/latest/download/memsh_linux_amd64.tar.gz
tar xzf memsh.tar.gz
sudo mv memsh /usr/local/bin/

macOS (Apple Silicon):

curl -Lo memsh.tar.gz https://github.com/amjadjibon/memsh/releases/latest/download/memsh_darwin_arm64.tar.gz
tar xzf memsh.tar.gz
sudo mv memsh /usr/local/bin/

macOS (Intel):

curl -Lo memsh.tar.gz https://github.com/amjadjibon/memsh/releases/latest/download/memsh_darwin_amd64.tar.gz
tar xzf memsh.tar.gz
sudo mv memsh /usr/local/bin/

Windows (amd64):

Download memsh_windows_amd64.zip, extract, and add memsh.exe to your PATH.

Build from Source

git clone https://github.com/amjadjibon/memsh.git
cd memsh
go build -o memsh .

Verify Installation

memsh --help

Quick Start

# Interactive REPL
memsh

# Run a script
memsh ./path/to/script.sh

# Pipe commands
echo "mkdir /tmp && echo hello > /tmp/f && cat /tmp/f" | memsh

# HTTP server
memsh serve
memsh serve --addr :3000 --session-ttl 1h --cors

Usage as a Library

package main

import (
    "bytes"
    "context"
    "fmt"
    "log"

    "github.com/amjadjibon/memsh/pkg/shell"
)

func main() {
    ctx := context.Background()

    var out bytes.Buffer
    sh, err := shell.New(shell.WithStdIO(nil, &out, &out))
    if err != nil {
        log.Fatal(err)
    }
    defer sh.Close()

    err = sh.Run(ctx, `
        mkdir -p /home/user/docs
        echo '{"name":"alice","role":"admin"}' > /home/user/docs/user.json
        jq -r .name /home/user/docs/user.json
    `)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Print(out.String()) // alice
}

Pre-seeding the Virtual Filesystem

fs := afero.NewMemMapFs()
afero.WriteFile(fs, "/config.yaml", []byte("host: localhost\nport: 8080\n"), 0644)

var out bytes.Buffer
sh, _ := shell.New(
    shell.WithFS(fs),
    shell.WithStdIO(nil, &out, &out),
)
sh.Run(ctx, "yq .host /config.yaml") // localhost

Commands

Plugin System

Native Go Plugins

Implement the Plugin interface from pkg/shell/plugins:

import (
    "github.com/amjadjibon/memsh/pkg/shell/plugins"
    "mvdan.cc/sh/v3/interp"
)

type HelloPlugin struct{}

func (HelloPlugin) Name() string        { return "hello" }
func (HelloPlugin) Description() string { return "greet the user" }
func (HelloPlugin) Usage() string       { return "hello [name]" }

func (HelloPlugin) Run(ctx context.Context, args []string) error {
    hc := interp.HandlerCtx(ctx)  // pipe-aware I/O — always use this
    sc := plugins.ShellCtx(ctx)   // virtual FS, cwd, ResolvePath, SetEnv, …
    fmt.Fprintf(hc.Stdout, "Hello from %s!\n", sc.Cwd)
    return nil
}

Register at shell creation time:

sh, _ := shell.New(shell.WithPlugin(HelloPlugin{}))

Or add to defaultNativePlugins() in pkg/shell/defaults.go to include it in every shell instance.

JSON Processing (jq)

echo '{"name":"alice","scores":[10,20,30]}' | jq .name          # "alice"
echo '{"name":"alice"}' | jq -r .name                           # alice (no quotes)
echo '{"items":[1,2,3]}' | jq '.items | length'                 # 3
jq -n '{generated: true}'                                        # null input
jq -rc .name data.json                                           # combined flags

YAML/JSON Processing (yq)

echo 'name: alice' | yq .name                                    # alice
echo 'name: alice' | yq -j .                                     # JSON output
printf 'items:\n  - a\n  - b\n' | yq '.items[0]'                # a
yq .host /config.yaml                                            # read from virtual FS
yq -jc . data.yaml                                               # compact JSON output

Lua Scripting

lua -e 'print("hello from lua")'
echo 'for i=1,3 do print(i) end' | lua
lua /script.lua

JavaScript Scripting

goja -e 'console.log("hello")'
echo 'console.log("test")' | goja
goja /script.js
goja -e 'const arr=[1,2,3]; console.log(arr.map(x=>x*2).join(","))'

WASM Plugins

WASM plugins are compiled with GOOS=wasip1 GOARCH=wasm. The virtual FS is mounted via WASI so file I/O goes directly into afero.MemMapFs.

go run . plugin install python   # Python 3.12.0 (~25 MB)
go run . plugin install ruby     # Ruby 3.2.2 slim (~8 MB)
go run . plugin install php      # PHP 8.2.6 slim (~6 MB)
go run . plugin install /path/to/plugin.wasm  # local file
go run . plugin list             # list installed plugins

Installed runtimes are stored in ~/.memsh/plugins/*.wasm.

Plugin Loading Priority

1. WithPlugin(p) or WithPluginBytes(name, wasm) options
2. Native Go plugins registered in defaultNativePlugins()
3. Embedded WASM from defaultPlugins map (currently empty)
4. /memsh/plugins/*.wasm in the virtual FS
5. ~/.memsh/plugins/*.wasm on the real OS filesystem

Options

HTTP Server

go run . serve                          # listen on :8080
go run . serve --addr :3000 --cors      # custom port with CORS
go run . serve --session-ttl 1h --timeout 30s

Sessions are always enabled. Send X-Session-ID: <id> on POST /run to persist the virtual filesystem across requests.

Configuration

~/.memsh/config.toml is loaded at startup (missing file = defaults):

[shell]
wasm = true          # set false to skip all WASM loading (faster startup)

[plugins]
wasm    = ["python"] # allowlist of ~/.memsh/plugins/*.wasm names; empty = load all
disable = ["wc"]     # exclude specific plugins by name (native or WASM)

Configuration files:

• ~/.memsh/config.toml — shell and plugin configuration
• ~/.memsh/.memshrc — startup script (sourced at REPL start and first HTTP session)
• ~/.memsh/history/ — per-session command history
• ~/.memsh/plugins/ — user-installed WASM plugins

Testing

go test ./...                        # full test suite
go test ./tests -v                   # integration tests verbose
go test ./tests -run TestJq -v       # single suite
go test ./pkg/shell/... -run TestName  # shell package tests

Development

# Build
make build

# Run tests
make test

# Run coverage report
make cover

# Lint
make lint

# Clean build artifacts
make clean

# View all available commands
make help

Creating a Release

The project uses GoReleaser for automated releases and Homebrew cask generation.

# 1. Test the release process (dry-run)
make release-dry-run TAG=v1.0.0

# 2. Create the actual release
make release TAG=v1.0.0

The make release command will:

1. Commit and push any uncommitted changes (prepares for release)
2. Clean the dist/ directory (removes old build artifacts)
3. Clean build artifacts (bin/ and *.wasm files)
4. Create and push a git tag
5. Build binaries for all platforms (Linux, macOS, Windows × AMD64, ARM64)
6. Create a GitHub Release with all binaries
7. Generate and push the Homebrew cask automatically via goreleaser to homebrew-memsh

After release, users can install via:

brew tap amjadjibon/memsh
brew install memsh

Note: Ensure GITHUB_TOKEN is set for goreleaser to create releases and push to repositories.

Requirements

• Go 1.26+

License

See LICENSE.