Getting Started — L.U.N.A. Docs

Choose a variant

Luna ships in two flavours. Choose the one that matches your use case — the setup wizard will configure everything automatically.

Variant	Best for	Key features
Personal	Individual daily use	Voice, vision, Spotify, maps, desktop automation. Casual tone. No auth required.
Business	Teams & companies	Professional 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.

One-liner setup

The fastest path — clones the repo, walks you through variant + provider selection, installs all dependencies, and pulls Ollama models automatically.

terminal

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

The interactive setup prompt:

output

  Choose your variant

  1. Personal
     Voice, vision, 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

# Personal — full desktop stack
luna dev

# Business — Docker with rate limiting and auth enforced
luna docker:business

Docker (any device)

The easiest path for servers, NAS boxes, or any machine you don't want to install Python on. Requires Docker Desktop or Docker Engine.

Personal — local Ollama (CPU)

terminal

cp .env.personal.example .env   # edit model / location
docker compose up -d
open http://localhost:8899

Personal — NVIDIA GPU

terminal

docker compose -f compose.yml -f compose.gpu.yml up -d

Personal — cloud LLM (no Ollama)

terminal

# Set llm_provider + API key in .env first
docker compose -f compose.cloud.yml up -d

Business variant

terminal

cp .env.business.example .env
# Edit .env — set jwt_secret, business_name, llm_provider
docker compose -f compose.business.yml up -d

💡

luna docker command

After npm install, the CLI auto-detects the right compose file based on luna_variant and llm_provider in your .env:

npm run luna -- docker        # auto-detect
npm run luna -- docker:business  # force business
npm run luna -- docker:gpu    # force GPU

Desktop install

Required for voice, camera, screen vision, Electron window, and OS-level automation.

Tool	Version	Notes
Node.js	18+	Required by Electron and Vite.
Python	3.10+	Required by the FastAPI backend.
Ollama	Latest	Only if using local LLM inference.

Run the setup wizard

terminal

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

This installs all Node and Python dependencies, creates .env, and pulls Ollama models. Takes about 2 minutes on a fast connection.

Edit .env

Open .env and confirm the model name, your location for weather, and optionally your name:

.env

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

Start Luna

terminal

luna dev         # Electron + Vite + FastAPI
# or
luna backend     # FastAPI only (use the browser UI)
# or
luna web         # Backend + browser UI, no Electron

LLM provider

Luna works with 8 providers out of the box. Switch by setting llm_provider in.env — no code changes, no restart of anything else.

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:

.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
luna doctor

# Check the running backend is healthy
luna health

# Quick terminal chat (backend must be running)
luna 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.