Architecture Pillar // 05
Scoped Security & Systemd Sandboxing
Enforce least-privilege boundaries for AI agents. No raw root sockets, 256-bit cryptographic bearer tokens, and signed audit trails.
The Dangers of Raw Root Socket Sharing
Granting an AI coding agent access to /var/run/docker.sock is equivalent to granting root privileges on your host machine. Any prompt injection, model confusion, or malformed script can mount host root directories (-v /:/host), tamper with host SSH keys, or read memory secrets.
The Smoooth Security Hierarchy
Smoooth sits as a protective intermediary between the AI coding agent and the Linux kernel:
- Loopback Isolation: The HTTP daemon binds exclusively to local loopback (
127.0.0.1:4040) by default, completely inaccessible from public network interfaces. - Systemd Sandboxing: Runs under a dedicated service unit with
NoNewPrivileges=yes,ProtectSystem=strict, and restricted capability bounds. - 256-bit Scoped Bearer Tokens: Tokens enforce role-based access controls:
read_only: Query container status, inspect logs, and check health probes.plan: Run execution plan dry-runs without making state changes.deploy: Execute validated plans and cut over ingress routes.admin: Rotate credentials and modify host settings.
- Append-Only Audit Log: Every tool execution is recorded with a SHA-256 integrity hash for auditing.
Token Generation CLI
# Issue a deployment-scoped token for Claude Code:
$ smoooth auth token create --role deploy --ttl 24h
[OK] Token generated: smth_sec_7f9a8820c4e1b994f30a...
[INFO] Scopes granted: [inspect_host, create_plan, execute_plan]
[INFO] Denied operations: [drop_volume, rotate_master_keys, bash_exec]