create-hybrid 1.4.4 → 2.0.0

package/README.md

@@ -1,58 +1,173 @@
 # create-hybrid
 
-This package is part of the Hybrid monorepo.
+Project scaffolding tool for Hybrid AI agents. Generates a complete, production-ready agent project using the Cloudflare Containers + Durable Objects architecture.
 
-Hybrid makes it easy for developers to create intelligent agents that can understand natural language, process messages, and respond through XMTP's decentralized messaging protocol.
-
-See [hybrid.dev](https://hybrid.dev) for more information.
-
-## 📦 Quickstart
-
-Getting started with Hybrid is simple:
-
-### 1. Initialize your project
+## Usage
 
 ```bash
 npm create hybrid my-agent
-cd my-agent
+# or
+npx create-hybrid my-agent
+# or with options
+npx create-hybrid my-agent --env production --agent-name "My Bot"
 ```
 
-This creates all the necessary files and configuration for your agent.
+## Options
 
-### 2. Get your OpenRouter API key
-   
-Visit [OpenRouter](https://openrouter.ai/keys), create an account and generate an API key
+| Flag | Description | Default |
+|------|-------------|---------|
+| `<name>` | Project directory name | Required |
+| `--env` | XMTP environment: `dev` or `production` | Prompted interactively |
+| `--agent-name` | Display name for the agent | Prompted interactively |
 
-Add it to your `.env` file:
+## Generated Project Structure
 
-```env
-OPENROUTER_API_KEY=your_openrouter_api_key_here
+```
+my-agent/
+├── src/
+│   ├── gateway/
+│   │   └── index.ts        # Cloudflare Worker: routes to container
+│   ├── server/
+│   │   └── index.ts        # Agent server: Claude Code SDK + SSE
+│   └── dev-gateway.ts      # Local dev proxy to localhost:8454
+├── package.json
+├── tsconfig.json
+├── wrangler.jsonc           # Cloudflare Workers + Containers config
+├── Dockerfile               # Container image (cloudflare/sandbox base)
+├── build.mjs                # esbuild bundler script
+├── start.sh                 # Container startup: node dist/server/index.js
+├── SOUL.md                  # Agent personality / identity
+├── INSTRUCTIONS.md          # Agent behavioral guidelines
+├── .env.example             # Template for required environment variables
+└── .gitignore
 ```
 
-### 3. Generate XMTP keys
+## Architecture
+
+The generated project uses **Cloudflare Containers + Durable Objects**:
 
-```bash
-hybrid keys
 ```
+┌─────────────────────────────────────────────────────────────┐
+│                     Cloudflare Edge                          │
+│                                                              │
+│  src/gateway/index.ts  (Cloudflare Worker)                   │
+│       │                                                       │
+│       ├── Gets/creates Sandbox Durable Object by teamId      │
+│       ├── Calls ensureAgentServer() to start container       │
+│       └── sandbox.containerFetch() → port 8454              │
+│                           │                                   │
+│               ┌───────────▼────────────┐                     │
+│               │  Docker Container      │                      │
+│               │  (Sandbox DO)          │                      │
+│               │                        │                      │
+│               │  src/server/index.ts   │                      │
+│               │  Claude Code SDK       │                      │
+│               │  POST /api/chat → SSE  │                      │
+│               └────────────────────────┘                     │
+└─────────────────────────────────────────────────────────────┘
+```
+
+Each `teamId` gets its own `Sandbox` Durable Object and container instance.
+
+## Generated Files in Detail
+
+### `src/gateway/index.ts`
+
+The Cloudflare Worker entry point:
+- Routes `GET /health` and `POST /api/chat`
+- Gets or creates a `Sandbox` Durable Object keyed by `teamId`
+- Calls `ensureAgentServer()` which:
+  1. Polls `sandbox.listProcesses()` until the container is ready
+  2. Checks for a running `server/index.js` process
+  3. HTTP health checks port 8454
+  4. If unhealthy: kills node processes and starts `node /app/dist/server/index.js`
+- Proxies requests to the container via `sandbox.containerFetch()`
+
+### `src/server/index.ts`
+
+The agent server (runs inside the container):
+- Hono HTTP server on port 8454
+- `POST /api/chat`: Runs Claude Code SDK via `query()`, streams SSE response
+- `GET /health`: Returns `{ status: "healthy" }`
+- Reads `SOUL.md` and `INSTRUCTIONS.md` for system prompt
+- Supports both Anthropic direct and OpenRouter (auto-detected from `OPENROUTER_API_KEY`)
 
-or automatically add it to your `.env` file:  
+### `src/dev-gateway.ts`
+
+Local development proxy — proxies requests to `http://localhost:8454`:
 
 ```bash
-hybrid keys --write
+pnpm dev:gateway
 ```
 
-### 4. Register your wallet with XMTP
+### `Dockerfile`
 
-```bash
-hybrid register
+```dockerfile
+FROM cloudflare/sandbox:0.7.0
+WORKDIR /app
+COPY dist/server/index.js ./dist/server/
+COPY SOUL.md INSTRUCTIONS.md ./
+RUN npm install
+CMD ["sh", "start.sh"]
+```
+
+### `wrangler.jsonc`
+
+```jsonc
+{
+  "name": "my-agent",
+  "durable_objects": {
+    "bindings": [{ "name": "AgentContainer", "class_name": "Sandbox" }]
+  },
+  "containers": [
+    { "class_name": "Sandbox", "instance_type": "standard-1", "max_instances": 10 }
+  ]
+}
 ```
 
-This generates secure wallet and encryption keys for your XMTP agent.
+### `package.json` scripts
 
-  ### 5. Start developing
+| Script | Command |
+|--------|---------|
+| `build` | Runs `build.mjs` (esbuild bundles `src/server/index.ts`) |
+| `dev` | `pnpm build && node dist/server/index.js` |
+| `dev:gateway` | `node src/dev-gateway.ts` |
+| `dev:container` | `wrangler dev` (local container dev) |
+| `deploy` | `pnpm build && wrangler deploy` |
+| `typecheck` | `tsc --noEmit` |
+
+## Getting Started
+
+After scaffolding:
 
 ```bash
-hybrid dev
+cd my-agent
+
+# 1. Install dependencies
+pnpm install
+
+# 2. Copy and fill in environment variables
+cp .env.example .env
+# Edit .env: add OPENROUTER_API_KEY (or ANTHROPIC_API_KEY)
+
+# 3. Customize your agent
+# Edit SOUL.md for personality
+# Edit INSTRUCTIONS.md for behavioral guidelines
+
+# 4. Start local development
+pnpm dev
+
+# 5. Deploy to Cloudflare
+pnpm deploy
 ```
 
-Your agent will start listening for XMTP messages and you're ready to build!
+## Relation to Other Packages
+
+- The generated `src/server/index.ts` uses `@anthropic-ai/claude-agent-sdk` directly — same pattern as `packages/agent/src/server/index.ts`
+- The generated `src/gateway/index.ts` is a simplified version of `packages/gateway/src/index.ts` (without XMTP sidecar management)
+- The generated project is standalone — no dependencies on `@hybrd/*` packages
+- `packages/cli`'s `hybrid init` command delegates to this package
+
+## License
+
+MIT