@geminixiang/mama 0.2.0-beta.0 → 0.2.0-beta.10

package/README.md

@@ -1,70 +1,35 @@
-# mama
+# mama (Multi-Agent Mischief Assistant)
 
 [![npm version](https://img.shields.io/npm/v/@geminixiang/mama.svg)](https://www.npmjs.com/package/@geminixiang/mama)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-A multi-platform AI agent bot for Slack, Telegram, and Discord — based on [pi-mom](https://github.com/badlogic/pi-mono), with the goal of merging improvements back upstream.
+A multi-platform AI assistant for Slack, Telegram, and Discord.
 
-## 📜 Attribution & Origins
-
-This project is a **forked and extended version** of the `mom` package from [`badlogic/pi-mono`](https://github.com/badlogic/pi-mono) by Mario Zechner, licensed under MIT.
-
-- **Original project**: [pi-mom](https://github.com/badlogic/pi-mono/tree/main/packages/mom) (22K+ stars)
-- **Base version**: forked from pi-mom v0.57.1 (synchronized with `@mariozechner/*` packages)
-- **Primary motivation**: Internal services urgently needed a multi-platform bot — this fork enables rapid iteration while preparing changes to contribute back upstream
-
-## 🎯 Positioning & Roadmap
-
-| Aspect             | Description                                                                    |
-| ------------------ | ------------------------------------------------------------------------------ |
-| **Current Status** | Temporary standalone fork for urgent internal deployment                       |
-| **Ultimate Goal**  | Merge all improvements back into pi-mono monorepo                              |
-| **Unique Value**   | Multi-platform support (Slack + Telegram + Discord) to be contributed upstream |
-
-### Why a temporary fork?
-
-Our internal services urgently needed a multi-platform bot, and we couldn't wait for upstream release cycles. This fork allows us to:
-
-1. **Ship fast**: Deploy to production immediately while internal demand is high
-2. **Iterate freely**: Test multi-platform adapters (Slack, Telegram, Discord) without monorepo constraints
-3. **Contribute back**: All work here is intended to be merged into pi-mono — `mama` is not a replacement for `mom`
-
-### Contribution Philosophy 🔄
-
-> "This is not a separate product — it's a **temporary fork** for urgent internal needs, and all improvements will be contributed back to pi-mono."
-
-We actively track the upstream `pi-mom` and plan to:
-
-- ✅ Submit PRs for platform adapters (Telegram, Discord)
-- ✅ Contribute cross-platform abstractions
-- ✅ Keep dependencies synchronized with pi-mono releases
-- ✅ Document what we learn from production use
-
----
+Forked from [`badlogic/pi-mono`](https://github.com/badlogic/pi-mono)'s `mom` package (MIT, by Mario Zechner) at v0.57.1. This fork adds Telegram and Discord adapters and exists to ship internally while we prepare changes to upstream.
 
 ## Features
 
-- **Multi-platform** — Slack, Telegram, and Discord adapters out of the box
-- **Persistent sessions** — session behavior is adapted per platform instead of forcing one thread model everywhere
-- **Concurrent conversations** — Slack threads, Discord replies/threads, and Telegram reply chains can run independently
-- **Sandbox execution** — run agent commands on host or inside a Docker container
-- **Persistent memory** — workspace-level and channel-level `MEMORY.md` files
-- **Skills** — drop custom CLI tools into `skills/` directories
-- **Event system** — schedule one-shot or recurring tasks via JSON files
-- **Multi-provider** — configure any provider/model supported by `pi-ai`
+- **Multi-platform** — Slack, Telegram, Discord adapters
+- **Concurrent conversations** — Slack threads, Discord replies/threads, and Telegram reply chains run as independent sessions
+- **Sandbox execution** — host, shared container, per-user managed container, Firecracker (alpha), or Cloudflare bridge (experimental)
+- **Credential vaults** — `/login` stores credentials under `--state-dir` and injects env into sandbox runs
+- **Web session viewer** — read-only web view of the current session via `session` / `/session`
+- **Persistent memory** — workspace-level and channel-level `MEMORY.md`
+- **Skills** — drop CLI tools into `skills/`
+- **Events** — schedule one-shot or recurring tasks via JSON files
+- **Multi-provider** — any provider/model supported by `pi-ai`
 
 ## Platform Session Model
 
-| Platform | User Interaction Structure                | `sessionKey` Rule                                                    | Default Session Model                                                                | Special Handling Needed | Notes                                                                                            |
-| -------- | ----------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ----------------------- | ------------------------------------------------------------------------------------------------ |
-| Slack    | channel top-level + thread replies        | top-level: `channelId`; thread: `channelId:threadTs`                 | channel keeps one persistent session; thread forks from channel into its own session | High                    | channel -> thread inherits context via fork; thread -> channel does not merge back automatically |
-| Discord  | normal messages, replies, thread channels | `channelId:threadTsOrMsgId`                                          | replies / thread channels naturally map to isolated sessions                         | Low                     | no aliasing layer needed; session identity is determined directly from the Discord event         |
-| Telegram | private chats, group replies              | private chat: `chatId`; group reply chain: `chatId:replyToIdOrMsgId` | private chats use one long session; groups split by reply chain                      | Medium                  | Telegram has no native thread model; group sessions are modeled from reply chains                |
+| Platform | `sessionKey` Rule                                                                 | Notes                                                                                |
+| -------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| Slack    | top-level / DM: `conversationId`; thread: `conversationId:threadTs`               | thread inherits parent context at fork time only; branch changes do not merge back   |
+| Discord  | DM: `channelId`; shared top-level: `channelId:messageId`; reply/thread: rooted id | replies in shared channels continue the root message session; DM replies do not fork |
+| Telegram | private: `chatId`; shared top-level: `chatId:messageId`; reply chain: root reply  | no native thread model; shared sessions are inferred from reply chains               |
 
 ## Requirements
 
 - Node.js >= 20
-- One of the platform integrations below
 
 ## Installation
 
@@ -72,376 +37,248 @@ We actively track the upstream `pi-mom` and plan to:
 npm install -g @geminixiang/mama
 ```
 
-Or run directly after cloning:
+Or from source:
 
 ```bash
-npm install
-npm run build
+npm install && npm run build
 ```
 
----
-
 ## Quick Start
 
-### Slack
-
-1. Create a Slack app with **Socket Mode** enabled ([setup guide](docs/slack-bot-minimal-guide.md)).
-2. Add the following **OAuth Bot Token Scopes**:
-   - `app_mentions:read`, `channels:history`, `channels:read`, `chat:write`
-   - `files:read`, `files:write`, `groups:history`, `groups:read`
-   - `im:history`, `im:read`, `im:write`, `users:read`
-   - `assistant:write` — required for native "Thinking" status indicator
-3. Enable the **Home Tab** and **Agent mode**:
-   - **App Home → Show Tabs** — toggle **Home Tab** on
-   - **App Home → Agents & AI Apps** — toggle **Agent or Assistant** on
-4. Subscribe to **Bot Events**:
-   - `app_home_opened`, `app_mention`
-   - `assistant_thread_context_changed`, `assistant_thread_started`
-   - `message.channels`, `message.groups`, `message.im`
-5. Enable **Interactivity** (Settings → Interactivity & Shortcuts → toggle on).
-6. Copy the **App-Level Token** (`xapp-…`) and **Bot Token** (`xoxb-…`).
-
-Or import this **App Manifest** directly (Settings → App Manifest → paste JSON):
-
-<details>
-<summary>Example App Manifest</summary>
+All platforms share the same CLI:
 
-```json
-{
-  "display_information": {
-    "name": "mama"
-  },
-  "features": {
-    "app_home": {
-      "home_tab_enabled": true,
-      "messages_tab_enabled": false,
-      "messages_tab_read_only_enabled": false
-    },
-    "bot_user": {
-      "display_name": "mama",
-      "always_online": false
-    }
-  },
-  "oauth_config": {
-    "scopes": {
-      "bot": [
-        "app_mentions:read",
-        "assistant:write",
-        "channels:history",
-        "channels:read",
-        "chat:write",
-        "files:read",
-        "files:write",
-        "groups:history",
-        "groups:read",
-        "im:history",
-        "im:read",
-        "im:write",
-        "users:read"
-      ]
-    }
-  },
-  "settings": {
-    "event_subscriptions": {
-      "bot_events": [
-        "app_home_opened",
-        "app_mention",
-        "assistant_thread_context_changed",
-        "assistant_thread_started",
-        "message.channels",
-        "message.groups",
-        "message.im"
-      ]
-    },
-    "interactivity": {
-      "is_enabled": true
-    },
-    "org_deploy_enabled": false,
-    "socket_mode_enabled": true,
-    "token_rotation_enabled": false
-  }
-}
+```bash
+mama [--state-dir=~/.mama] [--sandbox=<mode>] <working-directory>
 ```
 
-</details>
+Set the platform tokens you need (you can run multiple platforms at once):
 
 ```bash
-export MOM_SLACK_APP_TOKEN=xapp-...
-export MOM_SLACK_BOT_TOKEN=xoxb-...
-
-mama [--sandbox=host|docker:<container>] <working-directory>
+export MAMA_SLACK_APP_TOKEN=xapp-...
+export MAMA_SLACK_BOT_TOKEN=xoxb-...
+export MAMA_TELEGRAM_BOT_TOKEN=123456:ABC-...
+export MAMA_DISCORD_BOT_TOKEN=MTI...
 ```
 
-The bot responds when `@mentioned` in any channel or via DM.
+### Slack
 
-- **Top-level channel messages** — share one persistent channel session.
-- **Thread replies** — fork from the channel session into an isolated thread session.
-- **Thread memory** — inherited at fork time only; thread changes do not merge back into the channel automatically.
-
----
+Create a Socket Mode app with the scopes and event subscriptions listed in [docs/slack-bot-minimal-guide.md](docs/slack-bot-minimal-guide.md). The bot responds when `@mentioned` in channels and to all DMs.
 
 ### Telegram
 
-1. Message [@BotFather](https://t.me/BotFather) → `/newbot` to create a bot and get the **Bot Token**.
-2. Optionally disable privacy mode (`/setprivacy → Disable`) so the bot can read group messages without being `@mentioned`.
+Create a bot via [@BotFather](https://t.me/BotFather) and copy the token. The bot responds to all private messages, and to `@mention` or reply chains in groups. Use `/login`, `/session`, `/new`, and `/stop` for controls.
 
-```bash
-export MOM_TELEGRAM_BOT_TOKEN=123456:ABC-...
+### Discord
 
-mama [--sandbox=host|docker:<container>] <working-directory>
-```
+Create an application in the [Discord Developer Portal](https://discord.com/developers/applications), enable **Message Content Intent**, and invite the bot with `Send Messages`, `Read Message History`, `Attach Files`. The bot responds to `@mentions` in servers and to all DMs.
 
-- **Private chats** — every message is forwarded to the bot automatically.
-- **Group chats** — the bot only responds when `@mentioned` by username.
-- **Reply chains** — replying to a previous message continues the same session.
-- Say `stop` or `/stop` to cancel a running task.
+## Sandbox Modes
 
----
+| Mode                         | Description                                                            |
+| ---------------------------- | ---------------------------------------------------------------------- |
+| `host` (default)             | Run on host; no vault env injection                                    |
+| `container:<name>`           | Run in an existing shared container; uses vault key `container-<name>` |
+| `image:<image>`              | Auto-provision one Docker container per resolved vault/user            |
+| `firecracker:<vm-id>:<path>` | Firecracker microVM (alpha; not recommended)                           |
+| `cloudflare:<sandbox-id>`    | Cloudflare Worker bridge (experimental; no auto workspace sync)        |
 
-### Discord
+Vault routing: `image`, `firecracker`, and `cloudflare` resolve a vault per platform userId. See [docs/sandbox.md](docs/sandbox.md) for the full matrix.
 
-1. Go to the [Discord Developer Portal](https://discord.com/developers/applications) → **New Application**.
-2. Under **Bot**, enable **Message Content Intent** (required to read message text).
-3. Under **OAuth2 → URL Generator**, select scopes `bot` + permissions `Send Messages`, `Read Message History`, `Attach Files`. Invite the bot to your server with the generated URL.
-4. Copy the **Bot Token**.
+### Managed per-user containers (`image:*`)
 
 ```bash
-export MOM_DISCORD_BOT_TOKEN=MTI...
-
-mama [--sandbox=host|docker:<container>] <working-directory>
+docker pull ghcr.io/geminixiang/mama-sandbox:latest
+mama --sandbox=image:ghcr.io/geminixiang/mama-sandbox:latest /path/to/workspace
 ```
 
-- **Server channels** — the bot responds when `@mentioned`.
-- **DMs** — every message is forwarded automatically.
-- **Threads** — messages inside a Discord thread share a single session.
-- **Reply chains** — replying to a message continues that session.
-- Say `stop` or `/stop` to cancel a running task.
+Or build locally:
 
----
+```bash
+docker build -f docker/mama-sandbox.Dockerfile -t mama-sandbox:tools .
+```
 
-## Options
+mama creates one container per vault, attaches each to its own bridge network, mounts the workspace at `/workspace`, injects vault env, mounts declared credential files, and stops idle containers.
 
-| Option                                 | Default | Description                                              |
-| -------------------------------------- | ------- | -------------------------------------------------------- |
-| `--sandbox=host`                       | ✓       | Run commands directly on host                            |
-| `--sandbox=docker:<name>`              |         | Run commands inside a Docker container                   |
-| `--sandbox=firecracker:<vm-id>:<path>` |         | Run commands inside a Firecracker microVM                |
-| `--download <channel-id>`              |         | Download channel history to stdout and exit (Slack only) |
+### Firecracker / Cloudflare
 
-### Download channel history (Slack)
+See [docs/firecracker-setup.md](docs/firecracker-setup.md) and [examples/cloudflare-sandbox-bridge/README.md](examples/cloudflare-sandbox-bridge/README.md).
+
+## `/login` and Web Session Viewer
 
 ```bash
-mama --download C0123456789
+export MAMA_LINK_URL="https://mama.example.com"   # public base URL
+export MAMA_LINK_PORT=8181                         # optional, defaults to 8181
 ```
 
+For local testing you can set just `MAMA_LINK_PORT`; mama will use `http://localhost:<port>`.
+
+- `/login` (DM only) returns a 15-minute link to store API keys or run built-in OAuth flows ([GitHub](docs/oauth/github.md), [Google Workspace](docs/oauth/google-workspace.md)).
+- `session` / `/session` (DM only) returns a read-only link showing the current session timeline.
+- `new` / `/new` (DM only) resets the current session and starts fresh.
+- `model` / `/model` / `/pi-model provider/model[:thinking]` switches the LLM for the current conversation, e.g. `/pi-model anthropic/claude-sonnet-4-6:off`.
+- `auto-reply` / `/pi-auto-reply on|off|status` controls group/channel auto-reply for the current conversation. Rules live in the conversation's `auto-reply` marker file.
+- `stop` / `/stop` stops the current run. On Slack, use text commands so thread-local stop routing remains accurate.
+- On Slack you can also register native commands like `/pi-login`, `/pi-session`, `/pi-model`, `/pi-auto-reply`, and `/pi-new`.
+
+Credentials are stored under `<state-dir>/vaults` (default `~/.mama/vaults`). Vault env is only injected in `container`, `image`, `firecracker`, and `cloudflare` modes.
+
 ## Configuration
 
-Create `settings.json` in your working directory to override defaults:
+mama reads global settings from `<state-dir>/settings.json` (default `~/.mama/settings.json`, override via `--state-dir` or `MAMA_STATE_DIR`). This file is required and is created explicitly with `mama --onboard`. Per-conversation settings live at `<workingDir>/<conversationId>/settings.json` and override global settings for that conversation.
 
 ```json
 {
-  "provider": "anthropic",
-  "model": "claude-sonnet-4-5",
-  "thinkingLevel": "off",
-  "sessionScope": "thread",
-  "logFormat": "console",
-  "logLevel": "info",
-  "sentryDsn": "https://examplePublicKey@o0.ingest.sentry.io/0"
+  "llm": {
+    "provider": "anthropic",
+    "model": "claude-sonnet-4-6",
+    "thinkingLevel": "off"
+  },
+  "log": {
+    "format": "console",
+    "level": "info"
+  },
+  "sentry": {
+    "dsn": "https://examplePublicKey@o0.ingest.sentry.io/0"
+  },
+  "sandbox": {
+    "cpus": "0.5",
+    "memory": "512m",
+    "boost": {
+      "cpus": "2",
+      "memory": "4g"
+    }
+  }
 }
 ```
 
-| Field           | Default             | Description                                              |
-| --------------- | ------------------- | -------------------------------------------------------- |
-| `provider`      | `anthropic`         | AI provider (env: `MOM_AI_PROVIDER`)                     |
-| `model`         | `claude-sonnet-4-5` | Model name (env: `MOM_AI_MODEL`)                         |
-| `thinkingLevel` | `off`               | `off` / `low` / `medium` / `high`                        |
-| `sessionScope`  | `thread`            | `thread` (per thread/reply chain) or `channel`           |
-| `logFormat`     | `console`           | `console` (colored stdout) or `json` (GCP Cloud Logging) |
-| `logLevel`      | `info`              | `trace` / `debug` / `info` / `warn` / `error`            |
-| `sentryDsn`     | unset               | Sentry DSN (preferred over env `SENTRY_DSN`)             |
-
-When `sentryDsn` is set, mama sends Sentry events with sensitive prompt/tool content redacted before upload.
-
-### GCP Cloud Logging (Compute Engine)
-
-Set `logFormat: "json"` to send structured logs directly to Cloud Logging via API — no Ops Agent or log file configuration needed.
+| Field                  | Default             | Description                                              |
+| ---------------------- | ------------------- | -------------------------------------------------------- |
+| `llm.provider`         | `anthropic`         | AI provider                                              |
+| `llm.model`            | `claude-sonnet-4-6` | Model name                                               |
+| `llm.thinkingLevel`    | `off`               | `off` / `low` / `medium` / `high`                        |
+| `log.format`           | `console`           | `console` (colored stdout) or `json` (GCP Cloud Logging) |
+| `log.level`            | `info`              | `trace` / `debug` / `info` / `warn` / `error`            |
+| `sentry.dsn`           | unset               | Sentry DSN; sensitive prompt/tool content is redacted    |
+| `sandbox.cpus`         | unset               | CPU limit for managed containers                         |
+| `sandbox.memory`       | unset               | Memory limit for managed containers                      |
+| `sandbox.boost.cpus`   | unset               | Temporary CPU limit used by `/pi-sandbox boost`          |
+| `sandbox.boost.memory` | unset               | Temporary memory limit used by `/pi-sandbox boost`       |
 
-**Requirements:**
+`/pi-sandbox` shows the current managed-container CPU/memory limits. `/pi-sandbox boost` temporarily applies `sandbox.boost` to the current conversation; the boost ends when that sandbox container is stopped.
 
-1. VM service account has `roles/logging.logWriter`
-2. `GOOGLE_CLOUD_PROJECT` env var is set
-
-```bash
-GOOGLE_CLOUD_PROJECT=<your-project-id> mama <working-directory>
-```
-
-`settings.json`:
+Conversation-local settings written by `/pi-model` use the same shape and usually only include the override:
 
 ```json
 {
-  "logFormat": "json",
-  "logLevel": "info"
+  "llm": {
+    "provider": "anthropic",
+    "model": "claude-sonnet-4-6",
+    "thinkingLevel": "off"
+  }
 }
 ```
 
-Logs appear in Cloud Logging under **Log name: `mama`**. Console output (stdout) is unaffected and continues to work alongside Cloud Logging.
+For GCP Cloud Logging, set `log.format: "json"`, give the VM service account `roles/logging.logWriter`, and export `GOOGLE_CLOUD_PROJECT`. Logs land under log name `mama`.
 
-## Working Directory Layout
+## Layout
 
 ```
+<state-dir>/
+├── settings.json
+└── vaults/
+    └── <vault-id>/
+        ├── env
+        └── ...                # credential files
+
 <working-directory>/
-├── settings.json          # AI provider/model/Sentry config
-├── MEMORY.md              # Global memory (all channels)
-├── SYSTEM.md              # Installed packages / env changes log
-├── skills/                # Global skills (CLI tools)
-├── events/                # Scheduled event files
-└── <channel-id>/
-    ├── MEMORY.md          # Channel-specific memory
-    ├── log.jsonl          # Full message history
-    ├── attachments/       # Downloaded user files
-    ├── scratch/           # Agent working directory
-    ├── skills/            # Channel-specific skills
+├── MEMORY.md                  # global memory
+├── SYSTEM.md                  # installed packages / env log
+├── skills/                    # global skills
+├── events/                    # scheduled events
+└── <conversation-id>/
+    ├── MEMORY.md
+    ├── auto-reply[.disabled]    # optional channel auto-reply rules
+    ├── log.jsonl
+    ├── attachments/
+    ├── scratch/
+    ├── skills/
     └── sessions/
-        ├── current                      # Pointer for the channel-level session
-        ├── 2026-04-05T18-04-31-010Z_1d92b3ad.jsonl
-        └── <thread-ts>.jsonl            # Fixed-path thread session
 ```
 
-## Docker Sandbox
-
-```bash
-# Create a container (mount your working directory to /workspace)
-docker run -d --name mama-sandbox \
-  -v /path/to/workspace:/workspace \
-  alpine:latest sleep infinity
-
-# Start mama with Docker sandbox
-mama --sandbox=docker:mama-sandbox /path/to/workspace
-```
+## Events
 
-## Firecracker Sandbox
+Drop JSON files into `<working-directory>/events/`:
 
-Firecracker provides lightweight VM isolation with the security benefits of a hypervisor. Unlike Docker containers, Firecracker runs a full Linux kernel, providing stronger isolation.
+```json
+// Immediate
+{"type": "immediate", "platform": "slack", "conversationId": "C0123456789", "conversationKind": "shared", "text": "Deploy finished"}
 
-### Requirements
+// One-shot
+{"type": "one-shot", "platform": "telegram", "conversationId": "574247312", "conversationKind": "direct", "text": "Standup", "at": "2025-12-15T09:00:00+08:00"}
 
-- SSH access to the Firecracker VM
-- SSH key-based authentication configured
-- Host workspace must be mounted at `/workspace` inside the VM
+// Periodic (cron)
+{"type": "periodic", "platform": "discord", "conversationId": "1498975469343739948", "conversationKind": "shared", "text": "Check inbox", "schedule": "0 9 * * 1-5", "timezone": "Asia/Taipei"}
+```
 
-### Format
+## Skills
 
 ```
---sandbox=firecracker:<vm-id>:<host-path>[:<ssh-user>[:<ssh-port>]]
+skills/my-tool/
+├── SKILL.md      # name + description frontmatter, usage docs
+└── run.sh
 ```
 
-| Parameter   | Default | Description                    |
-| ----------- | ------- | ------------------------------ |
-| `vm-id`     | -       | VM identifier (hostname or IP) |
-| `host-path` | -       | Working directory on the host  |
-| `ssh-user`  | `root`  | SSH username                   |
-| `ssh-port`  | `22`    | SSH port                       |
-
-### Examples
-
-```bash
-# Basic usage (VM at 192.168.1.100, default ssh user root:22)
-mama --sandbox=firecracker:192.168.1.100:/home/user/workspace /home/user/workspace
-
-# Custom SSH user
-mama --sandbox=firecracker:192.168.1.100:/home/user/workspace:ubuntu /home/user/workspace
+```yaml
+---
+name: my-tool
+description: Does something useful
+---
 
-# Custom SSH port
-mama --sandbox=firecracker:192.168.1.100:/home/user/workspace:root:2222 /home/user/workspace
+Usage: {baseDir}/run.sh <args>
 ```
 
-### Setup
-
-1. **Start a Firecracker VM** with your preferred method (fc-agent, firecracker-ctl, or manual)
-
-2. **Configure SSH access** inside the VM:
-
-   ```bash
-   # Inside the VM - allow password-less SSH for mama
-   sudo systemctl enable ssh
-   sudo sed -i 's/^#*PermitRootLogin.*/PermitRootLogin yes/' /etc/ssh/sshd_config
-   sudo sed -i 's/^#*PubkeyAuthentication.*/PubkeyAuthentication yes/' /etc/ssh/sshd_config
-   sudo systemctl restart ssh
-   ```
+## Slack: Download channel history
 
-3. **Mount your workspace** at `/workspace` inside the VM:
-
-   ```bash
-   # Option A: 9pfs (recommended, from host)
-   sudo mount -t 9p -o trans=virtio,version=9p2000.L host0 /workspace
-
-   # Option B: NFS
-   sudo mount -t nfs <host-ip>:/path/to/workspace /workspace
-   ```
-
-4. **Test SSH connectivity** from host:
-   ```bash
-   ssh root@192.168.1.100 "echo works"
-   ```
+```bash
+mama --download C0123456789
+```
 
-The host path is mounted as `/workspace` inside the Firecracker VM. All bash commands will execute inside the VM.
+## Production deployment (PM2)
 
-## Events
+For long-running deployments, use [PM2](https://pm2.keymetrics.io/) as a process supervisor. It daemonizes mama, restarts on crash, and survives reboots.
 
-Drop JSON files into `<working-directory>/events/` to trigger the agent:
-
-```json
-// Immediate — triggers as soon as mama sees the file
-{"type": "immediate", "channelId": "C0123456789", "text": "New deployment finished"}
+```bash
+# 1. Install mama and pm2
+npm i -g @geminixiang/mama pm2
 
-// One-shot — triggers once at a specific time
-{"type": "one-shot", "channelId": "C0123456789", "text": "Daily standup reminder", "at": "2025-12-15T09:00:00+08:00"}
+# 2. Start the sandbox container (long-lived; mama execs into it)
+docker pull ghcr.io/geminixiang/mama-sandbox:latest
 
-// Periodic — triggers on a cron schedule
-{"type": "periodic", "channelId": "C0123456789", "text": "Check inbox", "schedule": "0 9 * * 1-5", "timezone": "Asia/Taipei"}
+# 3. Grab the ecosystem file, edit args + env tokens, then start
+curl -O https://raw.githubusercontent.com/geminixiang/mama/main/deploy/pm2/ecosystem.config.cjs
+pm2 start ecosystem.config.cjs
+pm2 save
+pm2 startup        # run the printed command to enable boot autostart
 ```
 
-## Skills
-
-Create reusable CLI tools by adding a directory with a `SKILL.md`:
+Upgrade flow:
 
-```
-skills/
-└── my-tool/
-    ├── SKILL.md    # name + description frontmatter, usage docs
-    └── run.sh      # the actual script
+```bash
+npm i -g @geminixiang/mama && pm2 reload mama
 ```
 
-`SKILL.md` frontmatter:
+`pm2 reload` sends SIGTERM and waits up to `kill_timeout` (60s in the shipped config) before SIGKILL. mama's internal graceful shutdown drains in-flight LLM turns within that window, so reloads do not interrupt active conversations.
 
-```yaml
----
-name: my-tool
-description: Does something useful
----
-
-Usage: {baseDir}/run.sh <args>
-```
+See [`deploy/pm2/ecosystem.config.cjs`](deploy/pm2/ecosystem.config.cjs) for all tunables.
 
 ## Development
 
 ```bash
 npm run dev     # watch mode
-npm test        # run tests
-npm run build   # production build
+npm test
+npm run build
 ```
 
-## 📦 Dependencies & Versions
-
-| Package                         | mama Version | pi-mom Synced Version         |
-| ------------------------------- | ------------ | ----------------------------- |
-| `@mariozechner/pi-agent-core`   | `^0.57.1`    | ✅ Synchronized               |
-| `@mariozechner/pi-ai`           | `^0.57.1`    | ✅ Synchronized               |
-| `@mariozechner/pi-coding-agent` | `^0.57.1`    | ✅ Synchronized               |
-| `@anthropic-ai/sandbox-runtime` | `^0.0.40`    | ⚠️ Newer (pi-mom uses 0.0.16) |
-
 ## License
 
-MIT — see [LICENSE](LICENSE).
-
-**Note**: This project inherits the MIT license from pi-mom and aims to keep its contributions compatible with the upstream ecosystem.
+MIT — see [LICENSE](LICENSE). Inherits from pi-mom.