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 ¶
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 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.
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 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 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 Prepare ¶
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).
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). |