Documentation
¶
Overview ¶
Package sandbox runs RocketClaw's emulated shell: real Bash and Linux programs in a bubblewrap sandbox with no network, no host files but the agent's folders, cgroup limits and seccomp (docs/specs/2026-11-01-linux-native-just-bash-spec.md). Commands an agent declares, and curl, run on the host through Host; the RocketClaw binary, mounted read-only, relays them out of the sandbox.
Index ¶
- Constants
- Variables
- func BuildImage(ctx context.Context, snapshot, arch, dst, cgroup string) (installed []string, release string, err error)
- func CheckCommandName(name string) error
- func Guest(args []string) (code int, ok bool)
- type Bubblewrap
- type BuildError
- type Command
- type Host
- type None
- type Result
- type Runtime
Constants ¶
const Curl = "curl"
Curl is the managed HTTP client every emulated shell has; Host runs it like a command.
const Snapshot = "20261031T000000Z"
Snapshot is the Ubuntu archive moment every package of the guest image comes from.
Variables ¶
var ErrPreparing = errors.New("the first start builds the sandbox's Ubuntu image, which takes a minute or two; commands wait for it")
ErrPreparing is what Err reports while Prepare still works; commands wait for it instead.
Functions ¶
func BuildImage ¶
func BuildImage(ctx context.Context, snapshot, arch, dst, cgroup string) (installed []string, release string, err error)
BuildImage builds the guest image for arch from the archive snapshot (a moment like Snapshot) into dst: mmdebstrap (Linux, unprivileged user namespaces, and qemu-user emulation for the other architecture) writes a tar, and extract writes it out without device nodes, setuid or setgid bits, or file capabilities, plus the guest user and js-exec. It returns the installed packages as name=version lines and the Ubuntu release. Prepare builds Snapshot's at the first start, and the update tool in rootfs/ the newest. mmdebstrap runs in a cgroup, build, under cgroup ("" for the caller's), killed when the build ends.
func CheckCommandName ¶
CheckCommandName reports why an agent cannot declare a command named name: it becomes a file and a Bash function in the sandbox.
Types ¶
type Bubblewrap ¶ added in v0.2.31
type Bubblewrap struct{}
Bubblewrap prepares the real sandbox.
func (Bubblewrap) Prepare ¶ added in v0.2.31
Prepare readies the sandbox under dir in the background and returns at once: it checks the host, builds the pinned guest image the first time (a minute or two; later starts find it under the lock's hash), takes over RocketClaw's delegated cgroup, and runs a probe. Run waits for it. On any failure the Runtime stays unavailable with a reason that says what to do, and log records it in full, so emulated shells refuse rather than run unsandboxed (spec §5.3).
type BuildError ¶
BuildError is a failed mmdebstrap. Its message is the first error line of the output, which is long and goes to the server log whole.
func (*BuildError) Error ¶
func (e *BuildError) Error() string
func (*BuildError) Unwrap ¶
func (e *BuildError) Unwrap() error
type Command ¶
type Command struct {
Script string
Cwd string // guest working directory; folders show at their host paths
Dir string // the agent's writable folder
ReadOnly []string // folders shown read-only
Env []string // the guest's whole environment; never RocketClaw's
Commands []string // names Host runs; the guest reaches only these and curl
Timeout time.Duration // whole command
}
Command is one emulated shell command line.
type Host ¶
type Host interface {
// Command runs name with args and stdin, writing its output, and returns its exit status, 0 to 255. cwd
// is the guest's working directory, a guest path.
Command(ctx context.Context, name string, args []string, cwd string, stdin io.Reader, stdout, stderr io.Writer) int
}
Host runs, outside the sandbox, what an emulated shell may ask of the host: the agent's commands and curl. Everything it receives comes from the guest and is untrusted.
type None ¶ added in v0.2.31
type None struct{}
None prepares no sandbox, for tests that never run an emulated shell.
type Result ¶
type Result struct {
Output []byte
ExitCode int
TimedOut bool
// Truncated means the output limit stopped the command.
Truncated bool
}
Result is the outcome of a shell that started: stdout and stderr together, as host bash gives them.
type Runtime ¶
type Runtime struct {
// contains filtered or unexported fields
}
Runtime runs emulated shell commands. It is a handle: copies share one preparation, which Prepare fills in the background, so a copy taken while it works sees the outcome too. The zero value is unavailable: every Run fails, never falling back to host Bash.
func (*Runtime) Err ¶
Err reports why commands cannot run, ErrPreparing while that is still being decided (wrapped with the last failed try when the image build is retrying), or nil when the sandbox is ready. It never waits.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Command rootfs moves the emulated shell's guest image to the newest Ubuntu archive snapshot.
|
Command rootfs moves the emulated shell's guest image to the newest Ubuntu archive snapshot. |
|
Package wire is the emulated shell's relay protocol: length-delimited protobuf Frames over a Unix socket, one invocation per connection (wire.proto, docs/explainers/2026-11-01-emulated-shell-sandbox.md).
|
Package wire is the emulated shell's relay protocol: length-delimited protobuf Frames over a Unix socket, one invocation per connection (wire.proto, docs/explainers/2026-11-01-emulated-shell-sandbox.md). |