MosAIc Companion MCP server
Commit Oct 27, 2026An open desktop runtime that lets AI agents use sandboxed WASM tools, MCP server connections, and permissioned add-ons in a single workspace.
Also known as hypercycle-development/mosaic-companion
- Stars
- 20
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Oct 27, 2026
- License
- Apache-2.0
What is MosAIc Companion MCP?
MosAIc Companion is an open desktop runtime that lets AI agents use sandboxed WASM tools, MCP server connections, and permissioned add-ons in a single workspace.
Summary generated from the project's README
About MosAIc Companion MCP server
Running multiple AI agents within a single, tabbed desktop workspace is what MosAIc Companion enables for developers and AI enthusiasts. This open-source desktop application allows you to chat with providers like Claude, OpenAI, Gemini, Ollama, and HyperCycle through a unified interface. It functions as a runtime where these agents can interact with sandboxed WebAssembly tools, Model Context Protocol connections, and permissioned renderer add-ons.
Users install the application on macOS, Windows, or Linux to manage local data and Web3 capabilities. The environment includes a built-in code editor, terminal, and project explorer to support development tasks. Security is managed through different execution models, ranging from low-privilege sandboxed tools to highly privileged bundled components. While the app provides local Vault boxes for agent-level access control, users should note that these are currently stored as unencrypted local JSON files.
What you can do with it
- 1Consolidate multiple AI providersChat with different large language models like Claude and Gemini within a single tabbed interface.
- 2Extend agent capabilities with toolsProvide AI agents with specialized functions using sandboxed WebAssembly or MCP connections.
- 3Develop and test extensionsBuild and run new add-ons or tools locally using the integrated development environment.
- 4Manage Web3 transactionsPerform blockchain-related tasks such as checking balances or managing tokens directly through the agent workspace.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablehypercycle-development/mosaic-companion is public and reachablegithub.com/hypercycle-development/mosaic-companion ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-27github.com/hypercycle-development/mosaic-companion ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubMosAIc Companion
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.
Download & Install
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.
What MosAIc does
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.
Extension and trust model
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.
Important data note
Agent API keys, wallet keys, and sandbox tool secrets use Electron safeStorage where the platform provides it.
The Vault is an early component. 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 is not implemented in any build, and is tracked in #110. The per-agent access controls are enforced within the application and are separate from encryption; they do not protect the files on disk.
Run from source
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 start
Or 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.json
Available Scripts
npm 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
Build & Package Scripts (Electron Forge)
| 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
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. The
window.addonAPI reference documents the API an add-on
page actually calls.
- 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.
Publishing an add-on
Add-ons reach other people through mosaic-open-platform, 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.
Contributing
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.
Governance
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.
Security
Do not report suspected vulnerabilities through a public issue. Follow SECURITY.md for private reporting and coordinated disclosure.
License
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.
Project links
MosAIc Companion MCP questions
What AI providers can I use with MosAIc Companion?
You can chat with AI agents from Claude, OpenAI, Gemini, Ollama, and HyperCycle.
How do I configure my AI provider API keys?
API keys are configured directly inside the application via the onboarding wizard or the Configuration menu.
What kind of extensions does MosAIc support?
It supports sandboxed WASM tools, MCP integrations, and renderer add-ons.