1. Minimal attack surface — no web UI, no unnecessary open ports, SSH key-only (password auth disabled)
2. Explicit trust — every communication channel requires authentication
3. Physical presence — high-privilege actions (enrollment, admin) require being physically at the box
4. Local processing — perception runs on-device; no images or audio leave the box except explicit API calls
5. No information leakage — unauthenticated requests receive no response

Users are people with authenticated remote channels (WhatsApp by default). Registration uses single-use, time-limited codes. See user-registration.md for the complete flow.

• Code displayed on the 7" screen during initial setup (physical presence)
• User texts code to BB's WhatsApp → registered as primary admin
• Bootstrap permanently disabled after first admin registers
• This is the ONLY registration that doesn't require an existing admin

• Admin requests a code → BB sends code to admin via WhatsApp
• Admin shares code with new user out-of-band (in person, text, etc.)
• New user texts code to BB → registered as standard user
• BB never initiates contact with unknown numbers — admin gatekeeps

• 6 digits, cryptographically random, single-use, expires in 10 minutes
• One active code at a time, rate-limited (3 per hour per admin)
• Failed attempts: silent drop, rate limiting, temp/permanent blocking

• admin — register/remove users, approve packages, promote admins
• standard — send/receive messages, interact with skills

• Messages from unregistered numbers → silent drop (no response)
• No error message, no acknowledgment, no information leakage
• Only exception: message contains a valid, unexpired registration code
• Failed code attempts also produce no response

BB's WhatsApp is for user ↔ BB communication only. It is not a proxy for other services:

• Email checking → skill (sandbox, IMAP/Gmail API, own credentials)
• Calendar sync → skill (sandbox, CalDAV, own credentials)
• RSS/news → skill (sandbox, own packages)
• Any inbox-style service → skill, never through the messaging path

BB may relay results via WhatsApp ("you have 3 unread emails"), but the data fetching runs in the sandbox. This prevents privilege confusion and keeps the authenticated channel clean.

• WHATSAPP_APP_SECRET is required — boxBot will not start the WhatsApp listener without it. Set it in .env
• Incoming webhooks validated against WhatsApp's X-Hub-Signature-256 header using HMAC-SHA256 with the app secret
• Forged webhooks rejected (HTTP 403) before any processing
• Webhook port is the only open listener (required by WhatsApp API)

Two distinct surfaces, by who needs the value:

1. Main-process secrets — .env

• API keys the main process uses directly: ANTHROPIC_API_KEY, WHATSAPP_ACCESS_TOKEN, ELEVENLABS_API_KEY, AWS keys, etc.
• File mode 0600, owned by the main-process user
• WhatsApp credentials also in config/whatsapp.yaml (gitignored)
• The sandbox user has no read access (and home-dir 0700 blocks traversal regardless)

2. Agent-managed secrets — bb.secrets / data/credentials/secrets.json

• Credentials the agent stores at runtime (third-party API keys, OAuth refresh tokens, e.g. GOOGLE_CALENDAR_TOKEN_JSON)
• File mode 0600, owned by the main-process user, atomic write, 64-secret cap, ≤8 KB per value
• Sandbox scripts and integrations receive their values only as BOXBOT_SECRET_<NAME> env vars at launch, scoped to:
  • The names declared in an integration's manifest secrets: list, or
  • The names the agent passed in execute_script's secrets=[…]
• The agent itself cannot read values back. SDK calls return name lists and existence checks; values cross only the runner→subprocess boundary
• Action log redaction: secrets.store records {name, status} only; the value is never written to the action log the agent observes

Neither store is committed; both are gitignored.

• Person embeddings stored locally in data/ (gitignored)
• Photos stored locally in data/photos/ (gitignored)
• Memory database stored locally (gitignored)
• Optional encrypted cloud backup (S3, disabled by default)

Sandbox security is enforced at the operating system level. Python- level restrictions can always be bypassed; OS-level enforcement cannot be circumvented from userspace code.

Dedicated user: Scripts run as boxbot-sandbox, a restricted system user with minimal permissions. The main process runs as boxbot.

seccomp filter: The sandbox process has execve, fork, vfork, and clone syscalls blocked at the kernel level. No subprocess spawning of any kind — subprocess.run(), os.system(), os.exec*(), and even ctypes-based syscalls are all killed by the kernel.

Filesystem permissions: Enforced by Unix file ownership, not Python checks:

• .env → mode 0600 owned by boxbot → sandbox cannot read
• src/boxbot/ → owned by boxbot → sandbox cannot write
• data/sandbox/venv/lib/ → owned by boxbot → sandbox cannot write (read + execute only)
• data/sandbox/venv/bin/pip → mode 0700 owned by boxbot → sandbox cannot execute
• data/sandbox/output/, tmp/ → owned by boxbot-sandbox → writable
• skills/ → group-writable → sandbox can create skill directories

Resource limits: 30s timeout (main process kills), 256MB memory (ulimit/cgroup), single core.

Secrets: Scripts receive only specific API keys needed for the current task, passed as env vars by the main process. Never the full .env.

The sandbox cannot install packages. This is enforced by four independent OS-level controls:

1. seccomp blocks execve → can't run pip as subprocess
2. pip binary is mode 0700 owned by boxbot → sandbox can't execute it
3. site-packages is owned by boxbot → sandbox can't write to it
4. venv directory is read-only to boxbot-sandbox

Only the main process (as boxbot) can install packages, and it will only do so after out-of-band human approval through a channel the sandbox cannot access:

• Display tap: approval prompt on the touchscreen (physical input)
• WhatsApp reply: message to the admin user, response validated against the admin's phone number

The approval channel is completely separate from the sandbox's stdout. The sandbox can only emit a REQUEST action — there is no SDK action that means "already approved." The agent cannot spoof approval because the approval comes from a different input pathway entirely.

All installs are logged to data/sandbox/installed.txt (append-only, owned by boxbot).

The agent creates skills and displays through the boxbot_sdk — a constrained, immutable API pre-installed in the sandbox venv. The agent cannot write code that runs directly in the main process:

• SDK is in read-only site-packages (owned by boxbot)
• Skills auto-activate (logic runs in sandbox, contained)
• Displays are declarative (agent uses building blocks, main process generates validated render code — no raw render() from agent input)
• Displays require user confirmation before activation
• Core code (src/boxbot/) is off-limits (owned by boxbot)

The application-level controls above protect against a compromised agent. OS-level hardening protects the Pi itself from network-based attacks.

scripts/harden-os.sh is a standalone, idempotent script that:

• Enables a UFW firewall (deny all inbound; allow only SSH and the WhatsApp webhook port)
• Hardens SSH: key-only authentication, no root login, idle timeout
• Enables automatic security updates (Debian security patches only)
• Disables unnecessary services (Bluetooth, mDNS)

SSH remains enabled — this is a tinkerer project — but password auth is disabled. The script includes lockout protection: it will not disable password auth unless at least one SSH public key is present.

See os-hardening.md for full rationale, verification steps, and how to revert each change.

If you discover a security vulnerability, do not open a public issue. Contact the maintainers directly.