# Jan User Guide

Jan is an open-source desktop application that runs large language models (LLMs) directly on your own computer. It is a privacy-first alternative to cloud chat apps: you can download open models like Llama, Gemma, Qwen, and GPT-OSS and chat with them completely offline, or connect to cloud providers such as OpenAI, Anthropic, Google, and Mistral when you want frontier models. Jan also exposes everything it runs through an OpenAI-compatible local API server, ships a terminal CLI, and supports tools through the Model Context Protocol (MCP).

This guide walks you from installation to advanced workflows. It is written for everyday users — no prior AI or command-line experience is assumed, though a Command Line section is included for those who want it.

> [!NOTE]
> Jan is a product of **Menlo Research**. The desktop app, models, and documentation are open source. Everything in this guide is derived directly from the Jan source code at the documented commit — every command, setting, and default reflects what the application actually does.

---

## Table of Contents

1. [What Jan Does](#1-what-jan-does)
2. [Quick Start](#2-quick-start)
3. [Installation](#3-installation)
4. [Your First Chat](#4-your-first-chat)
5. [Managing Models](#5-managing-models)
6. [Local vs. Cloud Models](#6-local-vs-cloud-models)
7. [Connecting Cloud Providers](#7-connecting-cloud-providers)
8. [Model Settings & Tuning](#8-model-settings--tuning)
9. [Assistants](#9-assistants)
10. [Projects](#10-projects)
11. [Files, Images & Documents](#11-files-images--documents)
12. [Connectors & Tools (MCP)](#12-connectors--tools-mcp)
13. [The Local API Server](#13-the-local-api-server)
14. [The Jan CLI](#14-the-jan-cli)
15. [Coding Agents (Claude Code & OpenClaw)](#15-coding-agents-claude-code--openclaw)
16. [Settings Reference](#16-settings-reference)
17. [Your Data & Privacy](#17-your-data--privacy)
18. [How Jan Works (Concepts)](#18-how-jan-works-concepts)
19. [Troubleshooting](#19-troubleshooting)
20. [Frequently Asked Questions](#20-frequently-asked-questions)
21. [Quick Reference](#21-quick-reference)

---

## 1. What Jan Does

Jan brings open-source AI into a single, easy-to-use desktop app. At its core, Jan lets you:

- **Run AI models locally** — Download LLMs from Hugging Face and run them entirely on your own machine using CPU, GPU, or Apple Silicon. No internet required once a model is downloaded, and no data leaves your device.
- **Connect to cloud providers** — Add an API key to use OpenAI (GPT), Anthropic (Claude), Google (Gemini), Mistral, Groq, xAI (Grok), and more, all in the same chat interface.
- **Organize work with Projects** — Group related conversations, share an assistant persona, and upload documents that the AI can reference.
- **Create custom Assistants** — Save reusable instructions so you don't repeat yourself every chat.
- **Extend with tools (MCP)** — Give models the ability to search the web, read files, query databases, or call external services through the Model Context Protocol.
- **Serve an OpenAI-compatible API** — Run a local server at `http://127.0.0.1:1337` so your own apps and scripts can use your local models as a drop-in replacement for the OpenAI API.
- **Drive coding agents from the terminal** — Use the `jan` CLI to wire tools like Claude Code to a model running on your own hardware.

> [!TIP]
> The single biggest reason people choose Jan is **privacy**. When you use a local model, your conversations, files, and prompts never leave your computer. You only send data to a third party if you deliberately connect a cloud provider.

### Who Jan Is For

- **Privacy-conscious users** who want AI without sending data to the cloud.
- **Developers** who want a local OpenAI-compatible endpoint for building apps offline.
- **Tinkerers and researchers** who want full control over which models they run and how.
- **Anyone with capable hardware** who wants to avoid per-message API costs.

---

## 2. Quick Start

Get from zero to your first conversation in three steps.

> [!IMPORTANT]
> Jan automatically downloads a default foundation model the first time you launch it. You need an internet connection for this initial download, but after that the model runs offline.

1. **Install Jan** — Download the installer for your operating system from [jan.ai](https://jan.ai/) and run it. See [Installation](#3-installation) for platform-specific steps.
2. **Wait for the default model** — On first launch, Jan downloads its default model in the background. When the download finishes, you're ready.
3. **Start chatting** — Type a message and press Enter. That's it.

Try one of these prompts to get a feel for it:

```text
Explain quantum computing in simple terms.
Help me write a Python function to sort a list.
What are the pros and cons of electric vehicles?
```

> [!TIP]
> Jan comes pre-configured with [Exa](https://exa.ai) for web search via MCP. To enable it, add your Exa API key under **Settings → MCP Servers** and toggle the Exa server on. Once active, the AI can answer questions about current events.

After the basics, explore:

- **The Hub** (left sidebar) to download more local models — see [Managing Models](#5-managing-models).
- **Settings → Model Providers** to connect a cloud account — see [Connecting Cloud Providers](#7-connecting-cloud-providers).

---

## 3. Installation

Jan is available for Windows, macOS, and Linux. Download the version for your platform from [jan.ai](https://jan.ai/) or the [GitHub Releases page](https://github.com/janhq/jan/releases).

### Download Links

| Platform | Package |
|----------|---------|
| **Windows** | `jan.exe` installer (also on the [Microsoft Store](https://apps.microsoft.com/detail/xpdcnfn5cpzlqb)) |
| **macOS** | `jan.dmg` (universal — works on both Apple Silicon and Intel Macs) |
| **Linux (Debian/Ubuntu)** | `jan.deb` |
| **Linux (portable)** | `jan.AppImage` |
| **Linux (Flatpak)** | [Flathub: `ai.jan.Jan`](https://flathub.org/apps/ai.jan.Jan) |

=== "Windows"

    1. Download `jan.exe` (or install from the Microsoft Store).
    2. Run the installer and follow the prompts.
    3. Launch Jan from the Start menu.

=== "macOS"

    1. Download `jan.dmg`.
    2. Open the disk image and drag **Jan** into your **Applications** folder.
    3. Launch Jan from Applications. The universal build runs natively on both Apple Silicon (M-series) and Intel Macs.

=== "Linux"

    **Debian/Ubuntu (.deb):**

    ```bash
    sudo apt install ./jan.deb
    ```

    **AppImage (portable):**

    ```bash
    chmod +x jan.AppImage
    ./jan.AppImage
    ```

    **Flatpak:**

    ```bash
    flatpak install flathub ai.jan.Jan
    ```

### System Requirements

Local models use your computer's memory (RAM) and processor, so your hardware determines which models you can run comfortably.

| Platform | Minimum | Notes |
|----------|---------|-------|
| **macOS** | 13.6+ | 8 GB RAM for ~3B models, 16 GB for ~7B, 32 GB for ~13B. Apple Silicon uses Metal automatically. |
| **Windows** | 10 or later | GPU acceleration for NVIDIA, AMD, and Intel Arc. |
| **Linux** | Most modern distributions | GPU acceleration available; see the [llama.cpp engine](#5-managing-models) backend options. |

> [!NOTE]
> A GPU backend is only preferred when a GPU reports **at least 6 GB of VRAM**. Below that, Jan runs models on the CPU. llama.cpp builds require an **AVX2**-capable CPU; very old CPUs need a `noavx`/CPU-compatible backend.

> [!TIP]
> A good rule of thumb: choose models that use less than **80% of your available RAM**. For an 8 GB machine, stay under ~6 GB models; for 16 GB, under ~13 GB.

### Linux on ARM64

Native ARM64 Linux builds are tracked in [issue #4543](https://github.com/janhq/jan/issues/4543); follow the linked how-to for current guidance.

---

## 4. Your First Chat

When you launch Jan, the main window is a chat interface. Here's the everyday flow.

### Sending a Message

1. Type into the input box at the bottom.
2. Press **Enter** to send (Shift+Enter for a new line).
3. Watch the response stream in token-by-token.

Each conversation is a **thread**. Threads are saved automatically and listed in the left sidebar, so you can return to past conversations at any time.

### Choosing a Model

Above or near the chat input is the **model selector**. Click it to switch between any local model you've downloaded and any cloud model from a connected provider. The model you pick applies to the current thread.

### Temporary Chats

Jan supports a temporary chat mode for one-off questions you don't want saved as a permanent thread. Temporary chats are kept separate from your saved thread history.

### Stopping and Regenerating

While a model is responding you can stop generation. You can also regenerate a response or edit your previous message and resend it.

> [!TIP]
> The response footer shows the **token speed** (tokens per second) for local models — a quick way to see how fast your hardware is running a given model.

---

## 5. Managing Models

Models are the AI "brains" Jan runs. This section covers downloading, importing, and removing **local** models. For cloud models, see [Connecting Cloud Providers](#7-connecting-cloud-providers).

Local models run through **llama.cpp** and use a file format called **GGUF**. On Apple Silicon Macs, Jan can additionally run **MLX** models.

### Download from the Hub (Recommended)

The **Hub** is Jan's built-in model browser, connected to [Hugging Face's model hub](https://huggingface.co/models).

1. Open the **Hub** from the left sidebar.
2. Browse or search for a model, then click a model to see its details.
3. Click **Download** on the version that fits your hardware.

Each model in the Hub shows a colored **fit pill** based on your hardware:

| Pill | Meaning |
|------|---------|
| **Fits** | Runs comfortably on your machine |
| **May be slow** | Will run but may be sluggish |
| **Won't fit** | Too large for your available memory |

Quantization tiers are grouped as **Small**, **Balanced**, or **Large**, with a **Recommended** tag on the default download.

> [!NOTE]
> No data is downloaded to compute the fit status — it is calculated from your hardware specs and the model's metadata only.

While a model downloads, the model name and percentage appear in the top bar. Click **×** to cancel at any time. If a download fails, it is cleared from the queue and a toast notification appears; click **Download** again to retry.

> [!WARNING]
> If a download is interrupted, partial model data may not be saved, which can make re-downloading awkward on slow connections (see [issue #8000](https://github.com/janhq/jan/issues/8000)). Let downloads finish before quitting Jan.

### Import from Hugging Face by ID

You can pull any GGUF model directly by its Hugging Face repository ID:

1. Visit [Hugging Face Models](https://huggingface.co/models) and find a GGUF model that fits your machine.
2. Copy the **model ID** (e.g. `TheBloke/Mistral-7B-v0.1-GGUF`).
3. Paste it into the **Search** bar on Jan's **Hub** page.
4. Choose a quantized version to download.

> [!IMPORTANT]
> Some models (for example, Meta's gated Llama models) require a **Hugging Face Access Token**. Get a token from [Hugging Face settings](https://huggingface.co/settings/tokens) and enter it under **Settings → General → Others → HuggingFace Token** before importing.

### Use a Model from the Hugging Face Website

On any model page on Hugging Face, click **Use this model**, then under **Local Apps** select **Jan**. The model opens directly in Jan ready to download.

### Import a Local GGUF File

If you already have a `.gguf` file on disk:

1. Open **Settings → Llama.cpp** (under Model Providers).
2. Click **Import** and select your GGUF file.

Jan **links to the file in place without copying it**, so it doesn't duplicate disk usage. This is ideal for models you downloaded via a browser or share with other apps.

> [!NOTE]
> For multi-shard (split) GGUF models, point Jan at **shard 1** (the standard llama.cpp convention). The remaining shards are picked up automatically.

### MLX Models (Apple Silicon Only)

On Apple Silicon Macs, Jan can run **MLX** models in addition to GGUF. Manage them under **Settings → MLX**. MLX is Apple's machine-learning framework and often delivers excellent performance on M-series chips.

### Deleting Models

- **One model:** Click the trash icon next to a model in **Settings → Llama.cpp** (or **MLX**), then confirm.
- **All managed models:** Click **Delete All** in the Models section of the engine settings. Jan shows the total space to be freed and removes every managed download at once.

> [!TIP]
> **Delete All** only removes models Jan downloaded and manages. Models you imported yourself (linked in place) are left untouched — only the link is removed, not your original file.

### Jan's Own Models

Beyond third-party models, Jan ships a family of foundation models tuned for different tasks:

| Model | Best for |
|-------|----------|
| **Jan-v3-4B** | General-purpose instruction following |
| **Jan-Code-4B** | Code generation and reasoning |
| **Jan-v2-VL** | Vision-language tasks (understanding images) |
| **Jan-Nano** | Smaller, lightweight general use |
| **Lucy** | Lightweight assistant model |

Browse these in the Hub like any other model.

---

## 6. Local vs. Cloud Models

Jan runs models two ways, and you can freely mix both in the same app — even switch between them mid-project.

| | **Local models** | **Cloud models** |
|---|------------------|------------------|
| **Where they run** | On your machine (CPU/GPU/Apple Silicon) | On a provider's servers |
| **Privacy** | Fully private; nothing leaves your device | Prompts and files are sent to the provider |
| **Internet** | Only needed to download the model | Required for every request |
| **Cost** | Free after download | Pay the provider per usage / API key |
| **Hardware** | Limited by your RAM/VRAM | No local hardware needed |
| **Model size** | Up to what your machine can handle | Access the largest frontier models |
| **Setup** | Download a model | Paste an API key |

**Local is the default.** Use local models for private, offline, no-cost work. Use cloud models when you need the very largest or most capable models and don't mind sending data to a provider.

---

## 7. Connecting Cloud Providers

To use a hosted model, add the provider's API key.

1. Go to **Settings → Model Providers**.
2. Select a provider (e.g. **OpenAI** or **Anthropic**).
3. Paste your **API Key** into the field.
4. Pick one of the provider's models from the model selector and start chatting.

After you add a key for a built-in provider, Jan automatically reads the provider's available models and their capabilities (such as `tools` and `vision`) — no manual model list to maintain.

### Built-in Providers

Jan ships preconfigured base URLs for these providers (you only need to add a key):

| Provider | Get API key | Default Base URL |
|----------|-------------|------------------|
| **OpenAI** | [platform.openai.com](https://platform.openai.com/account/api-keys) | `https://api.openai.com/v1` |
| **Anthropic** | [console.anthropic.com](https://console.anthropic.com/settings/keys) | `https://api.anthropic.com/v1` |
| **Google (Gemini)** | [aistudio.google.com](https://aistudio.google.com/apikey) | `https://generativelanguage.googleapis.com/v1beta/openai` |
| **Azure OpenAI** | [Azure OpenAI Studio](https://oai.azure.com/) | `https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1` |
| **Mistral** | [console.mistral.ai](https://console.mistral.ai/api-keys/) | `https://api.mistral.ai/v1` |
| **Groq** | [console.groq.com](https://console.groq.com/keys) | `https://api.groq.com/openai/v1` |
| **xAI (Grok)** | [console.x.ai](https://console.x.ai/) | `https://api.x.ai/v1` |
| **OpenRouter** | [openrouter.ai](https://openrouter.ai/settings/keys) | `https://openrouter.ai/api/v1` |
| **MiniMax** | [platform.minimax.io](https://platform.minimax.io/) | `https://api.minimax.io/v1` |
| **Hugging Face** | [huggingface.co/settings/tokens](https://huggingface.co/settings/tokens) | `https://router.huggingface.co/v1` |
| **NVIDIA NIM** | [NVIDIA NGC](https://org.ngc.nvidia.com/setup/api-keys) | `https://integrate.api.nvidia.com/v1` |

> [!TIP]
> **OpenRouter** is a single key that gives access to hundreds of models from many vendors — a convenient way to try lots of cloud models without separate accounts.

### Custom & Self-Hosted Endpoints

Running your own server, or using a provider Jan doesn't list? Jan can connect to any **OpenAI-compatible** or **Anthropic-compatible** endpoint.

1. Go to **Settings → Model Providers** and add a custom provider.
2. Set the **Base URL** to your endpoint (remember to include `/v1` for OpenAI-style APIs).
3. Set the correct **API type** (OpenAI-Compatible vs. Anthropic-Compatible).
4. Add an API key if your endpoint requires one.

> [!CAUTION]
> Two common mistakes cause every request to fail: choosing the **wrong API type** (OpenAI vs. Anthropic), and a **base URL missing `/v1`** (which produces a `404` on every request). Double-check both.

### API Key Fallbacks

For custom endpoints you can configure multiple API keys as fallbacks. If one key fails with a `401`/`403`, Jan rotates to the next. If you see **"key rotation exhausted,"** it means *every* configured key failed — they're all invalid or unauthorized.

---

## 8. Model Settings & Tuning

Model settings control how the AI "thinks" and how efficiently it runs. Open them by clicking the **gear icon** next to your selected model in the chat interface. A panel slides open on the right.

### Core Settings

| Setting | What it does | Plain-English guidance |
|---------|--------------|------------------------|
| **Context Size** | How much text the model remembers at once | The model's working memory. Larger = remembers more, uses more RAM/VRAM. Default `8192`, up to `131072`. |
| **GPU Layers** | How much of the model runs on your graphics card | More layers on GPU = faster, but needs more VRAM. Start high; reduce if you get out-of-memory errors. |
| **Temperature** | Creativity vs. predictability | Low (0.1–0.3) = focused/consistent. High (0.7–1.0) = creative/varied. **0.7** is a good general default. |
| **Top K** | How many word choices to consider | Smaller (20–40) = focused. Larger (80–100) = more variety. |
| **Top P** | Another variety control (nucleus sampling) | Works with Top K. `0.9` is a good value. Lower = focused, higher = creative. |
| **Min P** | Minimum probability a word needs to be picked | Filters out very unlikely words. Default usually fine. |
| **Repeat Last N** | How far back to check for repetition | Helps prevent the model repeating itself. |
| **Repeat Penalty** | How strongly to avoid repeating words | Higher (1.1–1.3) reduces repetition. Too high makes responses awkward. |
| **Presence Penalty** | Encourages new topics | **Cloud/remote providers only** — no effect on local llama.cpp models. |
| **Frequency Penalty** | Reduces word repetition by frequency | **Cloud/remote providers only** — no effect on local llama.cpp models. |

### Quick Recipes

**Most users:**
- Temperature `0.7`, max out GPU Layers (reduce only on memory errors), leave the rest at defaults.

**Creative writing:**
- Temperature `0.8–1.0`, Top P `0.95`.

**Factual / technical work:**
- Temperature `0.1–0.3`.

**Quick fixes:**
- *Too repetitive?* Raise Temperature or Repeat Penalty.
- *Out of memory?* Lower GPU Layers or Context Size.
- *Too random?* Lower Temperature.
- *Too slow?* Raise GPU Layers (if you have VRAM) or lower Context Size.

### Reasoning Mode (llama.cpp only)

For models that support extended thinking (e.g. DeepSeek-R1, QwQ), a **brain icon** appears in the chat input toolbar when using the llama.cpp provider. Set the reasoning mode:

| Mode | Behavior |
|------|----------|
| **Auto** | Model decides when to reason internally |
| **On** | Always reason before responding |
| **Off** | Skip reasoning, reply directly |

This setting persists per model and does not require reloading. It is not shown for cloud providers.

### Fit to Hardware

When **Fit to Hardware** is enabled, Jan automatically caps the context size based on your model and available memory. It is **on by default** for Windows and Linux with a discrete GPU, and **off by default** for integrated GPUs and macOS (Apple Silicon's unified memory makes the cap less critical). With fit disabled you can set context freely — but values beyond your hardware's capacity cause slowdowns or out-of-memory errors.

### Advanced Sampling (llama.cpp only)

These only apply to local llama.cpp models and have no effect on cloud providers.

**Mirostat** — an alternative sampling algorithm that targets a fixed perplexity, producing more consistent output length and coherence:

| Setting | Guidance |
|---------|----------|
| **Mirostat Mode** | Off = standard top-p/k. V1 or V2 = Mirostat (V2 is more stable). |
| **Mirostat Learning Rate** | Lower (0.05) = more stable; higher (0.2) = adapts faster. |
| **Mirostat Target Entropy** | Higher = more variety; lower = tighter focus. |

**Output Constraints** — force a specific output format:

| Setting | What it does |
|---------|--------------|
| **Grammar File** | Path to a GBNF grammar file; constrains every token to match (great for code, lists, custom formats). |
| **JSON Schema File** | Path to a JSON Schema file; enforces a specific JSON structure in every response. |

> [!TIP]
> Most users never need to touch advanced sampling. The defaults are chosen to work well on typical hardware — only experiment if you have a specific need.

For engine-wide tuning (continuous batching, KV cache precision, multi-GPU offload, RoPE scaling), see the [llama.cpp engine settings](#16-settings-reference) in the Settings Reference and the **Admin Guide** for the full reference.

---

## 9. Assistants

An **Assistant** is a model paired with a saved set of instructions and configuration — so you don't have to re-type the same guidance every conversation. Think of them as reusable personas.

Manage assistants under **Settings → Assistants**.

### Managing Assistants

- **Add:** Click the `+` button in the Assistants panel and enter your instructions.
- **Edit:** Click the pencil (✏️) icon on an assistant card to update its name, description, or instructions.
- **Delete:** Click the trash (🗑️) icon to remove one you no longer need.

### Writing Good Instructions

Each assistant has its own instructions that guide its behavior. For example:

```text
Act as a software engineering mentor focused on Python and JavaScript.
Provide detailed explanations with code examples when relevant.
Use markdown formatting for code blocks.
```

Or:

```text
Respond in a casual, friendly tone. Keep explanations brief and use simple language.
Provide examples when explaining complex topics.
```

**Best practices:**
- Be clear and specific about the behavior you want.
- State preferences for formatting, tone, and style.
- Include examples — they improve compliance.
- Use different assistants for different tasks (translation, travel planning, code review, etc.).

### Switching Assistants in Chat

You can switch assistants without opening Settings: click the **+** icon in the chat input, then **Use Assistant**, and pick one. The active assistant shows a checkmark.

### Assistants in Projects

When you create a Project you can assign an assistant to it, so every conversation in that project automatically uses the chosen persona and instructions. See [Projects](#10-projects).

---

## 10. Projects

**Projects** organize your AI work around a topic or goal. Each project has its own conversations, an assigned assistant, and a shared set of files — all in one place.

### Creating a Project

1. Press **⌘ P** (or click **New Projects** in the left sidebar).
2. Give it a name that reflects the goal — e.g. "Product Manager," "Research," "Code Review."
3. Start a conversation. All conversations inside the project share the same assistant and files.

### Project Assistant

Each project can have an assigned [Assistant](#9-assistants). Its instructions apply automatically to every conversation in the project. Click **Edit** to change it.

### Project Files

Upload documents to a project and reference them in any conversation within it:

- Click **Add** in the **Files** panel to upload.
- Uploaded files are **chunked and indexed**, then available as context across all the project's conversations.
- Ask questions about documents, extract information, or use them as background reference.

The file panel shows each file with its size and chunk count.

Supported formats include **PDFs, Markdown, Office documents (DOCX, XLSX, PPTX), code files, and more**.

> [!NOTE]
> Project files use Jan's built-in retrieval (RAG) system. The AI retrieves the most relevant chunks of your documents to answer each question, rather than reading every file in full.

---

## 11. Files, Images & Documents

Jan supports two ways to work with files: **chat attachments** (one message) and **project files** (shared context). Project files are covered in [Projects](#10-projects); this section covers chat attachments.

### Attaching Files to a Message

1. Click the **+** button at the bottom-left of the chat input.
2. Choose **Add Images**, **Add Audio**, or **Add documents or files**.
3. Select your file — a progress bar appears while it uploads.
4. Type your question and send.

You can also **drag and drop** files onto the chat input, or **paste images** from your clipboard.

### Images Require a Vision Model

The **Add Images** option only appears when the active model has the **`vision`** capability. If your current model isn't vision-capable, the option is hidden — switch to a vision model (for example **Jan-v2-VL**, available in the Hub) to enable image attachments.

### Audio Requires an Audio-Capable Model

The **Add Audio** option appears only when the active model supports audio input. Supported formats are **WAV** and **MP3**. Audio files show a preview chip with the filename and duration before sending.

### File Privacy

All files are processed **locally** on your machine. With a local model, your files never leave your device. If you use a cloud provider (e.g. OpenAI, Anthropic), files are sent to that provider's API as part of the request.

---

## 12. Connectors & Tools (MCP)

The **Model Context Protocol (MCP)** is an open standard that lets AI models use external tools and data sources — web search, file access, databases, GitHub, Slack, and custom programs. Jan acts as an **MCP host**: you add MCP servers, and compatible models can call their tools during a conversation.

### Requirements

To use MCP tools effectively, your model must support **tool calling**:

- **Cloud models:** Choose a model that shows the **tools** capability in the model picker (e.g. Claude Sonnet/Opus, GPT-4-class models). For built-in providers like Anthropic, Jan reads model capabilities automatically after you add your key.
- **Local models:** Enable tool calling in the model's parameters (the **Model Capabilities** edit button). Note that many open-source models are not good at tool use — you may need to try a few.

You also need **Node.js** and/or **Python** installed, since most MCP servers run as `npx` or Python commands. Download them from [nodejs.org](https://nodejs.org/) and [python.org](https://www.python.org/).

### Adding an MCP Server

1. Go to **Settings → MCP Servers**.
2. Click the **+** in the upper-right of the MCP box.
3. Fill in the server details. For example, to add the [Browser MCP](https://browsermcp.io/):
   - **Server Name:** `browsermcp`
   - **Command:** `npx`
   - **Arguments:** `@browsermcp/mcp`
   - **Environment Variables:** (leave empty unless the server needs them)
4. Confirm the server activates successfully.

Some MCP servers also need a companion browser extension or external setup (Browser MCP, for instance, uses a Chrome extension) — follow the specific server's instructions.

### Tool Approvals & Permissions

Granting a model access to tools is a security decision. Jan puts you in control:

- **Per-call approval (default):** When a model wants to use a tool, an approval panel appears **inline inside the tool card** in the chat, showing the exact arguments before you accept or deny.
- **Allow all:** To pre-approve every tool, enable **Allow All MCP Tool Permissions** under **Settings → MCP Servers**.

> [!CAUTION]
> Be deliberate with tool permissions. A malicious prompt or a compromised tool could take unintended actions or expose data ("prompt injection"). Review tool arguments before approving, especially for tools that can write files, run commands, or access the web. Only enable **Allow All** for servers you fully trust.

> [!NOTE]
> Active MCP connections consume part of the model's context window. The more tools and the longer the conversation, the more memory is used and the slower responses can be. Enable only the tools you need.

### Built-in Web Search (Exa)

Jan comes pre-configured with [Exa](https://exa.ai) for web search. Add your Exa API key under **Settings → MCP Servers** and toggle the Exa server on to let the AI answer questions about current events.

---

## 13. The Local API Server

Jan includes a built-in, **OpenAI-compatible API server** that runs entirely on your computer, powered by llama.cpp. Use it as a drop-in replacement for cloud APIs to build private, offline AI apps and scripts.

### Starting the Server

1. Go to **Settings → Local API Server**.
2. Click **Start Server**.

The server is ready when the logs show:

```text
JAN API listening at http://127.0.0.1:1337
```

### Testing with cURL

Replace `YOUR_MODEL_ID` with an available model's ID, and the bearer token with your configured API key:

```bash
curl http://127.0.0.1:1337/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer secret-key-123" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "messages": [{"role": "user", "content": "Tell me a joke."}]
  }'
```

```text
{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "choices": [
    { "message": { "role": "assistant", "content": "Why did the..." } }
  ]
}
```

### Server Configuration

Open the **Configuration** button (top-right of the Local API Server page) to adjust:

| Setting | Default | What it does |
|---------|---------|--------------|
| **Server Host** | `127.0.0.1` | `127.0.0.1` = only your computer can reach it (most secure). `0.0.0.0` = reachable from other devices on your network (use with caution). |
| **Server Port** | `1337` | Change to any free port (e.g. `8000`) if 1337 is taken. |
| **API Prefix** | `/v1` | Base path for endpoints. The chat endpoint becomes `http://127.0.0.1:1337/v1/chat/completions`. |
| **API Key** | (empty) | A secret clients must send as `Authorization: Bearer YOUR_KEY`. Leave empty to disable auth. |
| **Trusted Hosts** | — | Comma-separated hostnames allowed to access the server — an extra layer of security when exposed on a network. |
| **Request Timeout** | — | Seconds the server waits for the local model before giving up. Increase for large models on slow hardware. |

> [!WARNING]
> If you set **Server Host** to `0.0.0.0`, your local models become reachable by other devices on your network. **Always set an API Key** in that case. Leaving authentication disabled while bound to `0.0.0.0` exposes your models to anyone who can reach your machine.

### Advanced Settings

| Setting | Default | What it does |
|---------|---------|--------------|
| **Execute Tools on Server** | Disabled | When on, MCP tool calls made through `/v1/chat/completions` run server-side instead of being returned to the client. Leave off if your client handles tool execution. |
| **CORS** | Enabled | Allows browser-based web apps on other domains to call the API. Disable if only scripts/CLI tools use it. |
| **Verbose Server Logs** | Enabled | Detailed real-time logs of requests and responses. Very useful for debugging. |

### Server Troubleshooting

| Symptom | Likely cause / fix |
|---------|--------------------|
| **Connection refused** | Server isn't running, or your app points to the wrong host/port. |
| **401 Unauthorized** | API key missing from the `Authorization` header, or incorrect. |
| **404 Not Found** | The `model` ID doesn't match an available model, or the request URL/API prefix is wrong. |
| **CORS error (browser)** | Enable the CORS toggle in Jan's settings. |
| **Port 1337 in use** | Another process (often a previous Jan instance) holds the port. Free it or change the port — see [Troubleshooting](#19-troubleshooting). |

> [!TIP]
> Keep **Verbose Server Logs** enabled while developing so you can see exactly what your app sends to the model in the "Server Logs" view.

---

## 14. The Jan CLI

The `jan` command-line tool lets you serve local models and launch AI agents from your terminal — no cloud account, no usage fees, full privacy. Models downloaded in the Jan desktop app are automatically available to the CLI, and vice-versa (they share the same data folder).

> [!NOTE]
> The CLI is available since **Jan 0.7.8**. It is installed automatically the first time you launch the desktop app — no separate setup. You can uninstall or reinstall it any time from **Settings → General → Jan CLI**.

On macOS/Linux the installer writes the binary to `/usr/local/bin/jan` when writable, otherwise `~/.local/bin/jan`. Make sure the chosen directory is on your `$PATH`.

### Command Overview

```text
Usage: jan <COMMAND>

Commands:
  serve    Load a local model and expose it at localhost:6767/v1 (auto-detects LlamaCPP or MLX)
  launch   Start a local model, then launch an AI agent with it pre-wired
  threads  List and inspect conversation threads saved by the Jan app
  models   List and load models installed in the Jan data folder
  help     Print this message or the help of the given subcommand(s)

Options:
  -h, --help       Print help
  -V, --version    Print version
```

### `jan serve`

Load a local model and expose it at `http://localhost:6767/v1` as an OpenAI-compatible API. Auto-detects llama.cpp or MLX.

```bash
jan serve [MODEL_ID] [OPTIONS]
```

| Option | Description | Default |
|--------|-------------|---------|
| `MODEL_ID` | Model to load. A local model ID or a Hugging Face repo ID (e.g. `unsloth/Qwen3.5-9B-GGUF`). Omit to pick interactively. | — |
| `--port` | Port to listen on (`0` = random free port) | `6767` |
| `--api-key` | API key required of clients | `""` |
| `-d, --detach` | Run in the background and print the PID | — |
| `--embedding` | Treat the model as an embedding model (not yet supported with llamacpp on the CLI) | — |
| `--timeout` | Seconds to wait for the model server to become ready | `120` |
| `-v, --verbose` | Print full server logs | — |

**Examples:**

```bash
jan serve                              # pick a model interactively
jan serve jan-code-4b                  # serve a specific installed model
jan serve unsloth/Qwen3.5-9B-GGUF      # download from HuggingFace, then serve
jan serve jan-code-4b --detach         # run in the background
jan serve jan-code-4b --port 8080      # serve on a custom port
```

When no model ID is given, an interactive selector appears. If no models are installed yet, Jan automatically downloads its default foundation model.

> [!WARNING]
> Since Jan 0.8.0, llama-server runs in **router mode** under a single process. The flags `--ctx-size`, `--n-gpu-layers`, `--threads`, and `--fit` are accepted for backwards compatibility but are currently **ignored** — per-model inference settings come from the router preset generated by the desktop app (`<data-folder>/llamacpp/router.preset.ini`). Tune them from the desktop UI for now.

> [!NOTE]
> Environment variables with the `LLAMA_ARG_` prefix are forwarded to the underlying llama-server router. For example, `export LLAMA_ARG_HOST=0.0.0.0` binds the router to a specific host.

### `jan launch`

Start a local model, then launch an AI agent CLI with it pre-wired — connection environment variables are set automatically.

```bash
jan launch [PROGRAM] [OPTIONS]
```

| Option | Description | Default |
|--------|-------------|---------|
| `PROGRAM` | Agent to launch: `claude` or `openclaw` (omit to pick interactively) | — |
| `--model` | Model to load (omit to pick interactively) | — |
| `--port` | Port for the model server | `6767` |
| `--api-key` | Exported as `OPENAI_API_KEY` and `ANTHROPIC_AUTH_TOKEN` | `jan` |
| `-v, --verbose` | Print full server logs | — |

**Examples:**

```bash
jan launch                                   # pick agent + model interactively
jan launch claude                            # pick a model, then run Claude Code
jan launch claude --model jan-code-4b        # specific model with Claude Code
jan launch openclaw --model jan-code-4b      # wire OpenClaw to a local model
```

### `jan models`

```bash
jan models list              # list all installed models
jan models load <MODEL_ID>   # serve a model (alias for jan serve)
jan models load-mlx <ID>     # load an MLX model (macOS / Apple Silicon only)
```

### `jan threads`

Inspect conversation threads saved by the desktop app:

```bash
jan threads list                    # list all threads
jan threads get <ID>                # get a thread's metadata
jan threads messages <THREAD_ID>    # list all messages in a thread
jan threads delete <ID>             # permanently delete a thread
```

### Common CLI Workflows

```bash
jan serve jan-code-4b --fit          # serve a model for any OpenAI-compatible client
jan launch claude --model jan-code-4b # run Claude Code against a local model
jan serve jan-code-4b --detach       # run a model in the background
jan models list                      # see all installed models
```

> [!TIP]
> When you pass a Hugging Face repo ID that isn't downloaded yet, `jan serve` and `jan launch` will download it from Hugging Face automatically before serving.

---

## 15. Coding Agents (Claude Code & OpenClaw)

Jan can power autonomous coding agents with a model running on **your own hardware** — keeping inference local while you use agent tooling you already know.

> [!IMPORTANT]
> The **in-app** OpenClaw integration was removed in **Jan v0.7.9** due to resource and security concerns. Jan no longer runs agents inside the desktop app. Instead, agents run as **external programs** that you point at a local Jan model via the CLI.

### How It Works

The `jan launch` command:

1. Starts the model and serves it on a local OpenAI- and Anthropic-compatible endpoint.
2. Sets the agent's connection details automatically — environment variables like `OPENAI_BASE_URL` / `ANTHROPIC_BASE_URL`, the API key, and the model name. (For OpenClaw, Jan writes a provider entry to `~/.openclaw/openclaw.json` instead.)
3. Runs the agent in your terminal, sending its requests to your local model.

```bash
jan launch claude                                  # Claude Code against a local model
jan launch claude --model janhq/Jan-code-4b-gguf   # specific model
jan launch openclaw --model janhq/Jan-code-4b-gguf # OpenClaw with a local model
```

> [!WARNING]
> Install the agent CLI yourself first — `jan launch` runs Claude Code or OpenClaw but does not install them. Follow [Claude Code's docs](https://docs.claude.com/en/docs/claude-code) or OpenClaw's instructions. (If OpenClaw isn't installed, Jan falls back to running it via `npx`.)

---

## 16. Settings Reference

Open Settings via the gear icon in the bottom-left corner of Jan. The settings are organized into the following pages.

| Settings page | What you configure |
|---------------|--------------------|
| **Model Providers** | Local engines (Llama.cpp, MLX) and cloud providers; import/remove models; API keys |
| **General** | Jan Data Folder location, App Logs, HuggingFace Token, Jan CLI install, Factory Reset |
| **Appearance / Interface** | Theme and color, code-block colors |
| **Attachments** | File-attachment settings (e.g. size limits) |
| **Privacy** | Analytics opt-in/out |
| **Shortcuts** | Keyboard shortcuts |
| **Extensions** | Manage installed extensions |
| **Local API Server** | OpenAI-compatible server (host, port, API key, CORS) — see [section 13](#13-the-local-api-server) |
| **MCP Servers** | Add/manage MCP tool servers and permissions — see [section 12](#12-connectors--tools-mcp) |
| **HTTPS Proxy** | Route traffic through a proxy; optionally ignore SSL certificates |
| **Hardware** | View CPU/RAM/GPU, toggle GPU acceleration |
| **Assistant** | Manage assistant personas — see [section 9](#9-assistants) |
| **Claude Code** | Claude Code integration settings |

### Hardware

Under **Settings → Hardware** you can view CPU, RAM, and GPU usage and specs, and toggle **GPU Acceleration**. Jan manages GPU usage automatically — it switches to GPU mode when supported and selects the GPU with the highest VRAM. Verify your selected GPU(s) appear in **System Monitor** (in Jan's footer).

### Interface & Theme

Customize Jan's color theme and code-block colors under **Settings → Interface**. Jan also includes a built-in **spell check** for your messages.

### HTTPS Proxy

Route Jan's traffic through an HTTPS proxy under **Settings → HTTPS Proxy**:

1. Enable the proxy toggle.
2. Enter your proxy server in the format:

```text
http://<user>:<password>@<domain or IP>:<port>
```

- **Ignore SSL Certificates** lets Jan accept self-signed or unverified certificates — useful for corporate proxies or development, but only enable it on networks you trust.

> [!NOTE]
> The proxy affects model **downloads** but not remote (cloud) model usage. Download speeds may drop slightly due to encryption overhead.

### Jan Data Folder

Change where Jan stores your data under **Settings → General → Jan Data Folder**:

1. Click the pencil icon to edit the location.
2. Choose a new, **empty** directory and click **Select**.
3. Confirm — Jan duplicates your data into the new location (the original remains intact) and restarts.

See [Your Data & Privacy](#17-your-data--privacy) for the folder layout.

### Factory Reset

**Settings → General → Reset To Factory Settings** restores Jan to its initial state.

> [!CAUTION]
> Factory reset **permanently deletes all chat history, downloaded models, and settings**. It cannot be undone. Use it only as a last resort for serious, persistent issues. You'll be asked to type **RESET** to confirm, and can optionally keep the current data-folder location.

---

## 17. Your Data & Privacy

Jan stores everything locally on your filesystem in open formats (mostly JSON and YAML). Your data is yours alone.

### Where Your Data Lives

| Platform | Data folder |
|----------|-------------|
| **Windows** | `%APPDATA%\Jan\data` |
| **macOS** | `~/Library/Application Support/Jan/data` |
| **Linux** | `~/.local/share/Jan/data` (resolves via `XDG_DATA_HOME`) |

Open it quickly from **Settings → General → App Logs → Open Logs**, or via terminal:

```bash
# Windows
cd %APPDATA%/Jan/data
# macOS
cd ~/Library/Application\ Support/Jan/data
# Linux
cd ~/.local/share/Jan/data
```

### Folder Layout

```text
/assistants/
  /jan/
    assistant.json          # the default Jan assistant
/extensions/
  extensions.json
  /@janhq/                  # bundled extensions (llamacpp, mlx, rag, ...)
/files/                     # uploaded files
/logs/
  app.log                   # all app, server, and engine logs
/llamacpp/
  router.preset.ini         # per-model inference settings (router mode)
  /backends/<version>/<backend>/   # downloaded llama.cpp builds
  /models/
    <org>/<repo>/
      model.yml
      model.gguf
/mlx/
  /models/
    <model_id>/
      model.yml
/threads/
  /<thread_id>/
    messages.jsonl          # the conversation
    thread.json             # thread metadata
```

### Model Metadata (`model.yml`)

Each installed model has a `model.yml` describing it:

```yaml
model_path: llamacpp/models/janhq/Jan-v3-4B-base-instruct-gguf/Jan-v3-4b-base-instruct-Q4_K_XL.gguf
name: Jan-v3-4B-base-instruct-gguf
size_bytes: 2999182272
embedding: false
model_sha256: 1dc700f26bfb10e53d1b2daebd86d4c5f2accc50fe13acd863c59453f9abfa48
```

### Logs

Everything is written to `logs/app.log`, tagged by source:

- **`[APP]`** — core application logs
- **`[SERVER]`** — local API server activity
- **`[SPECS]`** — hardware information
- **`[llamacpp-router]`** — local model (llama.cpp) output, the best source when a model fails to load or crashes

> [!WARNING]
> When sharing logs for support, **redact private or sensitive information**. The Jan team retains submitted logs for only **24 hours**, so report issues promptly.

### Privacy Summary

- **Local models:** prompts, chats, and files never leave your machine.
- **Cloud providers:** your prompts and any attached files are sent to that provider's API as part of each request.
- **Analytics:** controlled under **Settings → Privacy** — opt out if you prefer.

---

## 18. How Jan Works (Concepts)

A short conceptual tour for the curious. You don't need this to use Jan, but it helps explain behavior.

### Local Inference Engines

- **llama.cpp** is the engine that runs GGUF models on your CPU, GPU, or Apple Silicon. Originally created by Georgi Gerganov and maintained by the [ggml-org/llama.cpp](https://github.com/ggml-org/llama.cpp) community, it runs LLMs efficiently on consumer hardware with no specialized accelerator or cloud needed.
- **MLX** is Apple's framework for running models on Apple Silicon; Jan offers it as an alternative engine on M-series Macs.

### Router Mode (Jan 0.8.0+)

Since v0.8.0, Jan runs llama.cpp as a single **router process** rather than launching a separate server for each model. The router loads and unloads models on demand (via llama.cpp's `POST /models/load` and `POST /models/unload` endpoints), so you no longer start or stop individual models manually — scheduling is automatic. Per-model settings live in `router.preset.ini` in your data folder, generated by the desktop UI.

### Hardware Backends

llama.cpp ships in many builds tuned for specific hardware (CUDA versions, Vulkan, Metal, and various CPU instruction sets like AVX2/AVX-512). Jan picks an appropriate backend automatically; you can override it under **Settings → Llama.cpp → Backend**. After installing a backend, Jan checks for required system libraries (CUDA, Vulkan, cuDNN) and tells you what to install if anything is missing.

### Capabilities

Models advertise capabilities such as **completion**, **tools** (function/tool calling), **vision** (image understanding), and **embedding**. Jan reads these to decide which UI options to show — for example, **Add Images** only appears for vision-capable models, and MCP tools require a tools-capable model.

### Quantization

Local models come in **quantized** versions — compressed to use less memory at a small quality cost. Common tiers (smallest to largest): `q4_0`/`q4_k_m` (4-bit, least memory), `q8_0` (8-bit, balanced), and full `f16` (16-bit, highest quality). Jan groups these as Small / Balanced / Large in the Hub. Smaller quantizations let you run bigger models on less hardware.

---

## 19. Troubleshooting

### How to Get Error Logs

Logs are the key to diagnosing problems.

- **In Jan:** Open **System Monitor** in the footer → choose **App Log**.
- **Via terminal (macOS example):**

```bash
tail -n 50 ~/Library/Application\ Support/Jan/data/logs/app.log
```

The file lives at `logs/app.log` inside your [data folder](#17-your-data--privacy). Look for `[APP]`, `[SERVER]`, `[SPECS]`, and `[llamacpp-router]` tags.

### Jan Won't Start or Crashes on Launch

**1. Corrupt settings/store file.** A damaged `store.json` can prevent startup. Fully quit Jan, then rename or delete it (Jan regenerates it):

- macOS: `~/Library/Application Support/Jan/data/store.json`
- Windows: `%APPDATA%\Jan\data\store.json`
- Linux: `~/.local/share/Jan/data/store.json`

This resets preferences but keeps your models and chat history.

**2. Another instance is already running.** Jan is single-instance — launching again just focuses the existing window. If you see no window, quit any stale process (system tray icon, or `ps aux | grep -i jan` / Task Manager) and relaunch.

**3. Port 1337 already in use.** Jan's Local API Server binds `127.0.0.1:1337` and does **not** fall back automatically. Free the port (see below) or change it in **Settings → Local API Server**.

### Model Won't Load or Crashes (llama.cpp)

Jan shows a model-error banner in chat and writes the cause to the logs. Common causes:

| Symptom | Cause | Fix |
|---------|-------|-----|
| Fails to load / stops with out-of-memory | Model + context needs more RAM/VRAM than available | Smaller/more quantized model; reduce **Context Size**; fewer GPU layers; or use CPU backend |
| "Ran out of context size" banner | Conversation longer than the context window | Click **Increase Context Size** in the banner, or raise **Context Size** (default `8192`, up to `131072`) |
| "Architecture not supported" | Backend older than the model, or not a text model | Update the backend (**Settings → Llama.cpp → Backend**) or use another model |
| "Router took too long to start and timed out" | Large model on slow disk | Wait and retry, use a smaller model, or store models on faster storage |
| "Model process encountered an unexpected error" / `cuda error:` / `ggml_vulkan` / `ggml_metal` | GPU driver/runtime issue or unsupported op | Update drivers, or switch backend (CPU / Vulkan / CUDA) |

**Common llama.cpp log messages** (prefixed `[llamacpp-router]` in `logs/app.log`):

| Log message | Likely cause | Resolution |
|-------------|--------------|------------|
| `unknown model architecture: '<arch>'` | Backend too old or unsupported model | Update the backend; confirm the model is supported |
| `error loading model` / `failed to load model` | Corrupt/truncated GGUF, partial download | Re-download the model |
| `missing tensor` / `wrong number of tensors` | Incomplete or mismatched GGUF | Re-download or try another quantization |
| `failed to allocate ... buffer` / `out of memory` / `cudaMalloc` | Not enough RAM/VRAM | Smaller model, lower context, fewer GPU layers |
| `request (N tokens) exceeds the available context size (M)` | Prompt longer than context | Increase context size or shorten the chat |
| `GGML_ASSERT(...)` | Backend bug or unsupported op | Try a different backend; report upstream if it persists |

### GPU Not Being Used (NVIDIA)

1. **Verify the GPU is detected.** Windows: NVIDIA Control Panel / Device Manager. Linux: `lspci | grep -i nvidia`.
2. **Install components.** NVIDIA driver **470.63.01+** (`nvidia-smi` to verify) and CUDA Toolkit **11.7+** (`nvcc --version`). On Linux also install `gcc-11 g++-11 cpp-11` and set `LD_LIBRARY_PATH`.
3. **Enable acceleration.** **Settings → Hardware** → confirm **GPU Acceleration** is on and your GPU appears in **System Monitor**.
4. **Restart Jan.**

### AMD, Intel & Apple GPUs

- **AMD / Intel (Vulkan):** Need up-to-date drivers with Vulkan support. On a `ggml_vulkan ... error`, update drivers and confirm Vulkan (`vulkaninfo` on Linux). Select the Vulkan backend under **Settings → Llama.cpp → Backend**.
- **Apple Silicon (Metal):** Used automatically on M-series Macs. A `ggml_metal ... error` usually means the model is too large for unified memory — use a smaller/more quantized model.
- **CPU requirement:** llama.cpp builds need **AVX2**. On older CPUs, pick a `noavx`/CPU-compatible backend.
- **GPU lost after sleep (Linux):** After suspend/resume the driver state can go stale ("No GPU detected"). Restart Jan to re-probe.

### "Failed to Fetch" / "Something's Amiss"

1. **Check hardware.** Use models under 80% of available RAM (8 GB → under 6 GB; 16 GB → under 13 GB).
2. **Check `ngl` (GPU layers).** If too high, lower it and increase gradually.
3. **Port conflicts.** Check whether `127.0.0.1:1337` is taken:

```bash
# macOS
netstat -an | grep 1337
# Windows
netstat -ano | find "1337"
# Linux
netstat -anpe | grep "1337"
```

Change the port under **Settings → Local API Server → Configuration → Server Port** if it's occupied.

4. **Factory reset** (last resort — deletes all data) or a clean reinstall.

### Cloud Provider Errors

| Status | Meaning | Fix |
|--------|---------|-----|
| `401` Unauthorized | Key missing, wrong, or revoked | Re-check the key; confirm the right provider |
| `403` Forbidden | Key lacks access to that model | Verify the key's permissions and model ID |
| `429` Rate limited | Too many requests, or out of quota | Wait and retry; add fallback keys; check billing |

For custom endpoints: a wrong **API type** (OpenAI vs. Anthropic) or a **base URL missing `/v1`** (causing `404`s) are the usual culprits. "key rotation exhausted" means *every* fallback key failed.

### Broken Build / Clean Reinstall

If Jan is stuck after an update, uninstall it and delete the data folder, then reinstall the latest version:

=== "macOS"

    ```bash
    rm -rf ~/Library/Application\ Support/Jan
    ```

=== "Windows"

    ```cmd
    cd C:\Users\%USERNAME%\AppData\Roaming
    rmdir /S Jan
    ```

=== "Linux"

    ```bash
    # .deb install
    sudo apt-get remove Jan
    # Data + config
    rm -rf ~/.local/share/Jan ~/.config/Jan
    ```

> [!WARNING]
> Deleting the data folder removes your downloaded models and chat history.

### Cannot Relocate Data Folder on Windows

If the in-app relocation fails, quit Jan fully, edit `%APPDATA%\Jan\settings.json`, and set the `data_folder` field (use double backslashes):

```json
{ "data_folder": "D:\\Jan" }
```

Optionally copy your old data over, save, and restart.

### Permission Denied (macOS extension install)

If you see `EACCES: permission denied` during extension install:

```bash
sudo chown -R $(whoami) ~/.npm
```

### Jan CLI: `jan` Opens the App Instead of the CLI (Windows)

Add the CLI binary directory to your `Path` environment variable:

```text
C:\Users\<username>\AppData\Local\Programs\Jan\resources\bin
```

Open a new terminal and run `jan` again (the binary is `jan.exe`).

### Default Ports

| Service | Port |
|---------|------|
| Jan Local API Server | `1337` |
| Jan CLI server (`jan serve`/`launch`) | `6767` |
| Jan documentation dev server | `3001` |

### Still Stuck?

Gather your error logs and system specs, then ask in the [Jan Discord](https://discord.gg/FTk2MvZwJH) `#🆘|jan-help` channel. Remove personal information first — logs are kept only 24 hours.

---

## 20. Frequently Asked Questions

**Q: Is Jan free?**
Yes. Jan is open-source software. Local models run at no cost after download. You only pay if you connect a cloud provider and use its paid API.

**Q: Does Jan work offline?**
Yes. Once you've downloaded a local model, you can chat fully offline. Only the initial model download and cloud providers need internet.

**Q: Where do my conversations go?**
Everything is stored locally in your [Jan data folder](#17-your-data--privacy) as plain JSON. Nothing is uploaded unless you use a cloud provider.

**Q: What model should I start with?**
Use the default model Jan downloads on first launch, or browse the Hub and pick one with a **Fits** pill. Jan's own **Jan-v3-4B** is a solid general-purpose choice; **Jan-Code-4B** is tuned for coding.

**Q: My machine is slow with a model. What can I do?**
Use a smaller or more quantized model, enable GPU acceleration, increase GPU Layers (if you have VRAM), or reduce Context Size. See [Model Settings & Tuning](#8-model-settings--tuning).

**Q: Can I use Claude or GPT-4 in Jan?**
Yes — add your Anthropic or OpenAI API key under **Settings → Model Providers**, then select the model. See [Connecting Cloud Providers](#7-connecting-cloud-providers).

**Q: How do I give the AI the ability to search the web or use tools?**
Add an MCP server such as Exa (web search) under **Settings → MCP Servers**, and use a tools-capable model. See [Connectors & Tools (MCP)](#12-connectors--tools-mcp).

**Q: Can other apps use Jan's models?**
Yes. Start the [Local API Server](#13-the-local-api-server) and point any OpenAI-compatible client at `http://127.0.0.1:1337/v1`.

**Q: Can I run a model from my terminal?**
Yes — use [`jan serve`](#14-the-jan-cli). You can also wire coding agents like Claude Code to a local model with `jan launch`.

**Q: How do I add images to a chat?**
Use a vision-capable model (e.g. **Jan-v2-VL**), then click **+ → Add Images**. The option is hidden for non-vision models.

**Q: Which file types can I upload to a Project?**
PDFs, Markdown, Office documents (DOCX, XLSX, PPTX), code files, and more. They're chunked and indexed for retrieval across the project.

**Q: How do I move my data to another drive?**
Use **Settings → General → Jan Data Folder** to relocate it. On Windows you can also edit `settings.json` directly (see Troubleshooting).

**Q: How do I completely reset Jan?**
**Settings → General → Reset To Factory Settings** — but note this deletes all models, chats, and settings.

**Q: What does the "Increase Context Size" banner mean?**
Your conversation grew longer than the model's context window. Click the banner or raise **Context Size** in model settings (uses more memory).

**Q: Is my data sent anywhere for the model "fit" calculation?**
No. Fit status is computed locally from your hardware and the model's metadata — nothing is downloaded.

---

## 21. Quick Reference

### Key Locations

| Item | Path |
|------|------|
| Data folder (Windows) | `%APPDATA%\Jan\data` |
| Data folder (macOS) | `~/Library/Application Support/Jan/data` |
| Data folder (Linux) | `~/.local/share/Jan/data` |
| Logs | `<data>/logs/app.log` |
| Local models | `<data>/llamacpp/models/<org>/<repo>/` and `<data>/mlx/models/` |
| Threads | `<data>/threads/<thread_id>/` |
| Settings (Windows) | `%APPDATA%\Jan\settings.json` |

### Default Ports

| Service | Port |
|---------|------|
| Local API Server | `1337` |
| CLI server (`jan serve`/`launch`) | `6767` |
| Docs dev server | `3001` |

### Essential CLI Commands

```bash
jan serve [MODEL_ID]            # serve a model at localhost:6767/v1
jan serve MODEL --detach        # serve in the background
jan launch claude --model M     # run Claude Code against a local model
jan models list                 # list installed models
jan threads list                # list saved conversations
```

### Local API Endpoint

```bash
curl http://127.0.0.1:1337/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_KEY" \
  -d '{"model":"YOUR_MODEL_ID","messages":[{"role":"user","content":"Hi"}]}'
```

### Where to Configure What

| I want to… | Go to… |
|------------|--------|
| Download a local model | **Hub** (left sidebar) |
| Add a cloud provider | **Settings → Model Providers** |
| Add my Hugging Face token | **Settings → General → Others → HuggingFace Token** |
| Tune a model | **Gear icon** next to the model |
| Pick a GPU backend | **Settings → Llama.cpp → Backend** |
| Add a tool/connector | **Settings → MCP Servers** |
| Start the API server | **Settings → Local API Server** |
| Create a persona | **Settings → Assistants** |
| Change where data is stored | **Settings → General → Jan Data Folder** |
| Set up a proxy | **Settings → HTTPS Proxy** |
| Reset everything | **Settings → General → Reset To Factory Settings** |

### Getting Help

- **Documentation:** [jan.ai/docs](https://jan.ai/docs)
- **Community:** [Discord](https://discord.gg/FTk2MvZwJH) (`#🆘|jan-help`)
- **Bug reports:** [GitHub Issues](https://github.com/janhq/jan/issues)
- **Changelog:** [jan.ai/changelog](https://jan.ai/changelog)

---

_Generated June 2026 from janhq/jan at 15e372f. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._