API Overview

gbash exposes a Go library for embedding a deterministic bash runtime in your application. The API is designed around a small set of core types and a functional options pattern for configuration.

Core Types

Type	Description
`Runtime`	The top-level sandbox runner. Created with `gbash.New(opts...)`.
`Session`	A persistent sandbox with shared filesystem state across executions. Created with `Runtime.NewSession(ctx)`.
`ExecutionRequest`	Input to `Runtime.Run` or `Session.Exec`. Contains the script to execute.
`ExecutionResult`	Output from an execution: exit code, stdout, stderr, timing, and optional trace events.

Package Hierarchy

github.com/ewhauser/gbash           Core runtime, sessions, and option helpers
github.com/ewhauser/gbash/commands   Command interface, registry, and invocation types
github.com/ewhauser/gbash/server     Shared Unix-socket JSON-RPC server mode for persistent sessions
github.com/ewhauser/gbash/fs         Filesystem abstractions (memory, host overlay, read-write)
github.com/ewhauser/gbash/network    HTTP client and allowlist configuration for curl
github.com/ewhauser/gbash/policy     Path access checks and execution limits
github.com/ewhauser/gbash/trace      Structured trace events used when tracing is enabled
github.com/ewhauser/gbash/cli        Shared CLI frontend for building wrapper binaries

Quick Example

package main
 
import (
	"context"
	"fmt"
 
	"github.com/ewhauser/gbash"
)
 
func main() {
	gb, err := gbash.New()
	if err != nil {
		panic(err)
	}
 
	result, err := gb.Run(context.Background(), &gbash.ExecutionRequest{
		Script: "echo hello world\npwd\n",
	})
	if err != nil {
		panic(err)
	}
 
	fmt.Printf("exit=%d\n", result.ExitCode)
	fmt.Print(result.Stdout)
}

exit=0
hello world
/home/agent

Next Steps

Runtime -- creating and configuring runtimes
Server -- hosting persistent sessions over a Unix-socket JSON-RPC endpoint
Tracing and Logging -- structured traces and lifecycle log callbacks
Sessions -- persistent sandbox state across executions
Custom Commands -- extending the command registry
WebAssembly -- running gbash in the browser or Node.js