my-project-public

repository

loading code, commits, and activity

repositories

loading repo index

#1	# Agent Instructions
#2
#3	Guidelines for AI agents working on this codebase.
#4
#5	## Project Overview
#6
#7	This is a Cloudflare Worker that runs [Moltbot](https://molt.bot/) in a Cloudflare Sandbox container. It provides:
#8	- Proxying to the Moltbot gateway (web UI + WebSocket)
#9	- Admin UI at `/_admin/` for device management
#10	- API endpoints at `/api/*` for device pairing
#11	- Debug endpoints at `/debug/*` for troubleshooting
#12
#13	Note: The CLI tool is still named `clawdbot` (upstream hasn't renamed yet), so CLI commands and internal config paths still use that name.
#14
#15	## Project Structure
#16
#17	```
#18	src/
#19	├── index.ts # Main Hono app, route mounting
#20	├── types.ts # TypeScript type definitions
#21	├── config.ts # Constants (ports, timeouts, paths)
#22	├── auth/ # Cloudflare Access authentication
#23	│ ├── jwt.ts # JWT verification
#24	│ ├── jwks.ts # JWKS fetching and caching
#25	│ └── middleware.ts # Hono middleware for auth
#26	├── gateway/ # Moltbot gateway management
#27	│ ├── process.ts # Process lifecycle (find, start)
#28	│ ├── env.ts # Environment variable building
#29	│ ├── r2.ts # R2 bucket mounting
#30	│ ├── sync.ts # R2 backup sync logic
#31	│ └── utils.ts # Shared utilities (waitForProcess)
#32	├── routes/ # API route handlers
#33	│ ├── api.ts # /api/* endpoints (devices, gateway)
#34	│ ├── admin.ts # /_admin/* static file serving
#35	│ └── debug.ts # /debug/* endpoints
#36	└── client/ # React admin UI (Vite)
#37	├── App.tsx
#38	├── api.ts # API client
#39	└── pages/
#40	```
#41
#42	## Key Patterns
#43
#44	### Environment Variables
#45
#46	- `DEV_MODE` - Skips CF Access auth AND bypasses device pairing (maps to `CLAWDBOT_DEV_MODE` for container)
#47	- `DEBUG_ROUTES` - Enables `/debug/*` routes (disabled by default)
#48	- See `src/types.ts` for full `MoltbotEnv` interface
#49
#50	### CLI Commands
#51
#52	When calling the moltbot CLI from the worker, always include `--url ws://localhost:18789`.
#53	Note: The CLI is still named `clawdbot` until upstream renames it:
#54	```typescript
#55	sandbox.startProcess('clawdbot devices list --json --url ws://localhost:18789')
#56	```
#57
#58	CLI commands take 10-15 seconds due to WebSocket connection overhead. Use `waitForProcess()` helper in `src/routes/api.ts`.
#59
#60	### Success Detection
#61
#62	The CLI outputs "Approved" (capital A). Use case-insensitive checks:
#63	```typescript
#64	stdout.toLowerCase().includes('approved')
#65	```
#66
#67	## Commands
#68
#69	```bash
#70	npm test # Run tests (vitest)
#71	npm run test:watch # Run tests in watch mode
#72	npm run build # Build worker + client
#73	npm run deploy # Build and deploy to Cloudflare
#74	npm run dev # Vite dev server
#75	npm run start # wrangler dev (local worker)
#76	npm run typecheck # TypeScript check
#77	```
#78
#79	## Testing
#80
#81	Tests use Vitest. Test files are colocated with source files (`*.test.ts`).
#82
#83	Current test coverage:
#84	- `auth/jwt.test.ts` - JWT decoding and validation
#85	- `auth/jwks.test.ts` - JWKS fetching and caching
#86	- `auth/middleware.test.ts` - Auth middleware behavior
#87	- `gateway/env.test.ts` - Environment variable building
#88	- `gateway/process.test.ts` - Process finding logic
#89	- `gateway/r2.test.ts` - R2 mounting logic
#90
#91	When adding new functionality, add corresponding tests.
#92
#93	## Code Style
#94
#95	- Use TypeScript strict mode
#96	- Prefer explicit types over inference for function signatures
#97	- Keep route handlers thin - extract logic to separate modules
#98	- Use Hono's context methods (`c.json()`, `c.html()`) for responses
#99
#100	## Documentation
#101
#102	- `README.md` - User-facing documentation (setup, configuration, usage)
#103	- `AGENTS.md` - This file, for AI agents
#104
#105	Development documentation goes in AGENTS.md, not README.md.
#106
#107	---
#108
#109	## Architecture
#110
#111	```
#112	Browser
#113	│
#114	▼
#115	┌─────────────────────────────────────┐
#116	│ Cloudflare Worker (index.ts) │
#117	│ - Starts Moltbot in sandbox │
#118	│ - Proxies HTTP/WebSocket requests │
#119	│ - Passes secrets as env vars │
#120	└──────────────┬──────────────────────┘
#121	│
#122	▼
#123	┌─────────────────────────────────────┐
#124	│ Cloudflare Sandbox Container │
#125	│ ┌───────────────────────────────┐ │
#126	│ │ Moltbot Gateway │ │
#127	│ │ - Control UI on port 18789 │ │
#128	│ │ - WebSocket RPC protocol │ │
#129	│ │ - Agent runtime │ │
#130	│ └───────────────────────────────┘ │
#131	└─────────────────────────────────────┘
#132	```
#133
#134	### Key Files
#135
#136	\| File \| Purpose \|
#137	\|------\|---------\|
#138	\| `src/index.ts` \| Worker that manages sandbox lifecycle and proxies requests \|
#139	\| `Dockerfile` \| Container image based on `cloudflare/sandbox` with Node 22 + Moltbot \|
#140	\| `start-moltbot.sh` \| Startup script that configures moltbot from env vars and launches gateway \|
#141	\| `moltbot.json.template` \| Default Moltbot configuration template \|
#142	\| `wrangler.jsonc` \| Cloudflare Worker + Container configuration \|
#143
#144	## Local Development
#145
#146	```bash
#147	npm install
#148	cp .dev.vars.example .dev.vars
#149	# Edit .dev.vars with your ANTHROPIC_API_KEY
#150	npm run start
#151	```
#152
#153	### Environment Variables
#154
#155	For local development, create `.dev.vars`:
#156
#157	```bash
#158	ANTHROPIC_API_KEY=sk-ant-...
#159	DEV_MODE=true # Skips CF Access auth + device pairing
#160	DEBUG_ROUTES=true # Enables /debug/* routes
#161	```
#162
#163	### WebSocket Limitations
#164
#165	Local development with `wrangler dev` has issues proxying WebSocket connections through the sandbox. HTTP requests work but WebSocket connections may fail. Deploy to Cloudflare for full functionality.
#166
#167	## Docker Image Caching
#168
#169	The Dockerfile includes a cache bust comment. When changing `moltbot.json.template` or `start-moltbot.sh`, bump the version:
#170
#171	```dockerfile
#172	# Build cache bust: 2026-01-26-v10
#173	```
#174
#175	## Gateway Configuration
#176
#177	Moltbot configuration is built at container startup:
#178
#179	1. `moltbot.json.template` is copied to `~/.clawdbot/clawdbot.json` (internal path unchanged)
#180	2. `start-moltbot.sh` updates the config with values from environment variables
#181	3. Gateway starts with `--allow-unconfigured` flag (skips onboarding wizard)
#182
#183	### Container Environment Variables
#184
#185	These are the env vars passed TO the container (internal names):
#186
#187	\| Variable \| Config Path \| Notes \|
#188	\|----------\|-------------\|-------\|
#189	\| `ANTHROPIC_API_KEY` \| (env var) \| Moltbot reads directly from env \|
#190	\| `CLAWDBOT_GATEWAY_TOKEN` \| `--token` flag \| Mapped from `MOLTBOT_GATEWAY_TOKEN` \|
#191	\| `CLAWDBOT_DEV_MODE` \| `controlUi.allowInsecureAuth` \| Mapped from `DEV_MODE` \|
#192	\| `TELEGRAM_BOT_TOKEN` \| `channels.telegram.botToken` \| \|
#193	\| `DISCORD_BOT_TOKEN` \| `channels.discord.token` \| \|
#194	\| `SLACK_BOT_TOKEN` \| `channels.slack.botToken` \| \|
#195	\| `SLACK_APP_TOKEN` \| `channels.slack.appToken` \| \|
#196
#197	## Moltbot Config Schema
#198
#199	Moltbot has strict config validation. Common gotchas:
#200
#201	- `agents.defaults.model` must be `{ "primary": "model/name" }` not a string
#202	- `gateway.mode` must be `"local"` for headless operation
#203	- No `webchat` channel - the Control UI is served automatically
#204	- `gateway.bind` is not a config option - use `--bind` CLI flag
#205
#206	See [Moltbot docs](https://docs.molt.bot/gateway/configuration) for full schema.
#207
#208	## Common Tasks
#209
#210	### Adding a New API Endpoint
#211
#212	1. Add route handler in `src/routes/api.ts`
#213	2. Add types if needed in `src/types.ts`
#214	3. Update client API in `src/client/api.ts` if frontend needs it
#215	4. Add tests
#216
#217	### Adding a New Environment Variable
#218
#219	1. Add to `MoltbotEnv` interface in `src/types.ts`
#220	2. If passed to container, add to `buildEnvVars()` in `src/gateway/env.ts`
#221	3. Update `.dev.vars.example`
#222	4. Document in README.md secrets table
#223
#224	### Debugging
#225
#226	```bash
#227	# View live logs
#228	npx wrangler tail
#229
#230	# Check secrets
#231	npx wrangler secret list
#232	```
#233
#234	Enable debug routes with `DEBUG_ROUTES=true` and check `/debug/processes`.
#235
#236	## R2 Storage Notes
#237
#238	R2 is mounted via s3fs at `/data/moltbot`. Important gotchas:
#239
#240	- rsync compatibility: Use `rsync -r --no-times` instead of `rsync -a`. s3fs doesn't support setting timestamps, which causes rsync to fail with "Input/output error".
#241
#242	- Mount checking: Don't rely on `sandbox.mountBucket()` error messages to detect "already mounted" state. Instead, check `mount \| grep s3fs` to verify the mount status.
#243
#244	- Never delete R2 data: The mount directory `/data/moltbot` IS the R2 bucket. Running `rm -rf /data/moltbot/*` will DELETE your backup data. Always check mount status before any destructive operations.
#245
#246	- Process status: The sandbox API's `proc.status` may not update immediately after a process completes. Instead of checking `proc.status === 'completed'`, verify success by checking for expected output (e.g., timestamp file exists after sync).
#247

z6Mkq5mY3JWtxoxUobWcfNHm7AkRubgSWEZTkBVqZXJviFZ5/my-project-public