Runtime

The Runtime is the top-level entry point for executing bash scripts inside a sandbox. Create one with gbash.New, configure it with option functions, and call Run for one-shot execution.

Creating a Runtime

gb, err := gbash.New()

With no options, New returns a runtime with:

An isolated in-memory filesystem rooted at /home/agent
The built-in command registry
The default in-tree shell core
No network access

Option Functions

Pass options to New to customize the runtime:

gb, err := gbash.New(
	gbash.WithWorkspace("/path/to/project"),
	gbash.WithHTTPAccess("https://api.example.com/"),
	gbash.WithBaseEnv(map[string]string{"APP_ENV": "test"}),
)

Option	Description
`WithWorkspace(dir)`	Mount a host directory into the sandbox under a writable in-memory overlay. Sessions start in that directory.
`WithFileSystem(cfg)`	Replace the session filesystem configuration with a custom `FileSystemConfig`.
`WithHTTPAccess(prefixes...)`	Enable `curl` with a URL allowlist. Only the listed prefixes are reachable.
`WithNetwork(cfg)`	Full control over HTTP methods, timeouts, response size limits, and private-range blocking.
`WithNetworkClient(client)`	Inject a fully custom `network.Client` for `curl`.
`WithRegistry(registry)`	Replace the command registry visible inside the sandbox.
`WithWorkingDir(dir)`	Override the initial working directory for new sessions.
`WithBaseEnv(env)`	Replace the base environment inherited by each execution.
`WithPolicy(p)`	Replace the sandbox policy (path access, execution limits).
`WithTracing(cfg)`	Enable structured execution tracing. `TraceRedacted` is the recommended default.
`WithLogger(fn)`	Register top-level execution lifecycle logging callbacks.
`WithConfig(cfg)`	Apply a pre-assembled `Config` struct as a single option.

One-Shot Execution

Runtime.Run creates a fresh session, executes the script, and returns the result:

result, err := gb.Run(ctx, &gbash.ExecutionRequest{
	Script: "ls -la /home/agent\necho done",
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(result.Stdout)

Each call to Run starts with a clean filesystem. Use sessions when you need state to persist across executions.

ExecutionRequest

The Script field is the primary input. Additional fields are available for advanced use:

Field	Type	Description
`Script`	`string`	The bash script to execute.
`Name`	`string`	Optional execution label used for traces and logs. When `ScriptPath` is empty, it is also used as the parser filename and `$0`.
`ScriptPath`	`string`	Optional source path for a script payload that came from a file. When set, gbash treats the execution as file-backed and uses it for the parser filename, `$0`, and `BASH_SOURCE[0]`.
`Interpreter`	`string`	Override the shell name used for this execution (`bash`, `sh`, or a wrapper name).
`PassthroughArgs`	`[]string`	Shell argv forwarded into nested invocations and CLI-style wrappers.
`Args`	`[]string`	Positional arguments (`$1`, `$2`, ...).
`StartupOptions`	`[]string`	Shell startup flags such as `-e` or `-u`.
`Env`	`map[string]string`	Per-execution environment overrides.
`WorkDir`	`string`	Override the working directory for this execution.
`Timeout`	`time.Duration`	Execution timeout.
`ReplaceEnv`	`bool`	Replace the base environment entirely instead of overlaying on top of it.
`Interactive`	`bool`	Marks the request as interactive when a wrapper is bridging an interactive shell.
`Stdin`	`io.Reader`	Standard input for the script.
`Stdout`	`io.Writer`	Direct stdout to a writer instead of capturing it.
`Stderr`	`io.Writer`	Direct stderr to a writer instead of capturing it.

ScriptPath only affects file provenance. Inline -c and stdin-style executions should leave it empty so BASH_SOURCE stays unset, matching bash.

ExecutionResult

Field	Type	Description
`ExitCode`	`int`	The exit code of the script.
`ShellExited`	`bool`	Reports whether the shell terminated via `exit` rather than simply finishing the script.
`Stdout`	`string`	Captured standard output (empty when `Stdout` writer is set on the request).
`Stderr`	`string`	Captured standard error (empty when `Stderr` writer is set on the request).
`ControlStderr`	`string`	Non-script diagnostics emitted by the runtime or CLI wrapper.
`StartedAt`	`time.Time`	Wall-clock start timestamp.
`FinishedAt`	`time.Time`	Wall-clock finish timestamp.
`Duration`	`time.Duration`	Wall-clock execution time.
`Events`	`[]trace.Event`	Structured trace events, populated only when tracing is enabled.
`FinalEnv`	`map[string]string`	The environment after execution completes.
`StdoutTruncated`	`bool`	True if stdout exceeded the capture limit.
`StderrTruncated`	`bool`	True if stderr exceeded the capture limit.

Observability

Tracing and logging are both opt-in.

Use WithTracing to populate ExecutionResult.Events and optionally receive OnEvent callbacks.
Use WithLogger for exec.start, stdout, stderr, exec.finish, and exec.error lifecycle hooks.