{"id":49191476,"url":"https://github.com/moikapy/nimbus-mono","last_synced_at":"2026-04-23T07:01:30.787Z","repository":{"id":352800303,"uuid":"1216612498","full_name":"Moikapy/nimbus-mono","owner":"Moikapy","description":"0xNIMBUS — Cloudflare-native AI agent with local-first runtime","archived":false,"fork":false,"pushed_at":"2026-04-21T06:18:16.000Z","size":829,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-21T08:28:29.149Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Moikapy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-21T04:29:14.000Z","updated_at":"2026-04-21T06:18:21.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Moikapy/nimbus-mono","commit_stats":null,"previous_names":["moikapy/nimbus-mono"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/Moikapy/nimbus-mono","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Moikapy%2Fnimbus-mono","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Moikapy%2Fnimbus-mono/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Moikapy%2Fnimbus-mono/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Moikapy%2Fnimbus-mono/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Moikapy","download_url":"https://codeload.github.com/Moikapy/nimbus-mono/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Moikapy%2Fnimbus-mono/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32169657,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-23T02:19:40.750Z","status":"ssl_error","status_checked_at":"2026-04-23T02:17:55.737Z","response_time":53,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-23T07:01:29.571Z","updated_at":"2026-04-23T07:01:30.722Z","avatar_url":"https://github.com/Moikapy.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Nimbus ☁️⚡\n\n\u003e *The golden cloud that only the pure of heart can ride.*\n\nNimbus is the **Cloudflare agent harness** — everything except the model. Built on the Agents SDK, wired through AI Gateway, fast as Kintoun.\n\n## What is Nimbus?\n\nAn **agent harness** is the complete architectural system surrounding an LLM that manages the lifecycle of context: from intent capture through tool execution, verification, and persistence. Nimbus handles everything except the model itself — tools, memory, context, verification, and state.\n\nYou extend `NimbusChatAgent`, add plugins for your domain with `.use(plugin)`, and deploy. No building agent loops from scratch. No vendor lock-in.\n\n```typescript\nimport { NimbusChatAgent } from \"nimbus-agent\";\nimport { treasuryPlugin } from \"nimbus-treasury\";\n\nexport class FederalDataAgent extends NimbusChatAgent {\n  constructor(ctx, env) {\n    super(ctx, env);\n    this.use(treasuryPlugin);\n  }\n}\n```\n\nThat's it. One harness. Add plugins. Ship.\n\n## Why \"Nimbus\"?\n\nGoku's Flying Nimbus (筋斗雲, Kintoun) is a magical golden cloud. It's fast, it goes anywhere, and **only the pure of heart can ride it**. That's the philosophy:\n\n- **Pure of heart** — Nimbus refuses harmful requests. Guard rails aren't optional, they're identity.\n- **Rides the cloud** — Born on Cloudflare's Agents SDK. Per-instance SQLite, WebSocket streaming, hibernation safety.\n- **Goes anywhere** — Workers AI, AI Gateway, OpenAI, Anthropic — one interface, any model.\n- **One harness, many riders** — The harness is the cloud. Plugins are the passengers.\n\n## Architecture\n\n```\nNimbusChatAgent (the harness ☁️)\n├── extends AIChatAgent (Agents SDK)\n│   ├── Per-instance SQLite (this.sql)\n│   ├── Message persistence (this.messages)\n│   ├── WebSocket streaming (resumable)\n│   ├── Hibernation safety (state survives eviction)\n│   └── useAgentChat (React hook)\n├── .use(plugin) (the composition layer)\n│   ├── Plugin tools → AI SDK tool() format\n│   ├── Plugin instructions → system prompt merge\n│   └── Plugin MCP servers → tool discovery\n├── Tool execution (Zod validation + error feedback)\n├── Model providers (which wind you ride)\n│   ├── Workers AI (default — Cloudflare native)\n│   └── AI Gateway (unified — any provider)\n└── Presets (pre-built tools)\n    ├── httpTools ← domain-allowlisted fetch\n    └── dataTools ← filter, sort, aggregate\n```\n\n## Quick Start\n\n### Install\n\n```bash\nbun add nimbus-agent\n```\n\n### Create an Agent\n\n```typescript\nimport { NimbusChatAgent } from \"nimbus-agent\";\nimport { treasuryPlugin } from \"nimbus-treasury\";\n\n// Extend the harness, add plugins\nexport class MyAgent extends NimbusChatAgent {\n  constructor(ctx, env) {\n    super(ctx, env);\n    this.use(treasuryPlugin);\n  }\n}\n```\n\n### Add a Custom Plugin\n\n```typescript\n// A plugin is just { name, tools, instructions }\nconst myPlugin = {\n  name: \"my-tools\",\n  description: \"Custom tools for my app\",\n  instructions: \"When answering questions about X, always cite the source.\",\n  tools: {\n    lookup_data: {\n      description: \"Look up data from my API\",\n      parameters: z.object({ query: z.string() }),\n      execute: async (params, ctx) =\u003e fetch(`/api/data?q=${params.query}`).then(r =\u003e r.json()),\n    },\n  },\n};\n\n// Use it\nthis.use(myPlugin);\n```\n\n### Deploy\n\n```typescript\n// src/worker.ts\nimport { NimbusChatAgent } from \"nimbus-agent\";\nimport { routeAgentRequest } from \"agents\";\n\nexport class MyAgent extends NimbusChatAgent {\n  constructor(ctx, env) { super(ctx, env); this.use(treasuryPlugin); }\n}\n\nexport default {\n  async fetch(request, env) {\n    return routeAgentRequest(request, env) || new Response(\"Not found\", { status: 404 });\n  },\n};\n```\nconsole.log(result.data);     // Raw data from tools\nconsole.log(result.steps);    // How many tool-call iterations\nconsole.log(result.tokens);   // Token usage\nconsole.log(result.duration); // Time in ms\n```\n\n## Model Providers\n\n### Workers AI (default)\n\nUses the `env.AI` binding in Cloudflare Workers. No API key needed.\n\n```typescript\ncreateNimbus({\n  model: \"workers-ai:@cf/zai-org/glm-4.7-flash\",\n});\n```\n\n### AI Gateway (unified)\n\nRoute any provider through Cloudflare AI Gateway. BYOK — bring your own keys, stored in the gateway.\n\n```typescript\ncreateNimbus({\n  model: \"unified:openai/gpt-5.2\",\n  gateway: {\n    accountId: \"your-account-id\",\n    gateway: \"your-gateway-id\",\n    apiKey: \"your-gateway-key\",\n  },\n});\n```\n\n### Fallback Chain\n\nTry the primary model, fall back if it fails:\n\n```typescript\ncreateNimbus({\n  model: \"unified:anthropic/claude-4-5-sonnet\",\n  fallbacks: [\"workers-ai:@cf/zai-org/glm-4.7-flash\"],\n});\n```\n\n## Memory\n\n### In-Memory (dev/test)\n\n```typescript\nimport { inMemory } from \"nimbus-agent/memory\";\n\ncreateNimbus({\n  model: \"workers-ai:...\",\n  memory: inMemory(),\n});\n```\n\n### D1 (production)\n\n```typescript\nimport { d1Memory } from \"nimbus-agent/memory\";\n\ncreateNimbus({\n  model: \"workers-ai:...\",\n  memory: d1Memory(env.DB),\n});\n```\n\n### KV (edge cache)\n\n```typescript\nimport { kvMemory } from \"nimbus-agent/memory\";\n\ncreateNimbus({\n  model: \"workers-ai:...\",\n  memory: kvMemory(env.CACHE),\n});\n```\n\n## Preset Tools\n\n### HTTP Tools\n\n```typescript\nimport { httpTools } from \"nimbus-agent/presets\";\n\nconst nimbus = createNimbus({\n  model: \"workers-ai:...\",\n}).use({\n  name: \"http\",\n  tools: httpTools({ allowedDomains: [\"api.example.com\"] }),\n});\n```\n\n### Data Tools\n\nFilter, sort, aggregate, top-N tools for data the model already has:\n\n```typescript\nimport { dataTools } from \"nimbus-agent/presets\";\n\n// Adds data_filter, data_sort, data_aggregate, data_top\n```\n\n## Plugin API\n\nA plugin adds tools, instructions, and/or MCP servers to the agent:\n\n```typescript\ninterface NimbusPlugin {\n  name: string;\n  description?: string;\n  tools?: Record\u003cstring, ToolDef\u003e;\n  mcpServers?: McpServerConfig[];\n  instructions?: string;  // Added to the system prompt when this plugin is active\n}\n```\n\nChain them:\n\n```typescript\nconst nimbus = createNimbus({ model, instructions })\n  .use(treasuryPlugin)    // federal data tools\n  .use(searchPlugin)      // web search\n  .use(weatherPlugin);    // weather data\n\nconsole.log(nimbus.plugins());\n// [\"nimbus-treasury\", \"nimbus-search\", \"nimbus-weather\"]\n```\n\nEach plugin's instructions are appended to the system prompt under a `--- plugin-name ---` header. Tools merge. MCP servers accumulate. No conflicts, no overwrites.\n\n## The Pure of Heart Clause\n\nNimbus refuses to:\n\n- **Harm people** — no weapons, no surveillance, no exploitation\n- **Deceive or manipulate** — no disinformation, no social engineering\n- **Violate privacy** — no unauthorized data collection, no stalking\n- **Build systems for evil** — even if profitable\n\nThis isn't a feature. It's identity. The Flying Nimbus only carries the pure of heart. If you can't ride it, the problem isn't the cloud.\n\n## Deploying on Cloudflare\n\n### Wrangler Setup\n\n```jsonc\n// wrangler.jsonc\n{\n  \"ai\": { \"binding\": \"AI\" },\n  \"d1_databases\": [{ \"binding\": \"DB\", \"database_name\": \"nimbus-db\" }],\n  \"kv_namespaces\": [{ \"binding\": \"CACHE\", \"id\": \"your-kv-id\" }]\n}\n```\n\n### Worker Entry\n\n```typescript\nimport { createNimbus } from \"nimbus-agent\";\n\nexport default {\n  async fetch(request: Request, env: Record\u003cstring, unknown\u003e) {\n    const nimbus = createNimbus({\n      model: \"workers-ai:@cf/zai-org/glm-4.7-flash\",\n      memory: d1Memory(env.DB as D1Database),\n    }).use(myPlugin);\n\n    const { searchParams } = new URL(request.url);\n    const question = searchParams.get(\"q\") ?? \"Hello\";\n    const result = await nimbus.run(question, { env });\n\n    return Response.json(result);\n  },\n};\n```\n\n## API Reference\n\n### `createNimbus(config)`\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `model` | `string` | *required* | Model reference (e.g. `workers-ai:@cf/...` or `unified:provider/model`) |\n| `instructions` | `string` | `\"\"` | System prompt |\n| `tools` | `Record\u003cstring, ToolDef\u003e` | `{}` | Inline tool definitions |\n| `mcpServers` | `McpServerConfig[]` | `[]` | Remote MCP tool servers |\n| `fallbacks` | `string[]` | `[]` | Fallback model references |\n| `memory` | `MemoryStore` | `null` | Conversation memory store |\n| `tracing` | `TraceStore` | `null` | Trace storage |\n| `context` | `object` | `{history:10, memory:true, maxContextTokens:8000, compaction:\"summarize\"}` | Context window config |\n| `maxSteps` | `number` | `10` | Max tool-call iterations |\n| `maxTokens` | `number` | `4096` | Max output tokens |\n| `timeout` | `number` | `30000` | Request timeout (ms) |\n| `retries` | `number` | `1` | Model call retries |\n| `retryDelay` | `number` | `1000` | Retry delay (ms) |\n\n### `nimbus.run(question, options?)`\n\nReturns `Promise\u003cNimbusResult\u003e`:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `answer` | `string` | The agent's final response |\n| `data` | `unknown[]` | Raw data collected from tool calls |\n| `sources` | `NimbusSource[]` | Which tools were used and what they returned |\n| `trace` | `NimbusTrace[]` | Full execution trace for debugging |\n| `model` | `string` | Which model was used |\n| `steps` | `number` | Tool-call iterations executed |\n| `tokens` | `{input, output, total}` | Token usage estimate |\n| `duration` | `number` | Total execution time (ms) |\n\n### `nimbus.use(plugin)`\n\nAdd a plugin. Returns `Nimbus` for chaining.\n\n### `nimbus.plugins()`\n\nList active plugin names.\n\n## License\n\nMIT\n\n---\n\n*Born on the cloud. Pure of heart. Fast as Kintoun.* ☁️⚡","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmoikapy%2Fnimbus-mono","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmoikapy%2Fnimbus-mono","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmoikapy%2Fnimbus-mono/lists"}