Elowen

A self-hosted AI agent you can talk to, steer, and trust with real work.

Chat · Act · Automate · Extend

Docs · Getting started · CLI · Web UI · Architecture

Elowen is a personal AI agent that runs on your machine. Chat with it in the terminal, from the Web UI, Discord, or WhatsApp; it keeps the same projects, permissions, tools, and durable memory across every surface. It can investigate code, edit files, use a terminal, plan tasks, delegate focused work — and stop to ask when a decision belongs to you.

It is deliberately self-hosted: a Node.js daemon, SQLite, a Next.js Web UI, and plugins you can inspect, enable, or remove. Your provider accounts and project data stay under your control.

Start here

One-line install — provisions a fresh box end to end (Node.js, the elowen package, tmux, systemd services, the first admin) and leaves a running daemon and Web UI:

# Linux (Debian/Ubuntu)
curl -fsSL https://raw.githubusercontent.com/dragocz95/elowen/main/install.sh | bash

# Windows — installs into WSL2 (run in an elevated PowerShell)
irm https://raw.githubusercontent.com/dragocz95/elowen/main/install.ps1 | iex

Already have Node.js 22+? Install locally and onboard by hand:

npm install -g elowen
elowen setup
elowen

elowen setup walks through the local account, a project, an AI provider, optional memory embeddings, and code intelligence. A bare elowen opens the terminal chat; elowen doctor explains what is ready and what still needs attention.

Requirements: Node.js 22+ and tmux. The one-line installer takes care of both; on Windows it runs inside WSL2 because tmux and systemd are Linux-only.

The bootstrap script is deliberately thin — it does only what has to happen before Elowen exists on the machine, then hands the rest to elowen install, the project's own provisioner:

1. Preflight — confirms a Debian/Ubuntu (apt) system and ensures curl.
2. Node.js — installs Node.js 22+ from NodeSource when it is missing or too old; a suitable Node already present is left untouched.
3. Package — installs the global elowen package from npm (ELOWEN_VERSION pins a specific release).
4. Provision — hands over to elowen install, which sets up tmux, the systemd services (elowen-daemon, elowen-web, auto-update), an optional reverse proxy, and the first admin. The interactive wizard runs on the real terminal even under curl … | bash; pass ELOWEN_INSTALL_ARGS='--unattended …' for a fully non-interactive run.

It is safe to re-run: an existing install is never reprovisioned without confirmation (or ELOWEN_FORCE=1), and a globally-linked development checkout is refused outright so a reinstall can't detach it.

On Windows the PowerShell script enables WSL2, installs Ubuntu if needed, turns on systemd inside the distro, and then runs the exact same install.sh — a first-time WSL setup needs one reboot, after which you re-run the command. The Web UI is reachable from Windows at http://localhost:4500.

elowen chat                         # interactive terminal chat
elowen run "review this repository" # one streamed, non-interactive turn
elowen status                       # daemon and Web UI health
elowen up | down                    # manage local services

What you get

One agent, several useful surfaces

A look at Elowen

Built for work that lasts longer than a prompt

Elowen does more than answer the next message. A persistent goal gives a conversation a concrete outcome, subgoals, a turn budget, and a hard safety ceiling; it can pause when it needs you and resume with its bearings intact. While one turn is working, a durable message queue keeps your follow-up instead of losing it, and context compaction preserves the useful thread rather than resetting the conversation.

When one agent is not the right shape for the job, Elowen can delegate focused work to sub-agents on a different model. Their live status, tool activity, model, and result stay attached to the parent conversation, so delegation never becomes a black box. For larger work, missions turn one outcome into ordered phases and can assign a dedicated pilot to plan it and an overseer to judge progress, reviews, and uncertain decisions — each with its own executor, selected per mission rather than forced globally.

That autonomy stays deliberate. Per-user model ceilings and granular tool rules decide what may run, what must ask, and what is denied; approval is a real pause in the work, not a best-effort notification. A mission can also use an isolated Git worktree and pull-request workflow, keeping concurrent work away from a shared checkout and holding publication behind its verification gate.

A brain that has context without becoming opaque

Elowen's embedded brain is an in-process, provider-agnostic agent. It exposes a per-user model catalog, configurable limits, optional reasoning, permission gates, goals, and a durable queue for mid-turn messages. Before a normal user turn, Elowen assembles the relevant policy, memory, skills, and plugin context. Dynamic plugin context can be placed before or after the user's text, remains ephemeral, and is never written into the conversation history — so time, runtime state, and other live signals stay fresh without being treated as durable instructions.

Architecture in one view

Browser ──> Next.js Web UI ──> Elowen daemon ──> SQLite
                                      │
Terminal CLI ─────────────────────────┤
Chat-platform plugins ────────────────┤
                                      └──> tmux workers / embedded brain

The daemon owns state, scheduling, agent sessions, plugins, and the API. The Web UI talks through a same-origin backend-for-frontend proxy; the CLI is a client of the same daemon. See Architecture for the precise boundaries.

Documentation

The full user guide lives at elowen.dragocz.dev and in docs/site:

Contributor references: development · plugin development · API · testing.

Development

npm test              # backend test suite
npm run build         # type-check and build the daemon
npm run check         # lint + typecheck
cd web && npm test    # web test suite
cd web && npm run dev # run the Web UI in dev mode

See CONTRIBUTING before opening a pull request.

Built with

Elowen is a small, self-hosted stack of stable, modern tooling — no external services required.

License

MIT © the Elowen authors