{"id":48892288,"url":"https://github.com/0xsyncroot/nimbus-os","last_synced_at":"2026-04-16T09:05:54.335Z","repository":{"id":351570461,"uuid":"1211537556","full_name":"0xsyncroot/nimbus-os","owner":"0xsyncroot","description":"Personal AI OS — autonomous, self-healing, soul-driven agent with cross-session memory. Bun + TypeScript, multi-provider, multi-channel, runs local 24/7.","archived":false,"fork":false,"pushed_at":"2026-04-15T14:37:14.000Z","size":465,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-15T16:30:31.458Z","etag":null,"topics":["agent","ai","anthropic","bun","cli","llm","openai","personal-assistant","self-hosted","typescript"],"latest_commit_sha":null,"homepage":"https://github.com/0xsyncroot/nimbus-os","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/0xsyncroot.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/security.md","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-15T13:45:45.000Z","updated_at":"2026-04-15T14:37:31.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/0xsyncroot/nimbus-os","commit_stats":null,"previous_names":["0xsyncroot/nimbus-os"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/0xsyncroot/nimbus-os","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xsyncroot%2Fnimbus-os","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xsyncroot%2Fnimbus-os/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xsyncroot%2Fnimbus-os/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xsyncroot%2Fnimbus-os/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/0xsyncroot","download_url":"https://codeload.github.com/0xsyncroot/nimbus-os/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xsyncroot%2Fnimbus-os/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31870525,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-15T15:24:51.572Z","status":"online","status_checked_at":"2026-04-16T02:00:06.042Z","response_time":69,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["agent","ai","anthropic","bun","cli","llm","openai","personal-assistant","self-hosted","typescript"],"created_at":"2026-04-16T09:05:53.797Z","updated_at":"2026-04-16T09:05:54.329Z","avatar_url":"https://github.com/0xsyncroot.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# nimbus-os\n\n\u003e Personal AI OS — autonomous, soul-driven agent with cross-session memory.\n\u003e Bun + TypeScript, multi-provider, local-first, runs 24/7.\n\n[![version](https://img.shields.io/github/v/release/0xsyncroot/nimbus-os?include_prereleases\u0026color=orange)](https://github.com/0xsyncroot/nimbus-os/releases)\n[![license](https://img.shields.io/badge/license-PolyForm%20Noncommercial-blue)](./LICENSE)\n[![bun](https://img.shields.io/badge/runtime-Bun%20%E2%89%A51.2-black)](https://bun.sh)\n[![typescript](https://img.shields.io/badge/TypeScript-strict-blue)](./tsconfig.json)\n[![CI](https://github.com/0xsyncroot/nimbus-os/actions/workflows/ci.yml/badge.svg)](https://github.com/0xsyncroot/nimbus-os/actions/workflows/ci.yml)\n\nnimbus-os runs on your machine and helps with anything you would normally hand\nto a personal assistant: research, planning, writing, file/data triage,\ncommunication, life admin, code help, and light automation. Each workspace\nhas a SOUL (personality) and persistent MEMORY that carry across sessions,\ngiving you a consistent, opinionated assistant rather than a blank chatbot.\n\n---\n\n## Table of contents\n\n- [Overview](#overview)\n- [Architecture](#architecture)\n- [Install \u0026 quick start](#install--quick-start)\n- [Configuration](#configuration)\n- [Providers](#providers)\n- [Security](#security)\n- [Development](#development)\n- [License](#license)\n- [Acknowledgments](#acknowledgments)\n\n---\n\n## Overview\n\n**What it is**\n\n- A local-first, long-running, single-user AI agent with shell / filesystem / network access.\n- Workspaces are plain markdown (`SOUL.md`, `IDENTITY.md`, `MEMORY.md`, `TOOLS.md`) plus append-only JSONL sessions — inspectable, editable, greppable.\n- Ships as a single compiled binary per platform (Linux / macOS / Windows).\n\n**Defining trait — runtime SDD.** Before non-trivial tasks the agent writes an\ninternal mini-spec (5 sections, ~100 words) as a structured thinking aid, shows\na one-line FYI, then executes. A separate permission layer protects destructive\noperations. You stay in control without being interrupted.\n\n**What you can do with it**\n\n- 🔬 Research — deep-dive a topic, summarize sources, compare options\n- 📅 Planning — trips, projects, events, schedules\n- ✍️ Writing — draft, edit, translate, summarize\n- 📁 File \u0026 data triage — rename, group, archive, deduplicate\n- 🤖 Code help — refactor, review, tests, debugging\n- 🧠 Life admin — reminders, expense logs, habit tracking\n\nSee [`examples/souls/`](./examples/souls/) for ready-made personalities and\n[`docs/soul-writing.md`](./docs/soul-writing.md) for the authoring guide.\n\n---\n\n## Architecture\n\n```\nChannels → WorkspaceManager → AgentLoop → CanonicalIR → Provider\n                 ↓                ↓             ↓\n           SOUL/MEMORY       Permission    Safety/Obs/Cost\n                                              ↓\n                                         Platform (Win/Linux/macOS)\n```\n\n- **Workspace** — SOUL.md + IDENTITY.md + MEMORY.md + TOOLS.md + sessions (JSONL)\n- **Agent loop** — 3-tier cancellation, plan detector, event bus\n- **Canonical IR** — provider-agnostic message/block format; Anthropic and OpenAI-compat adapt to it\n- **Permissions** — 3 modes (readonly / default / bypass), rule parser, bash tier-1 security, path deny-list\n- **Platform** — detection, paths, shell, signals, AES-GCM vault\n\nSpec-level detail:\n[`specs/00-meta/META-001-architecture.spec.md`](./specs/00-meta/META-001-architecture.spec.md) •\n[`specs/00-meta/META-004-canonical-ir.spec.md`](./specs/00-meta/META-004-canonical-ir.spec.md) •\n[`specs/00-meta/META-009-threat-model.spec.md`](./specs/00-meta/META-009-threat-model.spec.md).\n\n---\n\n## Install \u0026 quick start\n\n### One-line install (Linux / macOS)\n\n```sh\ncurl -fsSL https://raw.githubusercontent.com/0xsyncroot/nimbus-os/main/install.sh | sh\n```\n\nThe installer:\n\n1. Detects your OS + architecture (`linux-x64`, `linux-arm64`, `darwin-x64`, `darwin-arm64`)\n2. Downloads the latest pre-built binary from the [Releases page](https://github.com/0xsyncroot/nimbus-os/releases)\n3. Verifies the SHA256 checksum (when `SHA256SUMS` is published)\n4. Installs to `~/.nimbus/bin/nimbus`\n5. Adds `~/.nimbus/bin` to your shell's PATH (`~/.bashrc`, `~/.zshrc`, or fish config)\n\nAfter install, restart your shell (or `source ~/.bashrc`) then:\n\n```sh\nnimbus init          # interactive wizard: workspace, SOUL, API key\nnimbus               # start chatting\n```\n\n**Options**\n\n```sh\n# Auto-confirm all prompts (CI / scripted installs)\ncurl -fsSL https://raw.githubusercontent.com/0xsyncroot/nimbus-os/main/install.sh | sh -s -- -y\n\n# Uninstall\nsh install.sh --uninstall\n```\n\n**Windows**: use the [Releases page](https://github.com/0xsyncroot/nimbus-os/releases) to\ndownload `nimbus-windows-x64.exe`, or install via Scoop / Chocolatey (coming soon).\n\n### Prerequisites\n\n- An API key from any supported provider *(skip if using local Ollama / vLLM)*\n\n### From source\n\n```bash\ngit clone https://github.com/0xsyncroot/nimbus-os.git\ncd nimbus-os\nbun install\nbun run start init       # wizard: name, provider, model\nbun run start            # enter REPL\n```\n\n\u003e **Requires** [Bun](https://bun.sh) ≥ 1.2 — `curl -fsSL https://bun.sh/install | bash`\n\n### Compiled binary (manual)\n\nPre-built binaries for Linux, macOS, and Windows are attached to every release\non the [Releases page](https://github.com/0xsyncroot/nimbus-os/releases).\n\nTo build locally:\n\n```bash\nbun run compile:linux-x64      # or :linux-arm64 / :darwin-x64 / :darwin-arm64 / :windows-x64\n./dist/nimbus-linux-x64 init\n```\n\n### First chat\n\nInside the REPL, talk naturally:\n\n```\n\u003e summarize the last 5 emails in my inbox\n\u003e research best 14\" laptops under $1500, compare top 5\n\u003e tidy ~/Downloads and group screenshots into a folder\n\u003e schedule a meeting with Alice next week\n```\n\nThe agent plans internally (runtime SDD), shows a one-line FYI, then acts.\nDestructive actions go through the permission gate and prompt for confirmation.\n\nSlash commands: `/new`, `/sessions`, `/soul`, `/memory`, `/provider`, `/model`,\n`/mode readonly|default|bypass`, `/cost`, `/stop`.\nFull list: [`docs/getting-started.md`](./docs/getting-started.md).\n\n---\n\n## Configuration\n\n### API keys — stored encrypted\n\n```bash\n# Anthropic (official endpoint)\nnimbus key set anthropic\n\n# OpenAI\nnimbus key set openai\n\n# OpenAI-compatible w/ custom baseUrl (auto-aligns workspace defaults)\nnimbus key set openai --base-url https://api.groq.com/openai/v1\nnimbus key set openai --base-url http://localhost:9000/v1       # vLLM / Ollama\n```\n\nKeys are held in an AES-GCM vault at\n`~/.local/share/nimbus/vault.jsonl` (or the platform-equivalent).\nIn v0.1.0 the passphrase is supplied via `NIMBUS_VAULT_PASSPHRASE`; native OS\nkeychain integration is on the near-term roadmap.\n\n### Workspace data\n\n| OS | Path |\n|----|------|\n| Linux | `~/.local/share/nimbus/workspaces/{id}` |\n| macOS | `~/Library/Application Support/nimbus/workspaces/{id}` |\n| Windows | `%LOCALAPPDATA%\\nimbus\\workspaces\\{id}` |\n\nEach workspace contains `SOUL.md`, `IDENTITY.md`, `MEMORY.md`, `TOOLS.md`,\n`DREAMS.md`, and a `sessions/` directory.\n\n### SOUL.md example\n\n```markdown\n---\nschemaVersion: 1\nname: my-assistant\ncreated: 2026-04-15\n---\n\n# Identity\nI am your day-to-day assistant — friendly, concrete, cautious with anything\nirreversible. ...\n\n# Values\n- Confirm before any action that cannot be undone\n- State uncertainty explicitly\n- ...\n\n# Communication Style\n- Voice: warm, concise\n- Language: Vietnamese primary, English for technical terms\n\n# Boundaries\n- Will NOT: pay online, read .env / .ssh, send email without confirmation\n- Will only if explicit: mimic another author's style\n```\n\nFull authoring guide: [`docs/soul-writing.md`](./docs/soul-writing.md).\n\n---\n\n## Providers\n\n| Provider | Kind | baseUrl | Notes |\n|----------|------|---------|-------|\n| Anthropic | `anthropic` | default | Prompt caching (explicit), vision, extended thinking |\n| OpenAI | `openai-compat` | default | `max_completion_tokens` auto-routed for o1 / gpt-5.x |\n| Groq | `openai-compat` | `https://api.groq.com/openai/v1` | Fast, free tier |\n| DeepSeek | `openai-compat` | `https://api.deepseek.com/v1` | Low cost |\n| Ollama | `openai-compat` | `http://localhost:11434/v1` | Local, no key |\n| vLLM / any OpenAI-compat | `openai-compat` | your URL | Self-hosted |\n\nSwitch any time with `/provider \u003cid\u003e` inside the REPL. More:\n[`docs/providers.md`](./docs/providers.md).\n\n---\n\n## Security\n\nnimbus-os has full access to filesystem, shell, network, and code execution.\nIt is designed for single-user local use. Defenses:\n\n1. **Permission modes** — `readonly`, `default` (confirm on write/bash), `bypass` (opt-in).\n2. **Rule parser** — allow / deny lists with glob + regex.\n3. **Bash tier-1 security** — blocks `rm -rf /`, `curl | sh`, fork bombs, LD_PRELOAD, DNS exfil, and related patterns.\n4. **Path validator** — `.env`, `.ssh/`, credential files are denied by default (case-insensitive).\n5. **Encrypted vault** — API keys never stored in plaintext.\n6. **Audit log** — every tool call + security event appended to `events.jsonl`.\n\nRead [`docs/security.md`](./docs/security.md) before enabling `bypass` mode or\nexposing nimbus to remote channels.\n\n---\n\n## Development\n\nnimbus-os is built using **Spec-Driven Development**. Every feature has a spec\nin [`specs/`](./specs/) before any code is written; spec and code land in the\nsame commit.\n\n```bash\nbun run spec list                     # list specs\nbun run spec show SPEC-101            # view a spec\nbun run spec validate                 # verify 6 elements + link resolution\nbun run spec new SPEC-XXX             # scaffold a new spec\n\nbun test                              # run unit tests\nbun run typecheck                     # strict TS, no any\nbun run lint                          # eslint\nbun run format                        # prettier\n```\n\nCommit format: `[SPEC-XXX] imperative subject`. More:\n[`CLAUDE.md`](./CLAUDE.md).\n\n### Repo layout\n\n```\nnimbus-os/\n├── src/            # implementation (TS strict, Bun-native)\n├── specs/          # SDD artifacts — source of truth\n├── tests/          # unit tests (mirror of src/)\n├── docs/           # user-facing documentation\n├── examples/       # SOUL.md templates\n├── scripts/        # dev tooling (bun run spec …)\n└── dist/           # compiled binaries (git-ignored)\n```\n\nIssues and pull requests are welcome via the\n[Issues](https://github.com/0xsyncroot/nimbus-os/issues) and\n[Pull Requests](https://github.com/0xsyncroot/nimbus-os/pulls) pages.\n\n---\n\n## License\n\nnimbus-os is released under the\n[**PolyForm Noncommercial License 1.0.0**](./LICENSE).\n\n- **Personal, research, hobby, educational, and nonprofit use** is free.\n- **Commercial use** (hosting nimbus as a service, bundling into a product\n  you sell, internal production use at a for-profit organization beyond\n  evaluation scope) is **not permitted** under this license and requires\n  permission from the author. Open an issue tagged `commercial-license` to\n  get in touch.\n\n---\n\n## Acknowledgments\n\n- [OpenClaw](https://github.com/openclaw/openclaw) — SOUL/IDENTITY/MEMORY/DREAMS, daemon, channels\n- [Claude Code](https://claude.com/claude-code) — agentic loop, bash security, compaction\n- [soul.md](https://github.com/aaronjmars/soul.md) — personality layering\n- [Spec Kit](https://github.com/github/spec-kit) — SDD methodology\n- [Bun](https://bun.sh) — runtime that makes a single-binary personal AI OS practical\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0xsyncroot%2Fnimbus-os","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F0xsyncroot%2Fnimbus-os","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0xsyncroot%2Fnimbus-os/lists"}