Getting Started
Have Luna running in a few minutes with Docker, the Windows app, or from source, then reach it from any device.
Quick start
docker run -d --name luna --restart unless-stopped \
-p 127.0.0.1:8899:8899 -v luna_data:/app/data \
ghcr.io/sehastrajit-s/luna:latestOpen http://localhost:8899 and choose a model in Settings. Prefer an app? Get the Windows installer from Downloads. Want it on your phone? See Setup: Remote over Tailscale.
Choose a variant
Luna ships in two flavours. The setup wizard configures whichever you pick.
| Variant | Best for | Key features |
|---|---|---|
| Personal | Individual daily use | Voice, meeting mode, news, store prices, Spotify, desktop automation. Casual tone. No auth required. |
| Business | Teams & companies | Professional tone, multi-user JWT auth, rate limiting, Slack/Telegram/Discord channels. |
Change luna_variant=personal or luna_variant=business in your .env at any time and restart. No data is lost.
Setup from source
Clones the repo, walks you through variant and provider selection, installs all dependencies, and pulls Ollama models. Needs Node.js 18+ and Python 3.10+.
git clone https://github.com/Sehastrajit-S/Luna.git
cd Luna
npm install
npm run setupThe interactive setup prompt:
Choose your variant
1. Personal
Voice, desktop automation, Spotify, maps.
Casual AI companion. Single user. No auth required.
2. Business
Professional team assistant. Multi-user JWT auth.
Rate limiting, Slack/Telegram/Discord channels.
Enter 1 or 2 (default: 1): _After setup completes:
npm run web # Luna at http://localhost:8899
npm run serve:tailscale # same, shared to your devices over Tailscale
npm run luna -- docker:business # business variant in DockerDocker (any device)
The easiest path for servers, NAS boxes, or any machine you don't want to install Python on. The image is ghcr.io/sehastrajit-s/luna (amd64 and arm64). From a clone of the repo:
docker compose -f deploy/compose.yml up -d # Luna + Ollama (CPU)
docker compose -f deploy/compose.yml -f deploy/compose.gpu.yml up -d # NVIDIA GPU
docker compose -f deploy/compose.cloud.yml up -d # cloud model, no Ollama
docker compose -f deploy/compose.business.yml up -d # business variantA .env is optional: settings saved in the browser persist in the data volume. See Docker for volumes and upgrades.
Desktop app
The desktop app adds push-to-talk (Alt+L), a tray icon, and desktop automation on Windows.
Install
Run Luna-Setup-<version>.exe from Downloads, or build it yourself with npm run build:desktop (output in dist/desktop).
Pick a server
Settings → Server: This computer starts a local server with your Python (install server/requirements.txt once), or uses one already running on port 8899. Remote over Tailscale finds your Luna on another machine.
Personalise
Your name, weather location and model can be set in Settings or in .env:
user_name=your_name
weather_city=London
weather_lat=51.5074
weather_lon=-0.1278LLM provider
Luna works with 8 providers out of the box. Pick one in Settings → AI model, or setllm_provider in .env.
| Provider | llm_provider | Key needed | Notes |
|---|---|---|---|
| Ollama (default) | ollama | None | Fully local. Pull any model with ollama pull. |
| OpenAI | openai-compatible | openai_api_key | Also covers LM Studio, OpenRouter, Jan.ai, llama.cpp. |
| NVIDIA NIM | nvidia-nim | nvidia_nim_api_key | OpenAI-compatible NVIDIA-hosted or self-hosted NIM endpoint. |
| Anthropic Claude | anthropic | anthropic_api_key | Native Messages API. Recommended for business. |
| Google Gemini | google | google_api_key | Gemini 2.0 Flash by default. Long context, multimodal. |
| Groq | groq | groq_api_key | ~300 tok/s. Free tier. Fastest cloud option. |
| Cohere | cohere | cohere_api_key | Command R+. Strong RAG performance. |
| Mistral AI | mistral | mistral_api_key | Mistral Large. European-hosted, GDPR-friendly. |
Example - switch to Anthropic:
llm_provider=anthropic
anthropic_api_key=sk-ant-...
anthropic_model=claude-sonnet-4-5Example - switch to Groq (free tier, fastest):
llm_provider=groq
groq_api_key=gsk_...
groq_model=llama-3.3-70b-versatileUse openai-compatible with OpenRouter to access Claude, Gemini, GPT-4o, Mistral, and hundreds of other models through a single API key and pay-per-token pricing:
llm_provider=openai-compatible
openai_base_url=https://openrouter.ai/api/v1
openai_api_key=sk-or-...
openai_model=anthropic/claude-opus-4Verify setup
# Check all tools are installed
npm run luna -- doctor
# Check the running server is healthy
npm run health
# Quick terminal chat (server must be running)
npm run chat ✓ Node.js 20.x
✓ npm 10.x
✓ Python 3.11
✓ Ollama running
✓ Docker availableKill any existing Luna process or change port=8900 in .env. See Troubleshooting for more.