Getting started

Use this page when you want the shortest copy-paste path from install to first request.

Prerequisites

• one provider or upstream you want to route to
• provider credentials if that upstream needs them
• a terminal on macOS or Linux

1. Install LunarGate

macOSLinux

brew tap lunargate-ai/tap
brew install lunargate

curl -fsSL https://get.lunargate.ai/install.sh | sh

If you prefer to build from source, you can also build the binary from the gateway/ repository and run it with the same config.yaml shown below.

2. Save a minimal config.yaml

Pick one provider pattern and save it as config.yaml.

Tip

If you are just validating the gateway locally, choose the provider you already have access to and ignore the rest for now. You can add more providers later without changing your client integration pattern.

OpenAI / GPT-5.2Ollama / qwen3.5Anthropic / Claude Sonnet 4.5DeepSeek / DeepSeek ChatAbacus / GPT-5.2Gemini / gemini-2.5-flashGroq / Llama 3.3 70BTogether / GPT-OSS 20BOpenRouter / OpenAI GPT-4o

providers:
  openai:
    api_key: "${OPENAI_API_KEY}"

routing:
  routes:
    - name: "default"
      targets:
        - provider: openai
          model: gpt-5.2

providers:
  ollama:
    base_url: "http://127.0.0.1:11434"
    timeout: 10m
    timeout_mode: ttft
    temperature: 1.0
    top_p: 0.95
    top_k: 64

routing:
  routes:
    - name: "default"
      targets:
        - provider: ollama
          model: qwen3.5

Use timeout_mode: ttft for slow local Ollama models when startup can take a long time but you do not want to cut off the response after it begins streaming.

providers:
  anthropic:
    api_key: "${ANTHROPIC_API_KEY}"

routing:
  routes:
    - name: "default"
      targets:
        - provider: anthropic
          model: claude-sonnet-4-5

providers:
  deepseek:
    type: "openai"
    api_key: "${DEEPSEEK_API_KEY}"
    base_url: "https://api.deepseek.com/v1"
    compatibility_profile: "deepseek"

routing:
  routes:
    - name: "default"
      targets:
        - provider: deepseek
          model: deepseek-chat

providers:
  abacus:
    type: "openai"
    api_key: "${ABACUS_API_KEY}"
    base_url: "https://routellm.abacus.ai/v1"

routing:
  routes:
    - name: "default"
      targets:
        - provider: abacus
          model: gpt-5.2

providers:
  gemini:
    type: "openai"
    api_key: "${GEMINI_API_KEY}"
    base_url: "https://generativelanguage.googleapis.com/v1beta/openai"

routing:
  routes:
    - name: "default"
      targets:
        - provider: gemini
          model: gemini-2.5-flash

providers:
  groq:
    type: "openai"
    api_key: "${GROQ_API_KEY}"
    base_url: "https://api.groq.com/openai/v1"

routing:
  routes:
    - name: "default"
      targets:
        - provider: groq
          model: llama-3.3-70b-versatile

providers:
  together:
    type: "openai"
    api_key: "${TOGETHER_API_KEY}"
    base_url: "https://api.together.xyz/v1"

routing:
  routes:
    - name: "default"
      targets:
        - provider: together
          model: "openai/gpt-oss-20b"

providers:
  openrouter:
    type: "openai"
    api_key: "${OPENROUTER_API_KEY}"
    base_url: "https://openrouter.ai/api/v1"

routing:
  routes:
    - name: "default"
      targets:
        - provider: openrouter
          model: "openai/gpt-4o"

Optional: enable LunarGate observability

If you want the gateway to send request data to the LunarGate Dashboard on app.lunargate.ai, extend the same config with:

data_sharing:
  enabled: true
  share_prompts: true
  share_responses: true
  api_key: "${LUNARGATE_GATEWAY_API_KEY}"

Create that gateway API key in the Gateways section of app.lunargate.ai.

You do not need to set backend_url unless you want to override the gateway default.

Warning

Turning on share_prompts or share_responses changes the privacy boundary of your deployment. Keep them off unless you explicitly want request inspection in the LunarGate Dashboard on app.lunargate.ai.

Optional: require inbound API keys

If you want the gateway itself to require API keys on /v1/*, add:

security:
  enabled: true
  provider: "api_key"
  api_key:
    keys:
      - name: "local-dev"
        value: "${LUNARGATE_CLIENT_API_KEY}"

This minimal config already supports OpenAI-style Authorization: Bearer <key> by default.

3. Export environment variables and run

OpenAIOllamaAnthropicDeepSeekAbacusGeminiGroqTogetherOpenRouter

export OPENAI_API_KEY="your-key"
export LUNARGATE_CLIENT_API_KEY="your-gateway-client-key" # only if security.provider=api_key
lunargate --config ./config.yaml

lunargate --config ./config.yaml

export ANTHROPIC_API_KEY="your-key"
lunargate --config ./config.yaml

export DEEPSEEK_API_KEY="your-key"
lunargate --config ./config.yaml

export ABACUS_API_KEY="your-key"
lunargate --config ./config.yaml

export GEMINI_API_KEY="your-key"
lunargate --config ./config.yaml

export GROQ_API_KEY="your-key"
lunargate --config ./config.yaml

export TOGETHER_API_KEY="your-key"
lunargate --config ./config.yaml

export OPENROUTER_API_KEY="your-key"
lunargate --config ./config.yaml

The gateway listens on http://127.0.0.1:8080 by default.

Small but important detail:

• your app still talks to an OpenAI-compatible API
• the main client change is usually just base_url
• the gateway config is where provider choice and routing policy live

4. Smoke test the gateway

curl http://127.0.0.1:8080/health
curl http://127.0.0.1:8080/v1/models

curl http://127.0.0.1:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.2",
    "messages": [
      {"role": "user", "content": "Give me one sentence about LunarGate."}
    ]
  }'

If security.provider: api_key is enabled, include your client key:

curl http://127.0.0.1:8080/v1/models \
  -H "Authorization: Bearer ${LUNARGATE_CLIENT_API_KEY}"

curl http://127.0.0.1:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${LUNARGATE_CLIENT_API_KEY}" \
  -d '{
    "model": "openai/gpt-5.2",
    "messages": [
      {"role": "user", "content": "Give me one sentence about LunarGate."}
    ]
  }'

If your config includes an embeddings-capable model, you can also smoke test:

curl http://127.0.0.1:8080/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ollama/nomic-embed-text-v2-moe",
    "input": [
      "LunarGate can proxy embeddings.",
      "Embeddings are useful for retrieval."
    ]
  }'

The fastest embeddings-friendly starting points today are:

• OpenAI-compatible hosted providers that expose /v1/embeddings
• local Ollama with a model like nomic-embed-text-v2-moe

5. Use a normal OpenAI client

from openai import OpenAI

client = OpenAI(
    api_key="your-gateway-client-key-or-not-needed-if-auth-is-off",
    base_url="http://127.0.0.1:8080/v1",
)

resp = client.chat.completions.create(
    model="openai/gpt-5.2",
    messages=[{"role": "user", "content": "Say hello from LunarGate"}],
)

print(resp.choices[0].message.content)

What to do next

1. Go to Examples if you want a runnable Python, Node, Streamlit, or Docker Compose app.
2. Use Python Ollama embeddings with Poetry if you want the smallest /v1/embeddings smoke test.
3. Read lunargate/auto and autorouting if you want the gateway to choose model tiers for you.
4. Keep the configuration overview and detailed config pages open while editing YAML.