Menu
Sandbox execution model for boxbot_sdk scripts โ what execute_script can and cannot reach, and where the per-module API docs live.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
The bb Python package โ your hands inside the sandbox. Import it from execute_script for camera stills, photo search, the 7" display, a persistent notes/CSV workspace, memory, triggers and to-dos, audio playback, new skills, secrets, and data-pipe integrations (calendar lives here). Load when the user mentions photos, the camera, the screen, notes, lists tracked over time, reminders, or anything worth composing in one turn.
Control the household through Home Assistant โ lights, scenes, climate, media, smart plugs โ and read live state like alarm armed/disarmed, doors, sensors, presence. The home_assistant integration is the single pipe; this skill is the map. Loads when the user asks BB to do anything touching a physical device, set a mood, check the house, or peek at a camera.
How to onboard people to boxBot โ voice first-meeting (Person), first-admin bootstrap, admin-initiated user registration (User), welcoming a freshly-registered user.
How to create your own skills. A skill is structured prompt data โ a markdown SKILL.md you read on demand, optionally bundled with helper scripts. Load before calling bb.skill.create(), or when you catch yourself solving the same kind of problem twice.
| name | hal-sandbox-ref |
| description | Sandbox execution model for boxbot_sdk scripts โ what execute_script can and cannot reach, and where the per-module API docs live. |
| when_to_use | Writing a script via execute_script and you need the security boundary โ what's importable, what's blocked, why a call was refused. For API detail, load the `bb` skill instead. |
boxbot_sdk (importable as bb) is preinstalled and immutable. It is
the only way an execute_script script affects boxBot. boxbot.*
core imports are absent from the sandbox venv โ you cannot reach
internals, only declare intent through the SDK.
The SDK never acts directly. It emits structured JSON actions on stdout; the main process parses, validates, and applies them. You never think about the transport.
API docs live in the bb skill โ load_skill(name="bb") for the
module index, then subpath="modules/<x>.md" for depth. This page is
the boundary, not the reference.
boxbot.* โ not in the sandbox venv.execve and fork. Import
bundled scripts instead of shelling out..env or on-disk secrets โ mode 0600, different owner.site-packages is read-only. Use
bb.packages.request(); an admin approves out-of-band and there is no
way to spoof approval from inside.bb.secrets is write-only. Values reach
scripts only as BOXBOT_SECRET_<NAME> env vars.boxbot:boxbot 0644
after save. Delete and recreate.Everything in bb: workspace, camera, photos, audio,
display, memory, tasks, auth, skill, integrations,
packages, secrets โ plus stdlib and whatever is installed in the
sandbox venv (httpx, requests, โฆ).
Images from bb.workspace.view, bb.camera.capture, bb.photos.view,
and bb.display.preview attach to the tool result, up to 8 per call.
Mutating calls raise bb.ActionError when the main process rejects
them โ a failed write never looks like a success. Read calls return
response dicts; a failing run (an integration returning
status: "error") is data to inspect, not an exception.
bb skill โ the SDK's own docs, module by moduledocs/sandbox.md โ the full security modelsrc/boxbot/sdk/README.md โ SDK internalsdocs/memory.md, docs/display-system.md