@openparachute/agent 0.1.0

package/README.md

@@ -0,0 +1,190 @@
+# parachute-agent
+
+<p align="center">
+  An AI assistant that runs agents securely in their own containers. Lightweight, built to be easily understood and completely customized for your needs. A [Parachute](https://parachute.computer) module.
+</p>
+
+<p align="center">
+  <a href="https://parachute.computer">parachute.computer</a>&nbsp; • &nbsp;
+  <a href="docs/">docs</a>&nbsp; • &nbsp;
+  <a href="README_zh.md">中文</a>&nbsp; • &nbsp;
+  <a href="README_ja.md">日本語</a>
+</p>
+
+---
+
+## Why parachute-agent
+
+Most AI-assistant frameworks fall into one of two camps: heavyweight platforms with hundreds of thousands of lines of code, dozens of config files, and security at the application layer (allowlists, pairing codes); or DIY scripts with no isolation at all. Both ask you to either trust software you can't read, or hand the agent direct access to your machine.
+
+parachute-agent runs each agent group in its own Linux container with filesystem isolation, in a codebase small enough to read in an afternoon — one process and a handful of files. Bash access is safe because commands run inside the container, not on your host. The user's [Parachute Vault](https://github.com/ParachuteComputer/parachute-vault) is the agent's substrate: scoped vault tokens grant exactly the read/write surface you choose, and credentials live in a local AES-GCM-encrypted store, never round-tripped through chat context.
+
+## Quick Start
+
+parachute-agent is a [Parachute](https://parachute.computer) module — install it through the hub and configure it from the web UI:
+
+```bash
+parachute install parachute-agent
+```
+
+The hub builds the agent container, brings the host process up under `bun src/index.ts`, and serves the configuration UI at `http://127.0.0.1:1944/agent/`. From there: drop in your Anthropic API key, pick a channel (Telegram, Discord, or the local CLI), and pair your first agent — no shell scripts required. See [`docs/parachute-integration.md`](docs/parachute-integration.md) for the full Parachute path.
+
+## Philosophy
+
+**Small enough to understand.** One process, a few source files and no microservices. If you want to understand the full parachute-agent codebase, just ask Claude Code to walk you through it.
+
+**Secure by isolation.** Agents run in Linux containers and they can only see what's explicitly mounted. Bash access is safe because commands run inside the container, not on your host.
+
+**Built for the individual user.** parachute-agent isn't a monolithic framework; it's software that fits each user's exact needs. Instead of becoming bloatware, parachute-agent is designed to be bespoke. You make your own fork and have Claude Code modify it to match your needs.
+
+**Customization = code changes.** No configuration sprawl. Want different behavior? Modify the code. The codebase is small enough that it's safe to make changes.
+
+**AI-native, hybrid by design.** The install and onboarding flow is an optimized scripted path, fast and deterministic. When a step needs judgment, whether a failed install, a guided decision, or a customization, control hands off to Claude Code seamlessly. Beyond setup there's no monitoring dashboard or debugging UI either: describe the problem in chat and Claude Code handles it.
+
+**Skills over features.** Trunk ships the registry and infrastructure, not specific channel adapters or alternative agent providers. Channels (Discord, Slack, Telegram, WhatsApp, …) live on a long-lived `channels` branch; alternative providers (OpenCode, Ollama) live on `providers`. You run `/add-telegram`, `/add-opencode`, etc. and the skill copies exactly the module(s) you need into your fork. No feature you didn't ask for.
+
+**Best harness, best model.** parachute-agent natively uses Claude Code via Anthropic's official Claude Agent SDK, so you get the latest Claude models and Claude Code's full toolset, including the ability to modify and expand your own parachute-agent fork. Other providers are drop-in options: `/add-codex` for OpenAI's Codex (ChatGPT subscription or API key), `/add-opencode` for OpenRouter, Google, DeepSeek and more via OpenCode, and `/add-ollama-provider` for local open-weight models. Provider is configurable per agent group.
+
+## What It Supports
+
+- **Multi-channel messaging** — WhatsApp, Telegram, Discord, Slack, Microsoft Teams, iMessage, Matrix, Google Chat, Webex, Linear, GitHub, WeChat, and email via Resend. Installed on demand with `/add-<channel>` skills. Run one or many at the same time.
+- **Flexible isolation** — connect each channel to its own agent for full privacy, share one agent across many channels for unified memory with separate conversations, or fold multiple channels into a single shared session so one conversation spans many surfaces. Pick per channel via `/manage-channels`. See [docs/isolation-model.md](docs/isolation-model.md).
+- **Per-agent workspace** — each agent group has its own `CLAUDE.md`, its own memory, its own container, and only the mounts you allow. Nothing crosses the boundary unless you wire it to.
+- **Scheduled tasks** — recurring jobs that run Claude and can message you back
+- **Web access** — search and fetch content from the web
+- **Container isolation** — agents are sandboxed in Docker (macOS/Linux/WSL2), with optional [Docker Sandboxes](docs/docker-sandboxes.md) micro-VM isolation or Apple Container as a macOS-native opt-in
+- **Credential security** — agents never hold raw API keys. parachute-agent stores credentials in a local AES-GCM-encrypted secret store (`~/.parachute/agent/master.key` + the central DB), injects them into the container's environment at spawn time, and never round-trips them through chat context.
+
+## Usage
+
+Talk to your assistant with the trigger word (default: `@Andy`):
+
+```
+@Andy send an overview of the sales pipeline every weekday morning at 9am (has access to my Obsidian vault folder)
+@Andy review the git history for the past week each Friday and update the README if there's drift
+@Andy every Monday at 8am, compile news on AI developments from Hacker News and TechCrunch and message me a briefing
+```
+
+From a channel you own or administer, you can manage groups and tasks:
+```
+@Andy list all scheduled tasks across groups
+@Andy pause the Monday briefing task
+@Andy join the Family Chat group
+```
+
+## Customizing
+
+parachute-agent doesn't use configuration files. To make changes, just tell Claude Code what you want:
+
+- "Change the trigger word to @Bob"
+- "Remember in the future to make responses shorter and more direct"
+- "Add a custom greeting when I say good morning"
+- "Store conversation summaries weekly"
+
+Or run `/customize` for guided changes.
+
+The codebase is small enough that Claude can safely modify it.
+
+## Contributing
+
+**Don't add features. Add skills.**
+
+If you want to add a new channel or agent provider, don't add it to trunk. New channel adapters land on the `channels` branch; new agent providers land on `providers`. Users install them in their own fork with `/add-<name>` skills, which copy the relevant module(s) into the standard paths, wire the registration, and pin dependencies.
+
+This keeps trunk as pure registry and infra, and every fork stays lean — users get the channels and providers they asked for and nothing else.
+
+### RFS (Request for Skills)
+
+Skills we'd like to see:
+
+**Communication Channels**
+- `/add-signal` — Add Signal as a channel
+
+## Requirements
+
+- macOS or Linux (Windows via WSL2)
+- Node.js 20+ and pnpm 10+ (the installer will install both if missing)
+- [Docker Desktop](https://docker.com/products/docker-desktop) (macOS/Windows) or Docker Engine (Linux)
+- [Claude Code](https://claude.ai/download) for `/customize`, `/debug`, error recovery during setup, and all `/add-<channel>` skills
+
+## Architecture
+
+```
+messaging apps → host process (router) → inbound.db → container (Bun, Claude Agent SDK) → outbound.db → host process (delivery) → messaging apps
+```
+
+A single Node host orchestrates per-session agent containers. When a message arrives, the host routes it via the entity model (user → messaging group → agent group → session), writes it to the session's `inbound.db`, and wakes the container. The agent-runner inside the container polls `inbound.db`, runs Claude, and writes responses to `outbound.db`. The host polls `outbound.db` and delivers back through the channel adapter.
+
+Two SQLite files per session, each with exactly one writer — no cross-mount contention, no IPC, no stdin piping. Channels and alternative providers self-register at startup; trunk ships the registry and the Chat SDK bridge, while the adapters themselves are skill-installed per fork.
+
+For the full architecture writeup see [docs/architecture.md](docs/architecture.md); for the three-level isolation model see [docs/isolation-model.md](docs/isolation-model.md).
+
+Key files:
+- `src/index.ts` — entry point: DB init, channel adapters, delivery polls, sweep
+- `src/router.ts` — inbound routing: messaging group → agent group → session → `inbound.db`
+- `src/delivery.ts` — polls `outbound.db`, delivers via adapter, handles system actions
+- `src/host-sweep.ts` — 60s sweep: stale detection, due-message wake, recurrence
+- `src/session-manager.ts` — resolves sessions, opens `inbound.db` / `outbound.db`
+- `src/container-runner.ts` — spawns per-agent-group containers, injects encrypted secrets at spawn
+- `src/db/` — central DB (users, roles, agent groups, messaging groups, wiring, migrations)
+- `src/channels/` — channel adapter infra (adapters installed via `/add-<channel>` skills)
+- `src/providers/` — host-side provider config (`claude` baked in; others via skills)
+- `container/agent-runner/` — Bun agent-runner: poll loop, MCP tools, provider abstraction
+- `groups/<folder>/` — per-agent-group filesystem (`CLAUDE.md`, skills, container config)
+
+## FAQ
+
+**Why Docker?**
+
+Docker provides cross-platform support (macOS, Linux and Windows via WSL2) and a mature ecosystem. On macOS, you can optionally switch to Apple Container via `/convert-to-apple-container` for a lighter-weight native runtime. For additional isolation, [Docker Sandboxes](docs/docker-sandboxes.md) run each container inside a micro VM.
+
+**Can I run this on Linux or Windows?**
+
+Yes. Docker is the default runtime and works on macOS, Linux, and Windows (via WSL2). Install via the Parachute hub: `parachute install parachute-agent`.
+
+**Is this secure?**
+
+Agents run in containers, not behind application-level permission checks. They can only access explicitly mounted directories. Credentials live in parachute-agent's AES-GCM-encrypted secret store (master key at `~/.parachute/agent/master.key`, ciphertext in the central DB), injected into each container at spawn time and scoped per agent group. You should still review what you're running, but the codebase is small enough that you actually can.
+
+**Why no configuration files?**
+
+We don't want configuration sprawl. Every user should customize parachute-agent so that the code does exactly what they want, rather than configuring a generic system. If you prefer having config files, you can tell Claude to add them.
+
+**Can I use third-party or open-source models?**
+
+Yes. The supported path is `/add-opencode` (OpenRouter, OpenAI, Google, DeepSeek, and more via OpenCode config) or `/add-ollama-provider` (local open-weight models via Ollama). Both are configurable per agent group, so different agents can run on different backends in the same install.
+
+For one-off experiments, any Claude API-compatible endpoint also works via `.env`:
+
+```bash
+ANTHROPIC_BASE_URL=https://your-api-endpoint.com
+ANTHROPIC_AUTH_TOKEN=your-token-here
+```
+
+**How do I debug issues?**
+
+Ask Claude Code. "Why isn't the scheduler running?" "What's in the recent logs?" "Why did this message not get a response?" That's the AI-native approach that underlies parachute-agent.
+
+**Why isn't the setup working for me?**
+
+If a step fails, run `claude`, then `/debug`. If Claude identifies an issue likely to affect other users, open a PR against the relevant setup step or skill.
+
+**What changes will be accepted into the codebase?**
+
+Only security fixes, bug fixes, and clear improvements will be accepted to the base configuration. That's all.
+
+Everything else (new capabilities, OS compatibility, hardware support, enhancements) should be contributed as skills on the `channels` or `providers` branch.
+
+This keeps the base system minimal and lets every user customize their installation without inheriting features they don't want.
+
+## Community
+
+Questions? Ideas? [Join the Discord](https://discord.gg/VDdww8qS42).
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for breaking changes.
+
+## License
+
+MIT

package/README_ja.md

@@ -0,0 +1,194 @@
+<p align="center">
+  <img src="assets/nanoclaw-logo.png" alt="NanoClaw" width="400">
+</p>
+
+<p align="center">
+  エージェントを専用コンテナで安全に実行するAIアシスタント。軽量で、理解しやすく、あなたのニーズに完全にカスタマイズできるように設計されています。
+</p>
+
+<p align="center">
+  <a href="https://nanoclaw.dev">nanoclaw.dev</a>&nbsp; • &nbsp;
+  <a href="https://docs.nanoclaw.dev">ドキュメント</a>&nbsp; • &nbsp;
+  <a href="README.md">English</a>&nbsp; • &nbsp;
+  <a href="README_zh.md">中文</a>&nbsp; • &nbsp;
+  <a href="https://discord.gg/VDdww8qS42"><img src="https://img.shields.io/discord/1470188214710046894?label=Discord&logo=discord&v=2" alt="Discord" valign="middle"></a>&nbsp; • &nbsp;
+  <a href="repo-tokens"><img src="repo-tokens/badge.svg" alt="repo tokens" valign="middle"></a>
+</p>
+
+---
+
+## NanoClawを作った理由
+
+[OpenClaw](https://github.com/openclaw/openclaw)は素晴らしいプロジェクトですが、自分が理解しきれない複雑なソフトウェアに生活へのフルアクセスを与えたまま安心して眠れるとは思えませんでした。OpenClawは約50万行のコード、53の設定ファイル、70以上の依存関係を持っています。セキュリティはアプリケーションレベル（許可リスト、ペアリングコード）であり、真のOSレベルの分離ではありません。すべてが共有メモリを持つ1つのNodeプロセスで動作します。
+
+NanoClawは同じコア機能を提供しますが、理解できる規模のコードベースで実現しています。1つのプロセスと少数のファイル。Claudeエージェントは単なるパーミッションチェックの背後ではなく、ファイルシステム分離された独自のLinuxコンテナで実行されます。
+
+## クイックスタート
+
+```bash
+git clone https://github.com/qwibitai/nanoclaw.git nanoclaw-v2
+cd nanoclaw-v2
+bash nanoclaw.sh
+```
+
+`nanoclaw.sh`は、まっさらなマシンから、メッセージを送れる名前付きエージェントが動く状態までを一気通貫で案内します。NodeやpnpmやDockerが無ければインストールし、AnthropicクレデンシャルをOneCLIに登録し、エージェントコンテナをビルドし、最初のチャネル（Telegram、Discord、WhatsApp、またはローカルCLI）とペアリングします。途中でステップが失敗すれば自動的にClaude Codeが呼び出され、原因を診断して中断箇所から再開します。
+
+## 設計思想
+
+**理解できる規模。** 1つのプロセス、少数のソースファイル、マイクロサービスなし。NanoClawのコードベース全体を把握したいなら、Claude Codeに説明を求めれば十分です。
+
+**分離によるセキュリティ。** エージェントはLinuxコンテナで実行され、明示的にマウントされたものだけが見えます。コマンドはホストではなくコンテナ内で実行されるため、Bashアクセスも安全です。
+
+**個人ユーザー向け。** NanoClawはモノリシックなフレームワークではなく、各ユーザーのニーズに正確にフィットするソフトウェアです。肥大化するのではなく、オーダーメイドであるよう設計されています。自分のフォークを作り、Claude Codeにニーズに合わせて変更させます。
+
+**カスタマイズ＝コード変更。** 設定の肥大化はありません。動作を変えたいならコードを変える。コードベースは変更しても安全な規模です。
+
+**AIネイティブ、設計としてハイブリッド。** インストールとオンボーディングは最適化されたスクリプトのパスで、速く決定的です。判断が必要なところ（インストール失敗、対話的な決定、カスタマイズ）では、制御はシームレスにClaude Codeへ渡されます。セットアップ以降も、監視ダッシュボードやデバッグUIは用意しません。問題をチャットで説明すれば、Claude Codeが処理します。
+
+**機能ではなくスキル。** トランクにはレジストリとインフラのみを同梱し、個別のチャネルアダプターや代替プロバイダーは含めません。チャネル（Discord、Slack、Telegram、WhatsAppなど）は長期運用される`channels`ブランチに、代替プロバイダー（OpenCode、Ollama）は`providers`ブランチに置かれます。`/add-telegram`や`/add-opencode`などを実行すると、スキルが必要なモジュールだけを正確にフォークへコピーします。要求していない機能は一切入りません。
+
+**最高のハーネス、最高のモデル。** NanoClawはAnthropic公式のClaude Agent SDK経由でネイティブにClaude Codeを使用します。最新のClaudeモデルとClaude Codeの全ツールセット（自分のNanoClawフォークを変更・拡張する能力を含む）が手に入ります。他プロバイダーはドロップイン・オプションです。OpenAIのCodex（ChatGPTサブスクリプションまたはAPIキー）向けには`/add-codex`、OpenCode経由のOpenRouter、Google、DeepSeekなどには`/add-opencode`、ローカルのオープンウェイトモデルには`/add-ollama-provider`。プロバイダーはエージェントグループごとに設定可能です。
+
+## サポート機能
+
+- **マルチチャネルメッセージング** — WhatsApp、Telegram、Discord、Slack、Microsoft Teams、iMessage、Matrix、Google Chat、Webex、Linear、GitHub、WeChat、Resend経由のメール。`/add-<channel>`スキルでオンデマンドにインストール。1つでも複数でも同時に実行可能。
+- **柔軟な分離モデル** — チャネルごとに専用エージェントを割り当てて完全プライバシーを確保することも、複数チャネルで1つのエージェントを共有して会話は分離しつつメモリを統一することも、複数チャネルを1つの共有セッションにまとめて会話を横断させることもできます。`/manage-channels`でチャネル単位に選択。[docs/isolation-model.md](docs/isolation-model.md)参照。
+- **エージェントごとのワークスペース** — 各エージェントグループは独自の`CLAUDE.md`、独自のメモリ、独自のコンテナ、そしてあなたが許可したマウントのみを持ちます。明示的に配線しない限り、境界を越えるものはありません。
+- **スケジュールタスク** — Claudeを実行し、結果を返信できる定期ジョブ。
+- **Webアクセス** — Webからの検索とコンテンツ取得。
+- **コンテナ分離** — エージェントはDockerでサンドボックス化されます（macOS/Linux/WSL2）。[Docker Sandboxes](docs/docker-sandboxes.md)によるマイクロVM分離や、macOSネイティブのオプトインとしてApple Containerも選択可能です。
+- **クレデンシャルのセキュリティ** — エージェントは生のAPIキーを保持しません。アウトバウンドリクエストは[OneCLI Agent Vault](https://github.com/onecli/onecli)を経由し、リクエスト時に認証情報を注入して、エージェントごとのポリシーとレート制限を適用します。
+
+## 使い方
+
+トリガーワード（デフォルト：`@Andy`）でアシスタントに話しかけます：
+
+```
+@Andy 毎朝9時に営業パイプラインの概要を送って（Obsidian vaultフォルダにアクセス可能）
+@Andy 毎週金曜に過去1週間のgit履歴をレビューして、差異があればREADMEを更新して
+@Andy 毎週月曜の朝8時に、Hacker NewsとTechCrunchからAI関連のニュースをまとめてブリーフィングを送って
+```
+
+所有または管理しているチャネルからは、グループやタスクを管理できます：
+```
+@Andy 全グループのスケジュールタスクを一覧表示して
+@Andy 月曜のブリーフィングタスクを一時停止して
+@Andy Family Chatグループに参加して
+```
+
+## カスタマイズ
+
+NanoClawは設定ファイルを使いません。変更したいときは、Claude Codeにやりたいことを伝えるだけです：
+
+- 「トリガーワードを@Bobに変更して」
+- 「今後はレスポンスをもっと短く直接的にして」
+- 「おはようと言ったらカスタム挨拶を追加して」
+- 「会話の要約を毎週保存して」
+
+または`/customize`を実行すればガイド付きで変更できます。
+
+コードベースは十分に小さいため、Claudeが安全に変更できます。
+
+## コントリビューション
+
+**機能を追加するのではなく、スキルを追加してください。**
+
+新しいチャネルやエージェントプロバイダーを追加したい場合、トランクには追加しないでください。新しいチャネルアダプターは`channels`ブランチに、新しいエージェントプロバイダーは`providers`ブランチに追加します。ユーザーはそれぞれのフォークで`/add-<name>`スキルを実行し、スキルが必要なモジュールを標準パスへコピーし、登録を配線し、依存関係をピン留めします。
+
+こうすることでトランクは純粋なレジストリ／インフラのまま保たれ、どのフォークもスリムなままです。ユーザーは求めたチャネルとプロバイダーだけを受け取り、それ以外は入りません。
+
+### RFS（スキル募集）
+
+私たちが見たいスキル：
+
+**コミュニケーションチャネル**
+- `/add-signal` — Signalをチャネルとして追加
+
+## 必要条件
+
+- macOSまたはLinux（WindowsはWSL2経由）
+- Node.js 20以上とpnpm 10以上（インストーラーが未インストールなら両方をインストールします）
+- [Docker Desktop](https://docker.com/products/docker-desktop)（macOS/Windows）または Docker Engine（Linux）
+- [Claude Code](https://claude.ai/download)（`/customize`、`/debug`、セットアップ時のエラー復旧、全ての`/add-<channel>`スキルで使用）
+
+## アーキテクチャ
+
+```
+メッセージングアプリ → ホストプロセス（ルーター） → inbound.db → コンテナ（Bun、Claude Agent SDK） → outbound.db → ホストプロセス（配信） → メッセージングアプリ
+```
+
+単一のNodeホストがセッションごとのエージェントコンテナをオーケストレーションします。メッセージが到着すると、ホストはエンティティモデル（ユーザー → メッセージンググループ → エージェントグループ → セッション）に沿ってルーティングし、セッションの`inbound.db`に書き込み、コンテナを起こします。コンテナ内部のagent-runnerは`inbound.db`をポーリングしてClaudeを実行し、レスポンスを`outbound.db`に書き込みます。ホストは`outbound.db`をポーリングし、チャネルアダプターを通じて配信します。
+
+セッションごとに2つのSQLiteファイル、各ファイルにライターは1つだけ — クロスマウントの競合なし、IPCなし、stdinパイプなし。チャネルと代替プロバイダーは起動時に自己登録します。トランクはレジストリとChat SDKブリッジを同梱し、アダプター本体はフォークごとにスキルでインストールされます。
+
+詳しいアーキテクチャ説明は[docs/architecture.md](docs/architecture.md)を、3階層の分離モデルについては[docs/isolation-model.md](docs/isolation-model.md)を参照してください。
+
+主要ファイル：
+- `src/index.ts` — エントリーポイント：DB初期化、チャネルアダプター、配信ポーリング、sweep
+- `src/router.ts` — インバウンドルーティング：メッセージンググループ → エージェントグループ → セッション → `inbound.db`
+- `src/delivery.ts` — `outbound.db`をポーリングし、アダプター経由で配信、システムアクションを処理
+- `src/host-sweep.ts` — 60秒ごとのsweep：ストール検出、期限到来メッセージの起動、繰り返し
+- `src/session-manager.ts` — セッションの解決、`inbound.db`と`outbound.db`のオープン
+- `src/container-runner.ts` — エージェントグループごとのコンテナ起動、OneCLIによるクレデンシャル注入
+- `src/db/` — セントラルDB（ユーザー、ロール、エージェントグループ、メッセージンググループ、配線、マイグレーション）
+- `src/channels/` — チャネルアダプターのインフラ（アダプターは`/add-<channel>`スキルでインストール）
+- `src/providers/` — ホスト側プロバイダー設定（`claude`はバンドル、その他はスキル経由）
+- `container/agent-runner/` — Bun製agent-runner：ポーリングループ、MCPツール、プロバイダー抽象化
+- `groups/<folder>/` — エージェントグループごとのファイルシステム（`CLAUDE.md`、スキル、コンテナ設定）
+
+## FAQ
+
+**なぜDockerなのか？**
+
+Dockerはクロスプラットフォーム対応（macOS、Linux、WSL2経由のWindows）と成熟したエコシステムを提供します。macOSでは、`/convert-to-apple-container`でオプションとしてApple Containerに切り替え、より軽量なネイティブランタイムを使えます。さらに強い分離が必要なら、[Docker Sandboxes](docs/docker-sandboxes.md)が各コンテナをマイクロVM内で動作させます。
+
+**LinuxやWindowsで実行できますか？**
+
+はい。Dockerがデフォルトのランタイムで、macOS、Linux、Windows（WSL2経由）で動作します。`bash nanoclaw.sh`を実行するだけです。
+
+**セキュリティは大丈夫ですか？**
+
+エージェントはアプリケーションレベルのパーミッションチェックではなく、コンテナ内で実行されます。明示的にマウントされたディレクトリのみアクセス可能です。クレデンシャルはコンテナに渡されず、アウトバウンドAPIリクエストは[OneCLI Agent Vault](https://github.com/onecli/onecli)を経由し、プロキシレベルで認証を注入し、レートリミットやアクセスポリシーをサポートします。実行するものはレビューすべきですが、コードベースは実際にレビュー可能な規模です。完全なセキュリティモデルについては[セキュリティドキュメント](https://docs.nanoclaw.dev/concepts/security)を参照してください。
+
+**なぜ設定ファイルがないのか？**
+
+設定の肥大化を避けたいからです。すべてのユーザーがNanoClawをカスタマイズし、汎用的なシステムを設定するのではなくコードが自分の望み通りに動くようにすべきです。設定ファイルが欲しければClaudeに追加するよう伝えれば実現できます。
+
+**サードパーティやオープンソースモデルを使えますか？**
+
+はい。推奨される方法は`/add-opencode`（OpenCode設定経由でOpenRouter、OpenAI、Google、DeepSeekなど）か`/add-ollama-provider`（Ollama経由でローカルのオープンウェイトモデル）です。どちらもエージェントグループごとに設定可能なので、同じインストール内で異なるエージェントが異なるバックエンドで動作できます。
+
+一時的な実験用には、Claude API互換のエンドポイントも`.env`で利用できます：
+
+```bash
+ANTHROPIC_BASE_URL=https://your-api-endpoint.com
+ANTHROPIC_AUTH_TOKEN=your-token-here
+```
+
+**問題のデバッグ方法は？**
+
+Claude Codeに聞いてください。「スケジューラーが動いていないのはなぜ？」「最近のログには何がある？」「このメッセージに返信がなかったのはなぜ？」これがNanoClawの基盤となるAIネイティブなアプローチです。
+
+**セットアップがうまくいかない場合は？**
+
+ステップが失敗した場合、`nanoclaw.sh`は診断と再開のためにClaude Codeへ制御を渡します。それでも解決しなければ、`claude`を実行して`/debug`を呼び出してください。他のユーザーにも影響しそうな問題をClaudeが特定した場合は、該当のセットアップステップまたはスキルにPRを送ってください。
+
+**どのような変更がコードベースに受け入れられますか？**
+
+ベース設定に受け入れられるのは、セキュリティ修正、バグ修正、明確な改善のみです。それだけです。
+
+それ以外（新機能、OS互換性、ハードウェアサポート、拡張など）は、`channels`または`providers`ブランチのスキルとしてコントリビュートしてください。
+
+これにより、ベースシステムを最小限に保ち、全ユーザーが不要な機能を継承することなく自分のインストールをカスタマイズできます。
+
+## コミュニティ
+
+質問やアイデアがありますか？[Discordに参加](https://discord.gg/VDdww8qS42)してください。
+
+## 変更履歴
+
+破壊的変更については[CHANGELOG.md](CHANGELOG.md)を、完全なリリース履歴はドキュメントサイトの[full release history](https://docs.nanoclaw.dev/changelog)を参照してください。
+
+## ライセンス
+
+MIT

package/README_zh.md

@@ -0,0 +1,194 @@
+<p align="center">
+  <img src="assets/nanoclaw-logo.png" alt="NanoClaw" width="400">
+</p>
+
+<p align="center">
+  一个将智能体安全运行在独立容器中的 AI 助手。轻量、易于理解，并可根据您的需求完全定制。
+</p>
+
+<p align="center">
+  <a href="https://nanoclaw.dev">nanoclaw.dev</a>&nbsp; • &nbsp;
+  <a href="https://docs.nanoclaw.dev">文档</a>&nbsp; • &nbsp;
+  <a href="README.md">English</a>&nbsp; • &nbsp;
+  <a href="README_ja.md">日本語</a>&nbsp; • &nbsp;
+  <a href="https://discord.gg/VDdww8qS42"><img src="https://img.shields.io/discord/1470188214710046894?label=Discord&logo=discord&v=2" alt="Discord" valign="middle"></a>&nbsp; • &nbsp;
+  <a href="repo-tokens"><img src="repo-tokens/badge.svg" alt="repo tokens" valign="middle"></a>
+</p>
+
+---
+
+## 我为什么创建 NanoClaw
+
+[OpenClaw](https://github.com/openclaw/openclaw) 是一个令人印象深刻的项目，但我无法安心使用一个我不了解、却能访问我个人隐私的复杂软件。OpenClaw 有近 50 万行代码、53 个配置文件和 70+ 个依赖项。其安全性是应用级别的（白名单、配对码），而非真正的操作系统级隔离。所有东西都在一个共享内存的 Node 进程中运行。
+
+NanoClaw 用一个您能轻松理解的代码库提供了同样的核心功能：一个进程，少数几个文件。Claude 智能体运行在具有文件系统隔离的独立 Linux 容器中，而不是仅靠权限检查。
+
+## 快速开始
+
+```bash
+git clone https://github.com/qwibitai/nanoclaw.git nanoclaw-v2
+cd nanoclaw-v2
+bash nanoclaw.sh
+```
+
+`nanoclaw.sh` 会把您从一台全新机器一直带到一个可以直接发消息的命名智能体。它会在缺失时安装 Node、pnpm 和 Docker，向 OneCLI 注册您的 Anthropic 凭据，构建智能体容器，并配对您的第一个渠道（Telegram、Discord、WhatsApp 或本地 CLI）。如果某一步失败，会自动调用 Claude Code 进行诊断并从中断处继续。
+
+## 设计哲学
+
+**小到可以理解。** 单一进程，少量源文件，无微服务。如果您想了解完整的 NanoClaw 代码库，直接让 Claude Code 给您讲一遍就行。
+
+**通过隔离实现安全。** 智能体运行在 Linux 容器中，只能看到明确挂载的内容。Bash 访问是安全的，因为命令在容器内执行，而不是在您的宿主机上。
+
+**为个人用户打造。** NanoClaw 不是一个单体框架，而是能精确匹配每个用户需求的软件。它被设计成量身定制的，而不是臃肿膨胀。您创建自己的 fork，让 Claude Code 按您的需求修改它。
+
+**定制 = 修改代码。** 没有配置膨胀。想要不同的行为？改代码。代码库小到改动是安全的。
+
+**AI 原生，混合式设计。** 安装与上手流程走的是经过优化的脚本路径，快速且确定。当某一步需要判断（安装失败、引导决策、定制化）时，控制权会无缝地交给 Claude Code。安装之后也不提供监控仪表盘或调试 UI：您在聊天中描述问题，Claude Code 来处理。
+
+**技能优于功能。** 主干只发布注册表和基础设施，不包含具体的渠道适配器或替代智能体提供者。各个渠道（Discord、Slack、Telegram、WhatsApp……）放在长期存在的 `channels` 分支上；替代提供者（OpenCode、Ollama）放在 `providers` 分支上。您运行 `/add-telegram`、`/add-opencode` 等，技能会把您所需要的模块精确地复制到您的 fork 里。不会出现您没要求的功能。
+
+**最强的 harness，最强的模型。** NanoClaw 通过 Anthropic 官方的 Claude Agent SDK 原生使用 Claude Code，所以您能用上最新的 Claude 模型以及 Claude Code 的完整工具集——包括修改和扩展自己的 NanoClaw fork 的能力。其他提供者是可插拔选项：`/add-codex` 对应 OpenAI 的 Codex（ChatGPT 订阅或 API key），`/add-opencode` 通过 OpenCode 接入 OpenRouter、Google、DeepSeek 等，`/add-ollama-provider` 用于本地开源权重模型。提供者可按智能体组单独配置。
+
+## 功能支持
+
+- **多渠道消息** — WhatsApp、Telegram、Discord、Slack、Microsoft Teams、iMessage、Matrix、Google Chat、Webex、Linear、GitHub、WeChat，以及通过 Resend 的邮件。按需通过 `/add-<channel>` 技能安装。可同时运行一个或多个。
+- **灵活的隔离模式** — 可为每个渠道配一个独立智能体以获得完全隐私，也可让一个智能体在多个渠道上共享、统一记忆但会话独立，或者把多个渠道合并到一个共享会话里，让一场对话横跨多个入口。通过 `/manage-channels` 按渠道选择。详见 [docs/isolation-model.md](docs/isolation-model.md)。
+- **每个智能体的独立工作区** — 每个智能体组都有自己的 `CLAUDE.md`、自己的记忆、自己的容器，以及您允许的挂载点。除非您明确接线，否则不会有东西越过边界。
+- **计划任务** — 运行 Claude 的周期性作业，可以给您回发消息。
+- **网络访问** — 搜索和抓取网页内容。
+- **容器隔离** — 智能体在 Docker（macOS/Linux/WSL2）中沙箱化运行，可选 [Docker Sandboxes](docs/docker-sandboxes.md) 的微虚拟机隔离，或在 macOS 上选用 Apple Container 作为原生运行时。
+- **凭据安全** — 智能体不持有原始 API key。出站请求经由 [OneCLI 的 Agent Vault](https://github.com/onecli/onecli)，在请求时注入凭据，并按每个智能体执行策略和速率限制。
+
+## 使用方法
+
+用触发词（默认为 `@Andy`）与您的助手对话：
+
+```
+@Andy 每个工作日早上 9 点给我发一份销售渠道概览（可以访问我的 Obsidian vault 文件夹）
+@Andy 每周五回顾过去一周的 git 历史，如果与 README 有出入就更新它
+@Andy 每周一早上 8 点，从 Hacker News 和 TechCrunch 收集 AI 相关资讯，给我发一份简报
+```
+
+在您拥有或管理的渠道里，还可以管理群组和任务：
+```
+@Andy 列出所有群组里的计划任务
+@Andy 暂停周一简报任务
+@Andy 加入"家庭聊天"群组
+```
+
+## 定制
+
+NanoClaw 不用配置文件。想改就直接告诉 Claude Code：
+
+- "把触发词改成 @Bob"
+- "以后回答请更简短、更直接"
+- "我说早上好的时候加一个自定义问候"
+- "每周保存一次会话摘要"
+
+或者运行 `/customize` 进行引导式修改。
+
+代码库足够小，Claude 可以安全地修改它。
+
+## 贡献
+
+**不要加功能，要加技能。**
+
+如果您想添加新的渠道或智能体提供者，不要把它加到主干上。新的渠道适配器进入 `channels` 分支；新的智能体提供者进入 `providers` 分支。用户在自己的 fork 上运行 `/add-<name>` 技能，由技能把相关模块复制到标准路径、接好注册、固定依赖版本。
+
+这样主干始终保持为纯粹的注册表和基础设施，每个 fork 也都保持精简——用户只获得他们要求的渠道和提供者，其它什么也不会混进来。
+
+### RFS（技能征集）
+
+我们希望看到的技能：
+
+**通信渠道**
+- `/add-signal` — 添加 Signal 作为渠道
+
+## 系统要求
+
+- macOS 或 Linux（Windows 通过 WSL2）
+- Node.js 20+ 和 pnpm 10+（安装脚本会在缺失时自动安装）
+- [Docker Desktop](https://docker.com/products/docker-desktop)（macOS/Windows）或 Docker Engine（Linux）
+- [Claude Code](https://claude.ai/download)，用于 `/customize`、`/debug`、安装过程中的错误恢复以及所有 `/add-<channel>` 技能
+
+## 架构
+
+```
+消息应用 → 主机进程（路由器） → inbound.db → 容器（Bun、Claude Agent SDK） → outbound.db → 主机进程（投递） → 消息应用
+```
+
+单一 Node 主机编排每个会话的智能体容器。当一条消息到来时，主机按实体模型（用户 → 消息组 → 智能体组 → 会话）进行路由，写入该会话的 `inbound.db`，并唤醒容器。容器内部的 agent-runner 轮询 `inbound.db`，调用 Claude，并把响应写入 `outbound.db`。主机轮询 `outbound.db`，通过渠道适配器投递回去。
+
+每个会话两个 SQLite 文件，每个文件只有一个写入者——没有跨挂载的锁争用，没有 IPC，没有 stdin 管道。渠道和替代提供者在启动时自注册；主干提供注册表和 Chat SDK 桥接，而适配器本身在每个 fork 里通过技能安装。
+
+完整架构说明见 [docs/architecture.md](docs/architecture.md)；三级隔离模型见 [docs/isolation-model.md](docs/isolation-model.md)。
+
+关键文件：
+- `src/index.ts` — 入口：数据库初始化、渠道适配器、投递轮询、sweep
+- `src/router.ts` — 入站路由：消息组 → 智能体组 → 会话 → `inbound.db`
+- `src/delivery.ts` — 轮询 `outbound.db`，通过适配器投递，处理系统动作
+- `src/host-sweep.ts` — 60 秒 sweep：失效检测、到期消息唤醒、循环任务
+- `src/session-manager.ts` — 解析会话，打开 `inbound.db` / `outbound.db`
+- `src/container-runner.ts` — 为每个智能体组启动容器，OneCLI 凭据注入
+- `src/db/` — 中心数据库（用户、角色、智能体组、消息组、接线、迁移）
+- `src/channels/` — 渠道适配器基础设施（适配器通过 `/add-<channel>` 技能安装）
+- `src/providers/` — 主机侧提供者配置（`claude` 内置，其他通过技能安装）
+- `container/agent-runner/` — Bun 版 agent-runner：轮询循环、MCP 工具、提供者抽象
+- `groups/<folder>/` — 每个智能体组的文件系统（`CLAUDE.md`、技能、容器配置）
+
+## FAQ
+
+**为什么用 Docker？**
+
+Docker 提供跨平台支持（macOS、Linux、Windows via WSL2）和成熟的生态。在 macOS 上，您可以选择通过 `/convert-to-apple-container` 切换到 Apple Container，以获得更轻量的原生运行时。如需更强隔离，[Docker Sandboxes](docs/docker-sandboxes.md) 会把每个容器放到一台微虚拟机里运行。
+
+**我可以在 Linux 或 Windows 上运行吗？**
+
+可以。Docker 是默认运行时，可在 macOS、Linux 以及 Windows（通过 WSL2）上工作。运行 `bash nanoclaw.sh` 就行。
+
+**这个项目安全吗？**
+
+智能体运行在容器里，而不是躲在应用级权限检查之后。它们只能访问明确挂载的目录。凭据不会进入容器——出站 API 请求通过 [OneCLI 的 Agent Vault](https://github.com/onecli/onecli) 在代理层注入认证，并支持速率限制和访问策略。您仍然应该审查自己要运行的代码，但代码库小到您真的能做到。完整的安全模型见 [安全文档](https://docs.nanoclaw.dev/concepts/security)。
+
+**为什么没有配置文件？**
+
+我们不想让配置泛滥。每位用户都应该定制 NanoClaw，让代码精确地做他们想要的事，而不是去配置一个通用系统。如果您更喜欢有配置文件，可以让 Claude 给您加。
+
+**我可以使用第三方或开源模型吗？**
+
+可以。推荐做法是 `/add-opencode`（通过 OpenCode 配置接入 OpenRouter、OpenAI、Google、DeepSeek 等）或 `/add-ollama-provider`（通过 Ollama 使用本地开源权重模型）。两者都可以按智能体组单独配置，所以同一套安装里不同的智能体可以运行在不同的后端上。
+
+对于一次性实验，任何 Claude API 兼容的端点也可以通过 `.env` 使用：
+
+```bash
+ANTHROPIC_BASE_URL=https://your-api-endpoint.com
+ANTHROPIC_AUTH_TOKEN=your-token-here
+```
+
+**我该如何调试问题？**
+
+问 Claude Code。"为什么计划任务没运行？""最近的日志里有什么？""为什么这条消息没有得到回复？"这就是 NanoClaw 底层的 AI 原生方式。
+
+**为什么安装对我不成功？**
+
+如果某一步失败，`nanoclaw.sh` 会把控制权交给 Claude Code 进行诊断并从中断处继续。如果还是没解决，运行 `claude`，然后 `/debug`。如果 Claude 发现一个可能影响其他用户的问题，请对相关的安装步骤或技能提 PR。
+
+**什么样的更改会被接受进代码库？**
+
+进入基础配置的只会是：安全修复、bug 修复、明显的改进。仅此而已。
+
+其他一切（新能力、操作系统兼容、硬件支持、增强）都应作为技能贡献到 `channels` 或 `providers` 分支。
+
+这样基础系统保持最小化，每位用户都可以定制自己的安装，而不必继承他们不想要的功能。
+
+## 社区
+
+有问题或想法？欢迎[加入 Discord](https://discord.gg/VDdww8qS42)。
+
+## 更新日志
+
+破坏性变更见 [CHANGELOG.md](CHANGELOG.md)，完整发布历史见文档站的 [full release history](https://docs.nanoclaw.dev/changelog)。
+
+## 许可证
+
+MIT

package/config-examples/mount-allowlist.json

@@ -0,0 +1,25 @@
+{
+  "allowedRoots": [
+    {
+      "path": "~/projects",
+      "allowReadWrite": true,
+      "description": "Development projects"
+    },
+    {
+      "path": "~/repos",
+      "allowReadWrite": true,
+      "description": "Git repositories"
+    },
+    {
+      "path": "~/Documents/work",
+      "allowReadWrite": false,
+      "description": "Work documents (read-only)"
+    }
+  ],
+  "blockedPatterns": [
+    "password",
+    "secret",
+    "token"
+  ],
+  "nonMainReadOnly": true
+}

package/container/.dockerignore

@@ -0,0 +1,2 @@
+agent-runner/node_modules
+agent-runner/dist