MosAIc Companion is an open-source AI companion browser by HyperCycle. It lets you chat with AI agents from multiple providers — Claude, OpenAI, Gemini, Ollama, and HyperCycle — inside a familiar browser-style, tabbed desktop app.
It is also a runtime for extending what those agents can do: sandboxed WebAssembly tools, Model Context Protocol connections, permissioned add-ons, local data controls, Web3 capabilities, and a built-in development environment, all in one workspace.
MosAIc Companion is pre-1.0 and under active development. Interfaces, security boundaries, packaging, and extension APIs are still being stabilised, and they may change between releases. Read the extension and trust model below before using MosAIc with sensitive data or funds.
The easiest way to get MosAIc Companion is the download home:
- https://releases.hyperpg.site/mosaic/ — pick the installer for your platform
- Alternatively, grab installers from the GitHub releases page
Installers cover all three platforms, but support differs:
| Platform | Format | Status |
|---|---|---|
| macOS | .dmg |
Works. macOS blocks the app the first time you open it. The install page has the one-time step. |
| Windows | Setup.exe |
Works. SmartScreen warns on first run. The install page has the step. |
| Linux | .deb, AppImage |
Published, but not in a known-good state. Expect problems, and report what you hit. |
Releases aren't code-signed or notarized. The first-run warnings on macOS and Windows come from that, not from a problem with the download.
For a full non-technical walkthrough — install, first launch, connecting your first AI provider — see the Getting Started guide.
AI agents become more useful when they can safely use tools, data, services, and other agents. MosAIc is a desktop environment in which those capabilities can be installed, inspected, permissioned, and operated.
- Multiple AI agents using Claude, OpenAI, Gemini, Ollama, HyperCycle, or custom endpoints.
- Conversations with persistent history and tool use.
- MosaicBot background assistance with skills, memory, and scheduled heartbeats.
- MCP server connections over local process or HTTP transports.
- Sandboxed WASM tools with declared permissions and per-tool activity logs.
- Permissioned renderer add-ons with a constrained host API.
- Multi-user chat rooms with AI agent participants.
- Local Vault boxes with agent-level access controls.
- Web3 wallet, address-book, balance, token, and transaction functions.
- HyperInsight network and AIM analytics.
- A built-in code editor, project explorer, AI assistance, and terminal.
Maturity varies by subsystem. See the roadmap and the implementation status before treating any of it as production-ready.
MosAIc supports more than one kind of extension, and they do not have the same security properties.
| Extension type | Execution model | Trust expectation |
|---|---|---|
| Sandboxed tool | WebAssembly through Extism | Lowest privilege. Network and filesystem denied by default; requested capabilities are declared in the tool manifest |
| MCP integration | Local child process or remote HTTP service | Semi-trusted. What it can reach depends on the server and the transport |
| Renderer add-on | Isolated Electron webview using window.addonAPI |
Permissioned host API; no Node.js access for third-party add-ons |
| Bundled or privileged component | Ships with the app, or runs in the main process | Highest privilege, equivalent to core code, and reviewed to that standard |
Add-ons that supply main-process code fall into the last row rather than the third: main entries load unsandboxed, and the permission model covers only the renderer. Third-party main entries are therefore refused — the allowlist has one first-party entry — so every other add-on is renderer-only today.
The architectural goal is that boundary crossings are explicit, mediated by the core, and logged, and that the core itself stays as small as the product allows. How much belongs in the core rather than in an extension is an open question.
For detail, see the architecture overview, the permissions model, and the tool lifecycle. That documentation set has known divergences from the implementation — docs/architecture/STATUS.md records which parts are current and which are superseded.
Agent API keys, wallet keys, and sandbox tool secrets use Electron safeStorage where the platform provides it.
The Vault is an early component. In the current published release (v0.1.12), box contents are stored as local JSON, unencrypted at rest, and the Vault page says so — anyone who can read your files, or a backup of them, can read your boxes. Encryption at rest using the operating system's secure storage is built and enabled on main, so a build from source encrypts and its Vault page reports which protection is actually in effect; it is not yet in any published release. The per-agent access controls are enforced within the application and are separate from encryption; they do not protect the files on disk.
For contributors and anyone who wants to build the app themselves.
Prerequisites: Node.js 22, as pinned in .nvmrc — 20 or later works, and CI builds on 22. npm 9+, git, and platform build tools if you intend to package.
git clone https://github.com/hypercycle-development/mosaic-companion.git
cd mosaic-companion
nvm use
npm install
# Renderer-only dev server (Vite, hot reload)
npm run dev
# Full Electron app (via Electron Forge)
npm startOr run ./setup.sh for an automated setup, or ./start.sh to install dependencies if needed and launch the app.
There is no API-key file to set up: AI provider keys are configured inside the app, either through the onboarding wizard on first launch or later under Configuration → AI Agents.
Packaging expects a Gmail credentials file to exist even when Gmail is not being used:
cp config/gmail-credentials.example.json config/gmail-credentials.jsonnpm run dev- Start the Vite renderer dev server with hot reloadnpm run build- Build the application for productionnpm start- Start the Electron app via Forgenpm run preview- Preview the production buildnpm run typecheck- Run TypeScript type checking without buildingnpm run test:e2e- Run the Playwright end-to-end testsnpm run clean- Remove build artifacts
| Script | Description |
|---|---|
npm run make |
Build for current platform/arch |
npm run make:linux |
Build Linux (native arch) |
npm run make:linux:x64 |
Build Linux x64 |
npm run make:linux:arm64 |
Build Linux arm64 |
npm run make:mac |
Build macOS (native arch) |
npm run make:mac:x64 |
Build macOS x64 |
npm run make:mac:arm64 |
Build macOS arm64 |
npm run make:win |
Build Windows (native arch) |
npm run make:win:x64 |
Build Windows x64 |
npm run make:win:arm64 |
Build Windows arm64 |
npm run deploy |
Publish a release (maintainers: see docs/release-process.md) |
npm run deploy:x64 |
Publish x64 (maintainers: see docs/release-process.md) |
npm run deploy:arm64 |
Publish arm64 (maintainers: see docs/release-process.md) |
See docs/build.md for platform-specific packaging instructions.
Build an extension is the full guide: the two kinds of extension, the manifest, permissions, how to run one locally, and what happens when you submit one.
- Start with the minimal renderer add-on.
- Start with the minimal WASM tool.
- Read the tool manifest specification.
- Read the tool UI documentation.
- Review the MCP integration patterns.
Add-ons reach other people through mosaic-addons, a reviewed catalogue. Open a pull request adding addons/<your-id>/ with a manifest, a licence, and your source. We review the source you submit, not a build of it: a submission is assessed from the files in your pull request — the ones a reviewer can open and read — rather than from running the add-on, so everything an add-on does should be readable in those files. Its CONTRIBUTING guide sets out what a submission must contain, and what it cannot ask for.
Catalogue releases are signed, and the application verifies them against a pinned publisher key before installing anything. A signature establishes who published an add-on, never that the add-on is safe — review addresses the second, and review is human.
You need none of that to build one. The Dev corner in Settings loads an unpacked add-on from a local directory — the fastest way to develop, and the right route for anything you only want to run yourself. It is gated to development builds: a packaged build refuses a dev-install unless it is started with MOSAIC_ADDON_DEV=1.
A conformance suite and broader SDK coverage are still outstanding. For significant extension work, open a public issue before investing heavily in it.
Contributions of code, integrations, documentation, testing, design, security research, network capabilities, and use cases are welcome.
Before contributing:
- Read CONTRIBUTING.md.
- Review the roadmap.
- Report vulnerabilities privately according to SECURITY.md.
- Follow the CODE_OF_CONDUCT.md.
- See GOVERNANCE.md for how decisions are made.
For substantial features, or changes to manifests, permissions, host functions, extension APIs, or security boundaries, begin with an issue before opening a large pull request. This applies to maintainers as well as to outside contributors.
For questions rather than contributions, SUPPORT.md explains where to ask.
Technical authority in MosAIc Companion is earned through sustained contribution and sound judgment. Company membership and financial sponsorship do not carry merge authority, and review rights are held by individuals rather than by the organisations they work for.
GOVERNANCE.md describes how decisions are made and MAINTAINERS.md records who makes them. Significant changes are proposed as issues before implementation, and every commit carries a Developer Certificate of Origin sign-off, which is an enforced check.
The project has three maintainers, all affiliated with HyperCycle. Decisions are made by majority, so no single maintainer can block a change; there is still no independent removal process, and a maintainer can merge their own change without a second review. Those are limits of the current size rather than settled positions, and growing past them is a goal.
Do not report suspected vulnerabilities through a public issue. Follow SECURITY.md for private reporting and coordinated disclosure.
MosAIc Companion is licensed under the Apache License 2.0. See NOTICE for attribution details. Bundled dependencies and contributed extensions may use their own compatible licences and should declare them clearly.