Nolune is an open-source, self-hosted AI companion with a persistent identity, long-term memory, and the ability to use real computers.
Run Nolune's always-on brain on a Mac mini, home server, or spare computer. Then connect the desktop app on your other machines so Nolune can work with their screens, apps, files, and terminals from one interface.
Unlike a faceless agent dashboard, Nolune has a voice, personality, mood, and animated presence you can make your own. Your companion and its memories stay on hardware you control.
How it works
1. Give Nolune a home
Install the Nolune server on an always-on macOS or Linux machine. It keeps your companion running, stores its memory, and coordinates its work. Either use the desktop app's Install on this computer button, or run the one-liner:
curl -fsSL https://nolune.dev/install.sh | bash
The installer downloads the server, prepares ~/.nolune, starts the server in the foreground so you can watch its logs, and opens http://localhost:26559. The first browser has to be paired: run nolune pair on the machine you just installed on and enter the eight-digit code it prints. Then follow the onboarding.
Paired browsers and desktop apps stay signed in. The desktop app pairs with the same codes: enter the server URL and a code from nolune pair. Review or revoke devices, or mint a code for the next one, under Settings → Connections → Pair a device. The installer adds ~/.nolune/bin to your PATH; until you open a new shell, use ~/.nolune/bin/nolune pair.
Press Ctrl-C to stop the server and nolune gateway to start it again. To keep it running without a terminal, opt in to the background service with nolune gateway install (see Install).
2. Connect your computers
Install the desktop app on the computers where you want Nolune to act. Each connected machine becomes another place where your companion can see the screen, use apps, work with files, and run commands.
For example, Nolune can live on a Mac mini at home while you talk to it through the desktop app on your MacBook.
3. Ask it to do the work
Talk to Nolune normally. It can research something on the web, organize files, work inside an app, run a command on a connected machine, or continue a task while you are away.
Computer-use actions appear through a visible desktop overlay. You choose which machines to connect and grant the operating-system permissions they need.
Why Nolune
A companion, not a control panel
Nolune is designed around one persistent character rather than a collection of disposable chats. Its personality lives in soul.md, its mood changes over time, and its animated skin gives it a recognizable presence.
One mind across multiple computers
The server holds Nolune's identity and memory: one companion per server. Connected desktop apps give it eyes and hands on other machines. Computers, chats, and the people it talks to are contexts of that one identity, never separate companions, so what it learns in one place it knows everywhere. You can keep the server somewhere reliable and interact with the same companion from wherever you work.
Memory you can inspect
Nolune stores memories as ordinary files organized by topic. You can read them, edit them, back them up, or remove them. Keyword and semantic retrieval bring relevant memories back into later conversations.
Proactive when you want it to be
Heartbeats and schedules let Nolune check in, follow recurring routines, and start useful work without waiting for a new message every time.
Yours from end to end
Nolune is self-hosted and BYOK. There is no required Nolune cloud account, and Nolune does not impose its own usage limits. Your model provider's pricing and limits still apply.
Your companion
Nolune · Little Moon — a curious lavender crescent. One familiar identity across your computers, with memories and personality that stay yours.
Our design system documents the visual language, reusable UI patterns, and accessibility rules. Run the client and open /design-system for the interactive reference.
Capabilities
- Computer use — Observe a window, click, type, scroll, and use apps on the server machine or a connected desktop, explicitly and with the permissions you grant; a screenshot is a one-shot capture of one window taken during an action, never a recording (docs/computer-use.md).
- Remote files and shell — Read and edit files or run commands on the server and connected computers.
- Persistent memory — Remember people, preferences, projects, and shared moments across conversations.
- Voice — Speak through optional text-to-speech and voice mode.
- Web and communication — Search the web, work with email, and use installed integrations.
- Skills and MCP — Add new workflows and connect external tools without changing Nolune's core.
- Schedules and heartbeats — Run recurring routines and initiate conversations proactively.
Install
There are two ways to get a server. Both end the same way: the nolune binary in ~/.nolune/bin, a workspace in ~/.nolune, and the server running in the foreground. No background service is created unless you ask for one.
Desktop app
Download the desktop app from GitHub Releases. Builds are available for macOS, Windows, and Linux.
On first run, choose Install on this computer. The app downloads the server for your platform, prepares the workspace, starts the server, and opens your companion. Nothing to paste and no terminal required. Show logs reveals the server output if you want it, and Use nightly builds sits behind an advanced toggle. The server runs while the app is open and starts again with it; the desktop app's Run in background setting hands it to a user-level service so it keeps running after you quit.
If you already run a server elsewhere, choose Connect to an existing server instead and enter its URL and auth token. That is how a laptop reaches the companion living on a Mac mini at home.
One-line installer
The script does the same on macOS or Linux and leaves the server running in the foreground:
curl -fsSL https://nolune.dev/install.sh | bash
It is a thin wrapper: it downloads the binary and hands over to nolune onboard and nolune gateway. Set NOLUNE_CHANNEL=nightly for nightly builds (rebuilt from every push to main) or NOLUNE_DIR for a custom directory. NOLUNE_INSTALL_CUA_DRIVER=1 also runs nolune cua install for computer use; it is off by default, so headless servers install nothing they cannot use.
The nolune command
Everything the installers do, you can do yourself:
| Command | What it does |
|---|
nolune onboard | Prepares ~/.nolune and config.toml with a generated auth token. Safe to rerun. --json prints the result for scripts, --port picks the port |
nolune gateway | Runs the server in the foreground and prints nolune: ready <url> once it listens (nolune gateway run is the explicit form) |
nolune gateway install | Registers a user-level launchd agent (macOS) or systemd user unit (Linux) that runs the gateway, and starts it |
nolune gateway uninstall | Stops and removes that service; data is untouched |
nolune gateway start / stop / restart / nolune gateway status / nolune gateway logs | Manage the service once installed |
nolune pair | Prints a one-time code so a browser or the desktop app can sign in |
nolune restore <archive> | Replaces the companion with a companion.tar.gz backup (from Export in Settings → Data or the create_backup tool) by sending it to the running server, which validates it and swaps it in; the current data is not kept. Asks first; --yes skips the question |
nolune config show / set / unset / email add / email remove | Shows or changes the companion's timezone, name, API keys, GitHub token, and SMTP/IMAP accounts in the files the Settings page writes; the server picks them up on the next message. show never prints secret values, and secrets (API keys, the token, email passwords) are read from stdin only, never from arguments. The companion changes its own settings with this command through its built-in configure-nolune skill |
nolune federation invite / accept / peers / confirm / revoke / rotate | Pairs this companion with another one, on this machine or elsewhere, through the running server: invite prints a one-time invite line once, accept redeems one given as an argument or on stdin (never from a URL), lists peers with their state and last sighting, pairs a peer that redeemed your invite, withdraws trust, replaces the signing key and tells every peer. The same actions live under ; see |
Service registration is per user and needs no elevated privileges. It is not available on Windows yet; run nolune gateway there.
The release workflow runs on v* tags; manual runs must select a v* tag. It publishes server binaries and macOS, Windows, and Linux desktop artifacts. Nothing in this workflow provisions or updates running servers. To exercise the pipeline from any branch without creating a release, run it manually with dry_run enabled; the binaries are attached to the workflow run as artifacts instead.
Architecture
server/ Rust + Axum — always-on brain, tools, memory, and embedded web client
client/ SvelteKit 5 — companion interface
desktop/ Tauri 2 — native client and computer-use bridge
landing/ SvelteKit — public website and documentation
| Layer | Technology |
|---|
| Server | Rust, Axum, Tokio |
| LLM | Anthropic, OpenAI or OpenRouter API key, or a ChatGPT login through the local Codex binary (docs/providers.md) |
| Web client | SvelteKit 5, Tailwind CSS |
| Desktop | Tauri 2 |
| Memory | File-based storage with keyword and vector search |
| Extensions | Skills and Model Context Protocol |
| Distribution | Native binaries, launchd, and systemd |
Data layout
Everything important is stored as files under ~/.nolune:
~/.nolune/
├── config.toml
├── browser_sessions.json paired browsers and desktop apps (hashes only)
└── instances/
└── companion/ the one companion this server hosts
├── soul.md personality definition
├── heartbeat.md proactive behavior
├── mood.json emotional state
├── memory/ long-term memory library
├── drops/ autonomous creative artifacts
├── uploads/ user-uploaded files
├── skills/ installed skills
└── chats/ conversation history
Configuration
Most settings are available through the interface. Advanced configuration lives at ~/.nolune/config.toml. docs/providers.md covers the model providers: setup, keys, model ids and what each one can do.
| Environment variable | Description |
|---|
NOLUNE_HOME | Data directory, defaults to ~/.nolune |
NOLUNE_AUTH_TOKEN | API token override. The token is for automation and the CLI; browsers and the desktop app pair for a revocable session instead and are unaffected when it changes |
NOLUNE_PUBLIC_URL | Public URL for the server. Defaults to http://localhost:<port>; set it when you reach Nolune through another address so shared file links work |
NOLUNE_CUA_DRIVER | Path of a Cua Driver binary to use instead of the one nolune cua install put under the workspace or the one on PATH. The driver lets the companion use the server machine itself; a headless server simply has no such target. See docs/computer-use.md |
NOLUNE_CUA_RELEASE_URL | Mirror that nolune cua install fetches the pinned Cua Driver assets from (<url>/<asset name>) instead of the upstream GitHub release; the pinned checksum is enforced either way |
ANTHROPIC_API_KEY | Anthropic API key override |
OPENAI_API_KEY | OpenAI API key override |
OPENROUTER_API_KEY | OpenRouter API key override |
BRAVE_SEARCH_API_KEY | Brave Search API key override (the web search tool) |
ELEVENLABS_API_KEY | ElevenLabs API key override (voice) |
NOLUNE_CODEX_BIN | Path of the codex binary for the Codex provider, instead of the one on PATH; it must be the release Nolune pins (Settings › Connections names it). Codex logs in with ChatGPT and holds no API key |
RUST_LOG | Logging level, defaults to info |
Updates
Nolune checks for updates automatically. When one is out, the Update available pill in the web interface applies it: a server the desktop app started is updated and restarted by the app itself, and a server from the one-line installer runs its own update script. To update from a terminal instead:
~/.nolune/bin/update
Then restart the server: nolune gateway restart if it runs as a background service, otherwise stop it with Ctrl-C and run nolune gateway again (or reopen the desktop app, which restarts the server it manages). The desktop app's own updater only updates the app.
The Cua Driver behind computer use is pinned per Nolune release and never updated on its own, not by Nolune and not through the driver's self-updater: when an update moves the pin, nolune cua status reports the installed driver as not the pinned version and nolune cua install installs the new one. On a computer running the desktop app, the same install is a button — Settings › Computer use › Install driver — so no terminal is needed there. Computer use is supported on macOS; on Linux and Windows the pinned driver installs but nolune cua status reports the host as unsupported until a release turns it on. A host without a graphical session (no DISPLAY or WAYLAND_DISPLAY on Linux, no Aqua login on macOS, no SESSIONNAME on Windows) reports headless and never starts the driver.
Uninstall
curl -fsSL https://nolune.dev/uninstall.sh | bash
Keep your data while removing the server:
KEEP_DATA=1 curl -fsSL https://nolune.dev/uninstall.sh | bash
The script delegates to nolune uninstall --keep-data or nolune uninstall --yes, which you can also run directly. Without a terminal the script defaults to keeping your data.
Development
See the Nolune launch cutover checklist for repository, domain, and release setup.
./scripts/dev.sh runs the server and the web client together with hot reload,
against a throwaway workspace; see CONTRIBUTING.md.
To run each piece by hand:
# Server
cd server && cargo run
# Web client
cd client && pnpm install && pnpm dev
# Desktop app
cd desktop && pnpm install && pnpm tauri dev
# Landing site
cd landing && pnpm install && pnpm dev
Use pnpm, not npm, for the JavaScript workspaces. See CONTRIBUTING.md for the complete development setup.
Security
Computer use and remote access are powerful capabilities. Only connect machines you control, keep your authentication token private, and review the permissions granted to the Cua Driver on each machine. Nolune never records the screen: computer use is explicit and permissioned, a screenshot is a one-shot capture of one window taken during an action, and there is no continuous capture; see docs/computer-use.md.
See SECURITY.md to report a vulnerability.
License
MIT — see LICENSE.
Computer use is driven by a pinned Cua Driver 0.28.2 (MIT, Cua AI, Inc.), verified by checksum and never updated on its own; see THIRD_PARTY_NOTICES.md.
