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

any OS with Docker
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:latest

Open 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.

VariantBest forKey features
PersonalIndividual daily useVoice, meeting mode, news, store prices, Spotify, desktop automation. Casual tone. No auth required.
BusinessTeams & companiesProfessional tone, multi-user JWT auth, rate limiting, Slack/Telegram/Discord channels.
ℹ️
Switching later

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+.

terminal
git clone https://github.com/Sehastrajit-S/Luna.git
cd Luna
npm install
npm run setup

The interactive setup prompt:

output
  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:

terminal
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 Docker

Docker (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:

terminal
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 variant

A .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.

1

Install

Run Luna-Setup-<version>.exe from Downloads, or build it yourself with npm run build:desktop (output in dist/desktop).

2

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.

3

Personalise

Your name, weather location and model can be set in Settings or in .env:

.env
user_name=your_name
weather_city=London
weather_lat=51.5074
weather_lon=-0.1278

LLM provider

Luna works with 8 providers out of the box. Pick one in Settings → AI model, or setllm_provider in .env.

Providerllm_providerKey neededNotes
Ollama (default)ollamaNoneFully local. Pull any model with ollama pull.
OpenAIopenai-compatibleopenai_api_keyAlso covers LM Studio, OpenRouter, Jan.ai, llama.cpp.
NVIDIA NIMnvidia-nimnvidia_nim_api_keyOpenAI-compatible NVIDIA-hosted or self-hosted NIM endpoint.
Anthropic Claudeanthropicanthropic_api_keyNative Messages API. Recommended for business.
Google Geminigooglegoogle_api_keyGemini 2.0 Flash by default. Long context, multimodal.
Groqgroqgroq_api_key~300 tok/s. Free tier. Fastest cloud option.
Coherecoherecohere_api_keyCommand R+. Strong RAG performance.
Mistral AImistralmistral_api_keyMistral Large. European-hosted, GDPR-friendly.

Example - switch to Anthropic:

.env
llm_provider=anthropic
anthropic_api_key=sk-ant-...
anthropic_model=claude-sonnet-4-5

Example - switch to Groq (free tier, fastest):

.env
llm_provider=groq
groq_api_key=gsk_...
groq_model=llama-3.3-70b-versatile
💡
OpenRouter - one key for everything

Use 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-4

Verify setup

terminal
# 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
output (doctor)
  ✓ Node.js 20.x
  ✓ npm 10.x
  ✓ Python 3.11
  ✓ Ollama running
  ✓ Docker available
⚠️
Port 8899 already in use

Kill any existing Luna process or change port=8900 in .env. See Troubleshooting for more.