{"id":47680054,"url":"https://github.com/zosmaai/openzosma","last_synced_at":"2026-04-26T05:01:23.122Z","repository":{"id":345427347,"uuid":"1185748129","full_name":"zosmaai/openzosma","owner":"zosmaai","description":"Build AI teams that work alongside yours -- accessible from your phone.","archived":false,"fork":false,"pushed_at":"2026-04-01T19:53:34.000Z","size":18150,"stargazers_count":13,"open_issues_count":12,"forks_count":8,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-03T01:44:27.108Z","etag":null,"topics":["ai-for-business","ai-twin","digital-twin","pi-agent","pi-coding-agent","work-ai","work-from-phone"],"latest_commit_sha":null,"homepage":"https://www.zosma.ai/openzosma","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zosmaai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"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":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-18T22:51:20.000Z","updated_at":"2026-04-01T18:28:21.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/zosmaai/openzosma","commit_stats":null,"previous_names":["zosmaai/openzosma"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/zosmaai/openzosma","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zosmaai%2Fopenzosma","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zosmaai%2Fopenzosma/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zosmaai%2Fopenzosma/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zosmaai%2Fopenzosma/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zosmaai","download_url":"https://codeload.github.com/zosmaai/openzosma/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zosmaai%2Fopenzosma/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32286271,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-25T18:29:39.964Z","status":"online","status_checked_at":"2026-04-26T02:00:05.962Z","response_time":129,"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":["ai-for-business","ai-twin","digital-twin","pi-agent","pi-coding-agent","work-ai","work-from-phone"],"created_at":"2026-04-02T13:56:31.628Z","updated_at":"2026-04-26T05:01:23.114Z","avatar_url":"https://github.com/zosmaai.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"assets/logo.png\" alt=\"OpenZosma\" width=\"400\" /\u003e\n\n\u003ch3\u003eBuild AI teams that work alongside yours -- accessible from your phone.\u003c/h3\u003e\n\n\u003cp\u003e\nOpen-source, self-hosted platform for hierarchical AI agents.\u003cbr /\u003e\nDelegate tasks through natural conversation from WhatsApp, Slack, or a web dashboard.\n\u003c/p\u003e\n\n\u003cp\u003e\n  \u003ca href=\"https://github.com/zosmaai/openzosma/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/zosmaai/openzosma?style=flat-square\u0026color=blue\" alt=\"License\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/zosmaai/openzosma/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/zosmaai/openzosma/ci.yml?branch=main\u0026style=flat-square\u0026label=CI\" alt=\"CI\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/create-openzosma\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/create-openzosma?style=flat-square\u0026color=cb3837\u0026label=npm\" alt=\"npm\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://discord.gg/ZVjdnyMN\"\u003e\u003cimg src=\"https://img.shields.io/badge/Discord-Join-7289DA?style=flat-square\u0026logo=discord\u0026logoColor=white\" alt=\"Discord\" /\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/node-%3E%3D22-brightgreen?style=flat-square\" alt=\"Node.js \u003e= 22\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/TypeScript-strict-3178C6?style=flat-square\u0026logo=typescript\u0026logoColor=white\" alt=\"TypeScript\" /\u003e\n\u003c/p\u003e\n\n\u003cp\u003e\n  \u003ca href=\"https://github.com/zosmaai/openzosma/stargazers\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/zosmaai/openzosma?style=flat-square\" alt=\"Stars\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/zosmaai/openzosma/graphs/contributors\"\u003e\u003cimg src=\"https://img.shields.io/github/contributors/zosmaai/openzosma?style=flat-square\" alt=\"Contributors\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/zosmaai/openzosma/issues\"\u003e\u003cimg src=\"https://img.shields.io/github/issues/zosmaai/openzosma?style=flat-square\" alt=\"Issues\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/zosmaai/openzosma/pulls\"\u003e\u003cimg src=\"https://img.shields.io/badge/PRs-welcome-brightgreen?style=flat-square\" alt=\"PRs Welcome\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp\u003e\n  \u003ca href=\"#get-started\"\u003eGet Started\u003c/a\u003e \u0026middot;\n  \u003ca href=\"#how-it-works\"\u003eHow It Works\u003c/a\u003e \u0026middot;\n  \u003ca href=\"#architecture\"\u003eArchitecture\u003c/a\u003e \u0026middot;\n  \u003ca href=\"./ARCHITECTURE.md\"\u003eFull Design Doc\u003c/a\u003e \u0026middot;\n  \u003ca href=\"./CONTRIBUTING.md\"\u003eContributing\u003c/a\u003e\n\u003c/p\u003e\n\n\u003c/div\u003e\n\n---\n\n## ⚡ Looking for a Standalone Agent Harness?\n\nIf you want a **lightweight, deployable agent server** without the full platform (no PostgreSQL, no dashboard, no auth complexity), check out **[@openzosma/pi-harness](./packages/pi-harness)**:\n\n```bash\nnpm install -g @openzosma/pi-harness\npi-harness   # First run auto-configures, then starts the server\n```\n\nIt runs `pi-coding-agent` headlessly as a background HTTP/SSE server — perfect for low-end hardware, background services, custom integrations, or when you just want the agent without the platform. [Learn more →](./packages/pi-harness)\n\n---\n\n## Get Started\n\nOne command sets up everything -- cloning, environment, Docker services, database migrations, and the first build:\n\n```bash\npnpm create openzosma\n```\n\nor\n\n```bash\nnpx create-openzosma\n```\n\nThe CLI walks you through choosing an LLM provider, configuring PostgreSQL, setting up auth secrets, and optionally enabling sandboxed execution. At the end it offers to start the gateway and dashboard for you.\n\n**Already cloned?** Run `pnpm setup` from the repo root instead. The CLI detects the existing checkout and skips the clone step.\n\n### Requirements\n\n- **Node.js** \u003e= 22\n- **pnpm** (latest)\n- **Docker** and **Docker Compose**\n- **Git**\n- **OpenShell CLI** (optional -- only needed for sandbox mode)\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eManual setup (without the CLI)\u003c/strong\u003e\u003c/summary\u003e\n\n```bash\ngit clone https://github.com/zosmaai/openzosma.git\ncd openzosma\npnpm install\n\n# Start services: PostgreSQL (with pgvector), Valkey, and RabbitMQ\ndocker compose up -d\n\n# Configure environment\ncp .env.example .env.local\n# Edit .env.local -- at minimum set an LLM API key and AUTH_SECRET\n\n# Build all packages (required before migrations)\npnpm run build\n\n# Run database migrations\npnpm db:migrate\npnpm db:migrate:auth\n\n# Start the gateway and dashboard\npnpm --filter @openzosma/gateway dev   # Terminal 1 (port 4000)\npnpm --filter @openzosma/web dev       # Terminal 2 (port 3000)\n```\n\nOpen \u003chttp://localhost:3000\u003e, sign up, and start a conversation.\n\n\u003e **Note:** The gateway `dev` script loads `../../.env.local` automatically via `--env-file`. If you need a different env file, run `npx tsx --env-file=\u003cpath\u003e src/index.ts` from `packages/gateway/`.\n\n\u003c/details\u003e\n\n---\n\n## What is OpenZosma?\n\nOpenZosma is an open-source, self-hosted platform for creating hierarchical AI agents that act as digital work twins for your team. Configure an agent org chart that mirrors your business structure, delegate tasks through natural conversation, and manage your operations from anywhere -- your phone, WhatsApp, Slack, or a web dashboard. No laptop required.\n\nAgents don't replace your team. They handle the routine lookups, status checks, data entry, and coordination that eat up your team's day -- so your people can focus on work that requires human judgment.\n\n\u003cdiv align=\"center\"\u003e\n  \u003ch3\u003eWatch: Set up OpenZosma in under 2 minutes\u003c/h3\u003e\n  \u003cimg src=\"assets/setup-demo.gif\" alt=\"Setup demo\" width=\"100%\" /\u003e\n\u003c/div\u003e\n\n### Key Features\n\n- **Hierarchical agents** -- Configure org-chart-like agent trees. Manager agents delegate to specialist agents automatically.\n- **Talk from anywhere** -- Web dashboard, mobile app, WhatsApp, Slack, or agent-to-agent via the [A2A protocol](https://github.com/google/A2A).\n- **Self-hosted** -- Your data stays on your infrastructure. One instance = one organization.\n- **Connect your tools** -- Integrate with databases, CRMs, email, and other business systems through configurable connectors.\n- **Secure by design** -- Each agent session runs in an isolated sandbox ([NVIDIA NemoClaw](https://github.com/NVIDIA/NemoClaw) + [OpenShell](https://github.com/NVIDIA/OpenShell)) with Landlock, seccomp, and network namespace isolation.\n- **Open source** -- Apache 2.0 license. No vendor lock-in, no usage fees, no data leaving your network.\n\n---\n\n## How It Works\n\nYou define a hierarchy of agents that mirrors your organization. Each agent has a role, a set of capabilities, and knows which agents report to it. You talk to the top-level agent, and it delegates work down the chain.\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"assets/diagram-hierarchy.png\" alt=\"Agent Hierarchy\" width=\"600\" /\u003e\n\u003c/div\u003e\n\n**Example:** You message your CEO Agent from WhatsApp: _\"What were last week's sales numbers and are there any open support tickets over 48 hours?\"_ The CEO Agent delegates to the Sales Manager Agent and Support Agent in parallel. They query your connected systems, and you get a consolidated answer back -- all from a single message on your phone.\n\n---\n\n## Architecture\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"assets/diagram-architecture.png\" alt=\"Architecture\" width=\"750\" /\u003e\n\u003c/div\u003e\n\nThe gateway runs in two modes controlled by `OPENZOSMA_SANDBOX_MODE`:\n\n| Mode                  | How it works                                                                                                                 | Best for    |\n| --------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ----------- |\n| **`local`** (default) | pi-agent runs in-process inside the gateway. No OpenShell needed.                                                            | Development |\n| **`orchestrator`**    | Each user gets a persistent OpenShell sandbox. The orchestrator manages sandbox lifecycle and proxies messages via HTTP/SSE. | Production  |\n\n\u003e **Want just the agent, without the gateway?** [`pi-harness`](./packages/pi-harness) is the local mode extracted as a standalone, deployable package — no PostgreSQL, no dashboard, no auth complexity. One `npm install -g` and you're running.\n\nSee [ARCHITECTURE.md](./ARCHITECTURE.md) for the full system design, data flow, and component details.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eRunning with sandboxes (orchestrator mode)\u003c/strong\u003e\u003c/summary\u003e\n\n```bash\n# 1. Install the OpenShell CLI and start the gateway (bootstraps a local K3s cluster)\n#    https://github.com/NVIDIA/OpenShell\nopenshell gateway start\n\n# 2. Build the sandbox image and import it into the K3s cluster\n./scripts/build-sandbox.sh v0.1.0\n\n# 3. Set sandbox mode in .env.local\nOPENZOSMA_SANDBOX_MODE=orchestrator\nSANDBOX_IMAGE=openzosma/sandbox-server:v0.1.0\n\n# 4. Start the gateway (it will create sandboxes on demand)\npnpm --filter @openzosma/gateway dev\n```\n\nUse a versioned tag (e.g. `v0.1.0`), not `:latest`. K3s sets `imagePullPolicy: Always` for `:latest`, which causes `ImagePullBackOff` since the image is local, not on Docker Hub.\n\nSee [infra/openshell/README.md](./infra/openshell/README.md) for sandbox image details and policy configuration.\n\n\u003c/details\u003e\n\n---\n\n## Tech Stack\n\n| Component       | Technology                                                 |\n| --------------- | ---------------------------------------------------------- |\n| Runtime         | Node.js 22 (TypeScript)                                    |\n| HTTP Server     | Hono                                                       |\n| Database        | PostgreSQL (raw SQL via `pg`, migrations via `db-migrate`) |\n| Auth            | Better Auth                                                |\n| Sandbox         | NVIDIA NemoClaw + OpenShell                                |\n| Web Dashboard   | Next.js 16, React 19, Tailwind CSS v4                      |\n| Mobile          | React Native (planned)                                     |\n| Agent Protocol  | [Google A2A](https://github.com/google/A2A)                |\n| Cache / Pub-Sub | Valkey (ioredis)                                           |\n| Internal Comms  | HTTP / SSE (orchestrator to sandbox-server)                |\n\n---\n\n## Supported LLM Providers\n\n| Provider    | Default model                                       |\n| ----------- | --------------------------------------------------- |\n| Anthropic   | Claude Sonnet 4                                     |\n| OpenAI      | GPT-4o                                              |\n| Google      | Gemini 2.5 Flash                                    |\n| Groq        | Llama 3.3 70B                                       |\n| xAI         | Grok 3                                              |\n| Mistral     | Mistral Large                                       |\n| Local model | Any OpenAI-compatible endpoint (Ollama, vLLM, etc.) |\n\n---\n\n## Project Structure\n\n```\nopenzosma/\n  apps/\n    web/                  Next.js dashboard\n    mobile/               React Native app (planned)\n  packages/\n    gateway/              API gateway (REST + WebSocket + A2A)\n    orchestrator/         Sandbox lifecycle, session proxying, health checks\n    agents/               Agent provider interface + implementations\n    pi-harness/           Standalone headless agent server (lightweight deploy)\n    sandbox/              OpenShell CLI wrapper\n    sandbox-server/       HTTP server running inside sandbox containers\n    db/                   Database migrations and query module\n    auth/                 Better Auth setup\n    a2a/                  A2A protocol implementation\n    grpc/                 Proto definitions + generated stubs\n    sdk/                  Client SDK (@openzosma/sdk)\n    adapters/             Channel adapters (Slack, WhatsApp)\n    skills/               Enterprise skills (reports, charts)\n  proto/                  Protobuf service definitions\n  infra/\n    openshell/            Sandbox Dockerfile, policies, entrypoint\n  docs/                   Phase implementation plans\n```\n\n---\n\n## Roadmap\n\n| Phase                                     | Description                                                         | Status            |\n| ----------------------------------------- | ------------------------------------------------------------------- | ----------------- |\n| [Phase 1](./docs/PHASE-1-MULTITENANT.md)  | Multi-instance pi-agent refactor (in pi-mono)                       | Complete          |\n| [Phase 2](./docs/PHASE-2-MONOREPO.md)     | Monorepo setup + DB schema + auth                                   | Complete          |\n| [Phase 3](./docs/PHASE-3-GATEWAY.md)      | API Gateway + A2A + auth                                            | Complete          |\n| **Pi-Harness**                            | Standalone headless agent server ([package](./packages/pi-harness)) | Complete          |\n| [Phase 4](./docs/PHASE-4-ORCHESTRATOR.md) | Orchestrator + OpenShell sandbox integration                        | In progress       |\n| [Phase 5](./docs/PHASE-5-ADAPTERS.md)     | Channel adapters (Slack, WhatsApp)                                  | Not started       |\n| [Phase 6](./docs/PHASE-6-SKILLS.md)       | Enterprise skills (database tool, reports)                          | Not started       |\n| [Phase 7](./docs/PHASE-7-DASHBOARD.md)    | Web dashboard                                                       | In progress (MVP) |\n\n**MVP (Phases 1-4):** ~4 weeks \u0026nbsp;|\u0026nbsp; **Full platform (Phases 1-7):** ~10 weeks\n\n---\n\n## Documentation\n\n| Document                                                         | Description                                           |\n| ---------------------------------------------------------------- | ----------------------------------------------------- |\n| [ARCHITECTURE.md](./ARCHITECTURE.md)                             | System design, component interactions, data flow      |\n| [CONTRIBUTING.md](./CONTRIBUTING.md)                             | Development setup, environment variables, conventions |\n| [packages/db/README.md](./packages/db/README.md)                 | Database migrations, schemas, query module            |\n| [packages/pi-harness/README.md](./packages/pi-harness/README.md) | Standalone headless agent server docs                 |\n| [docs/](./docs/)                                                 | Phase-by-phase implementation plans                   |\n\n---\n\n## Related Projects\n\n- **[pi-mono](https://github.com/badlogic/pi-mono)** -- Agent SDK (`pi-ai`, `pi-agent-core`, `pi-coding-agent`)\n- **[NVIDIA NemoClaw](https://github.com/NVIDIA/NemoClaw)** -- Sandbox runtime with Landlock + seccomp isolation\n- **[NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell)** -- K3s-based sandbox infrastructure\n- **[Google A2A](https://github.com/google/A2A)** -- Agent-to-Agent protocol (JSON-RPC 2.0)\n\n---\n\n## Contributors\n\n\u003ca href=\"https://github.com/zosmaai/openzosma/graphs/contributors\"\u003e\n  \u003cimg src=\"https://contrib.rocks/image?repo=zosmaai/openzosma\" alt=\"Contributors\" /\u003e\n\u003c/a\u003e\n\n## Star History\n\n[![Star History Chart](https://api.star-history.com/svg?repos=zosmaai/openzosma\u0026type=Date)](https://star-history.com/#zosmaai/openzosma\u0026Date)\n\n## License\n\n[Apache License 2.0](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzosmaai%2Fopenzosma","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzosmaai%2Fopenzosma","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzosmaai%2Fopenzosma/lists"}