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
2. Quick Start
3. Installation
4. Your First Chat
5. Managing Models
6. Local vs. Cloud Models
7. Connecting Cloud Providers
8. Model Settings & Tuning
9. Assistants
10. Projects
11. Files, Images & Documents
12. Connectors & Tools (MCP)
13. The Local API Server
14. The Jan CLI
15. Coding Agents (Claude Code & OpenClaw)
16. Settings Reference
17. Your Data & Privacy
18. How Jan Works (Concepts)
19. Troubleshooting
20. Frequently Asked Questions
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 and run it. See 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:

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 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.
• Settings → Model Providers to connect a cloud account — see Connecting Cloud Providers.

3. Installation

Jan is available for Windows, macOS, and Linux. Download the version for your platform from jan.ai or the GitHub Releases page.

Download Links

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

sudo apt install ./jan.deb

AppImage (portable):

chmod +x jan.AppImage
./jan.AppImage

Flatpak:

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.

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

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.

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:

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). 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 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 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:

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

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

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:

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:

Output Constraints — force a specific output format:

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

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:

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

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. 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; 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 and 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:
   • 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 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:

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:

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."}]
  }'

{
  "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:

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

Server 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

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.

jan serve [MODEL_ID] [OPTIONS]

Examples:

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.

jan launch [PROGRAM] [OPTIONS]

Examples:

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

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:

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

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.

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

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:

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

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

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

Folder Layout

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

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

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

The file lives at logs/app.log inside your data folder. 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:

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

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:

# 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

For custom endpoints: a wrong API type (OpenAI vs. Anthropic) or a base URL missing /v1 (causing 404s) 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

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

Windows

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

Linux

# .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):

{ "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:

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:

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

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

Default Ports

Still Stuck?

Gather your error logs and system specs, then ask in the Jan Discord #🆘|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 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.

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.

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

Q: Can other apps use Jan's models? Yes. Start 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. 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

Default Ports

Essential CLI Commands

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

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

Getting Help

• Documentation: jan.ai/docs
• Community: Discord (#🆘|jan-help)
• Bug reports: GitHub Issues
• Changelog: jan.ai/changelog