A self-hosted AI assistant with your choice of local or cloud models. Start with one assistant, then add specialist agents, connected services, dashboards, or open-hardware voice devices. Each user has their own workspace.
On Linux, with Git installed:
git clone --depth 1 https://github.com/openensemble/openensemble.git
cd openensemble
./install.sh- Keep the one-time first-run credential printed by the installer.
- Open
https://<your-server-ip>:3739. Check that it is your server before accepting the installer's self-signed certificate warning. - Create the owner account, or restore a backup, using that credential.
- Open Settings → Providers, connect one chat provider, and enable it.
- Choose Create Your Assistant, pick its model, save, and send a greeting.
New accounts use Single assistant mode. To add specialists later, switch Settings → Agents → Agent setup to Agent ensemble. Cortex provides internal reasoning and retrieval; your assistant still needs a chat provider.
Requirements: Linux (Debian-family systems are the main install path), Node.js 22.12 or newer, and the build/media/sandbox tools checked by the installer. macOS is a local-development option with different feature support. The installer can install missing dependencies and a systemd user service. Shallow clones support normal in-app updates.
Installation and Docker · First-run walkthrough · Complete user guide · Troubleshooting
Run oe bootstrap on the server if you lose the credential before setup is
complete. HTTP localhost on port 3737 is also available from a browser running
on the OE host; remote first-run setup uses HTTPS.
| Goal | Read next |
|---|---|
| Use one assistant or specialists with different models | Single assistant and ensembles, Providers |
| Keep separate chats and ongoing projects | Saved chats, Project spaces |
| Connect mail and Google Calendar | Email & calendar |
| Control home devices and saved action sequences | Home Assistant, Routines |
| Schedule work, reminders, and monitoring | Tasks & scheduler |
| Work with files, media, research, and code projects | Documents & sharing |
| Create skills and connect external tools | Skill Builder, MCP |
| Manage a remote machine and its services | Nodes, Service profiles |
| Learn preferences and prepare useful drafts | Personalization |
| Inspect background work and recover a job | Run Inspector, Resumable jobs |
Build up to 32 dashboards per profile, each with a stable address. Combine Home Assistant controls, calendar, email, node status, and custom-skill widgets. Customize portrait and landscape layouts, colors, and page elements; swipe between displays on a tablet.
Dashboard addresses use the signed-in profile and require normal OE login. Use a dedicated profile with limited access for an unattended display. Dashboard guide.
Pair a Seeed reSpeaker XVF3800 + XIAO ESP32-S3, say “Hey Ensemble,” and talk to your assistant. The browser flash wizard uses Chrome or Edge; prebuilt firmware is included. Supported features include household wake-word routing, conversation mode, AirPlay, and device-side alarms.
Voice processing follows your provider choices: remote STT receives recordings, cloud chat receives transcript/context, and remote TTS receives reply text. Configure local STT, chat, and TTS for local voice processing, and check other integrations separately. Voice setup · Model and privacy choices · Open firmware.
- Back up, restore, and update. Backups contain account
data, saved configuration, custom content, and decryption keys; they exclude
dependencies and bundled models. Password-protected exports use
.oeb. - Manage users and access.
- Set up public or private access with Cloudflare, a reverse proxy, or Tailscale.
- Understand security. Browser sessions use HttpOnly cookies; non-browser clients can use bearer tokens.
- Configure optional wake verification.
- See added features and release history.
For development, npm ci --ignore-scripts installs dependencies without the
model download; npm start uses the launcher. Local tests belong in ignored
tests/. Follow AGENTS.md and
documentation maintenance when contributing.
GNU Affero General Public License v3.0 or later. In plain English:
- Allowed: running OpenEnsemble yourself or for any commercial purpose, modifying it, redistributing it, and offering it as a hosted service.
- Required: if you modify OpenEnsemble and let anyone else use it (including over a network — hosting it for users counts), you must offer them the source of your modifications under the same AGPL-3.0 license.
- Required: preserve the copyright and license notices.
See LICENSE for the full text. For organizations that want to embed OpenEnsemble without the AGPL's copyleft obligation, a separate commercial license is available — get in touch.