Security model

OpenEnsemble assumes you trust the people who have accounts on your install — but it doesn’t assume the network or the agents themselves are trustworthy.

Authentication

  • Normal browser login uses an HttpOnly, SameSite session cookie; browser JavaScript cannot read the token. Non-browser API clients continue to use Authorization: Bearer …. Session tokens are never placed in ordinary page URLs (URLs leak through referrers and access logs).
  • Browser sessions have a fixed seven-day maximum. Settings → System → Session Expiry or OE_SESSION_EXPIRY can add a shorter inactivity timeout, expressed in hours; 0 disables only that idle timeout, not the seven-day hard limit.
  • All sessions for a user are listable and revocable in Settings → Profile → Active Sessions.

Display dashboards

Addresses such as /dashboards/kitchen are stable routes, not anonymous share links or kiosk-scoped credentials. The page shell contains no token, and its layout and live-data APIs require the browser’s normal OE session. The active profile selects the dashboard library, even when another profile uses the same slug.

A display session has the account’s normal OE scope. Hiding cards or page elements is presentation, not authorization, so use a dedicated least-privilege profile and a device/browser lock for unattended screens. Home Assistant access is profile-wide rather than per dashboard: owners and admins receive runtime access automatically, while regular profiles need the role_home_assistant skill enabled. OE exposes normalized state, permitted camera views, and a fixed allowlist of controls; the configured Home Assistant token can restrict those operations further.

Calendar, Email, and custom-widget access is rechecked during refresh. If one of those permissions is revoked while a display remains open, already-rendered data can remain visible as a stale result until reload. Reload or close the display, or revoke its session, when immediate removal matters. Home Assistant state is cleared when runtime access becomes unavailable.

Roles

owner > admin > user. Privileged endpoints check the requester’s role; users can’t escalate via skills or the API.

Coder sandbox

The coder skill wraps every shell command in bubblewrap with:

  • Read-only view of the host filesystem.
  • A writable bind-mount of just the project directory the agent is working in.
  • Network on (needed for npm, pip, git).
  • No access to other users’ workspaces.

So an agent that’s told “delete every file on the system” will, at worst, delete files inside its own project dir.

File-ownership enforcement

Every path passed to download / delete / shell is realpath-checked against the caller’s user directory before use. Symlinks can’t escape the workspace; the resolved path must still live under users/{callerId}/.

Media tokens

Some assets (images in chat bubbles, video previews, PDFs in iframes) need to authenticate but can’t carry a Bearer header. For those, the server mints short-lived (10-minute) URL-embedded media tokens on demand. Static long-lived URLs aren’t issued.

Encryption and backups

OE automatically encrypts registered provider API keys and other supported credentials, including Home Assistant and Telegram secrets, when saving them. Some records use a per-user key; global configuration uses the system key at users/_system/.master-key. Key files have 0600 permissions.

This protects a copied encrypted record when its key is not also available. It does not protect against someone who can read the OE process’s keys or memory. It is not whole-disk encryption: ordinary documents and conversation files are separate from these encrypted credential fields.

An ordinary .tar.gz backup includes the keys needed to restore credentials. Someone with that archive can recover those credentials. Use a password-protected .oeb export to protect the backup itself, and keep its password separately. Environment-only credentials need to be supplied again on the destination. Never remove master keys from a working installation or backup you expect to restore. See Backup and restore.

Network and provider data

  • HTTP 3737 serves the web UI/API; plain HTTP first-run setup is restricted to localhost on the OE host.
  • HTTPS 3739 is the installer’s default TLS entry point and supports browser microphone and USB features. Configure access for the interface you use; do not assume public inbound ports are required for a tunnel.
  • Cloud chat receives the context included in its requests. Remote STT receives recordings; remote TTS receives reply text. Local endpoints run where their configured addresses point. See Which model does what.
  • Optional tunnels, OAuth callbacks, and Telegram use the connections explained in Public and private access.

What OpenEnsemble does not protect against

  • A user with shell access to the host machine. They can read all the files. Don’t share host accounts.
  • A malicious provider — your prompts and the data you attach are sent to whichever cloud LLM you configured. Pick providers you trust.
  • A malicious skill you install. Skills are arbitrary JS. Owner/admin should review user-authored skills before allowing them broadly.
  • Your password being reused or trivial. Use a real password and consider using OS-level firewalling if your install is reachable from open networks.

Reporting issues

If you find a security issue, file at the project repo’s Issues — flag it as security so it’s triaged quickly.

This site uses Just the Docs, a documentation theme for Jekyll.