Mom Docker Sandbox¶

Overview¶

Mom can run tools either directly on the host or inside a Docker container for isolation.

Why Docker?¶

When mom runs on your machine and is accessible via Slack, anyone in your workspace could potentially: - Execute arbitrary commands on your machine - Access your files, credentials, etc. - Cause damage via prompt injection

The Docker sandbox isolates mom's tools to a container where she can only access what you explicitly mount.

Quick Start¶

# 1. Create and start the container
cd packages/mom
./docker.sh create ./data

# 2. Run mom with Docker sandbox
mom --sandbox=docker:mom-sandbox ./data

How It Works¶

┌─────────────────────────────────────────────────────┐
│  Host                                               │
│                                                     │
│  mom process (Node.js)                              │
│  ├── Slack connection                               │
│  ├── LLM API calls                                  │
│  └── Tool execution ──────┐                         │
│                           ▼                         │
│              ┌─────────────────────────┐            │
│              │  Docker Container       │            │
│              │  ├── bash, git, gh, etc │            │
│              │  └── /workspace (mount) │            │
│              └─────────────────────────┘            │
└─────────────────────────────────────────────────────┘

Mom process runs on host (handles Slack, LLM calls)
All tool execution (bash, read, write, edit) happens inside the container
Only /workspace (your data dir) is accessible to the container

Container Setup¶

Use the provided script:

./docker.sh create <data-dir>   # Create and start container
./docker.sh start               # Start existing container
./docker.sh stop                # Stop container
./docker.sh remove              # Remove container
./docker.sh status              # Check if running
./docker.sh shell               # Open shell in container

Or manually:

docker run -d --name mom-sandbox \
  -v /path/to/mom-data:/workspace \
  alpine:latest tail -f /dev/null

Mom Manages Her Own Computer¶

The container is treated as mom's personal computer. She can:

Install tools: apk add github-cli git curl
Configure credentials: gh auth login
Create files and directories
Persist state across restarts

When mom needs a tool, she installs it. When she needs credentials, she asks you.

Example Flow¶

User: "@mom check the spine-runtimes repo"
Mom:  "I need gh CLI. Installing..."
      (runs: apk add github-cli)
Mom:  "I need a GitHub token. Please provide one."
User: "ghp_xxxx..."
Mom:  (runs: echo "ghp_xxxx" | gh auth login --with-token)
Mom:  "Done. Checking repo..."

Persistence¶

The container persists across: - docker stop / docker start - Host reboots

Installed tools and configs remain until you docker rm the container.

To start fresh: ./docker.sh remove && ./docker.sh create ./data

CLI Options¶

# Run on host (default, no isolation)
mom ./data

# Run with Docker sandbox
mom --sandbox=docker:mom-sandbox ./data

# Explicit host mode
mom --sandbox=host ./data

Security Considerations¶

What the container CAN do: - Read/write files in /workspace (your data dir) - Make network requests (for git, gh, curl, etc.) - Install packages - Run any commands

What the container CANNOT do: - Access files outside /workspace - Access your host's credentials - Affect your host system

For maximum security: 1. Create a dedicated GitHub bot account with limited repo access 2. Only share that bot's token with mom 3. Don't mount sensitive directories

Troubleshooting¶

Container not running¶

./docker.sh status  # Check status
./docker.sh start   # Start it

Reset container¶

./docker.sh remove
./docker.sh create ./data

Missing tools¶

Ask mom to install them, or manually:

docker exec mom-sandbox apk add <package>