# Endpoints
Source: https://docs.magnitude.dev/api/endpoints

OpenAI-compatible and Anthropic-compatible routes with examples.

All paths are relative to `http://127.0.0.1:10100`. From another device, use the server's network address and API key; see [Network access](/api/network-access).

| Method | Path | Purpose |
| - | - | - |
| `GET` | `/health` | Returns `200` when the service is ready. |
| `GET` | `/inference/v1/models` | List models available for inference. |
| `POST` | `/inference/v1/chat/completions` | OpenAI Chat Completions, JSON or streaming. |
| `POST` | `/inference/v1/responses` | OpenAI Responses, JSON or streaming. |
| `POST` | `/inference/anthropic/v1/messages` | Anthropic Messages. `max_tokens` is required. |
| `POST` | `/inference/anthropic/v1/messages/count_tokens` | Count input tokens for an Anthropic-format request. |

Supported inputs and features depend on the model. Your application keeps the conversation history and executes any tools the model requests.

## Chat completion

Replace `MODEL_ID` with an ID from the models endpoint:

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl http://127.0.0.1:10100/inference/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "MODEL_ID",
    "messages": [{"role": "user", "content": "Explain prompt caching in one paragraph."}],
    "max_tokens": 256
  }'
```

The generated text is in `choices[0].message.content`.

## Streaming

Add `"stream": true` to the request body. Responses arrive as server-sent events. With curl, add `-N` to print events as they arrive.

## Anthropic Messages

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl http://127.0.0.1:10100/inference/anthropic/v1/messages \
  -H 'Content-Type: application/json' \
  -H 'anthropic-version: 2023-06-01' \
  -d '{
    "model": "MODEL_ID",
    "max_tokens": 256,
    "messages": [{"role": "user", "content": "Explain prompt caching in one paragraph."}]
  }'
```

The generated text is in `content[0].text`.

These examples use macOS and Linux quoting. On Windows, use `curl.exe` with quoting appropriate for your shell, or send the same JSON from your application.


# Network access
Source: https://docs.magnitude.dev/api/network-access

Connect to Magnitude over your network or an SSH tunnel.

By default the API is available only on the computer running Magnitude. Network access makes it available to other devices for inference, and lets you open the Magnitude app in a browser on another device.

For a complete server setup, see [Remote server](/remote-server).

## Enable network access

### Desktop Settings

1. Open **Settings → Network access** and turn it on.
2. Choose an **Address**. **All interfaces** serves every network this computer is on. Choosing one address serves only that network.
3. Copy the **API key**. Other devices send it with every request.
4. Copy the **Reachable at** URL.
5. Restart Magnitude when the **Restart required** notice appears.

The first time the service listens on a network, macOS or Windows may ask whether to allow incoming connections. Allow them.

### Configuration file

Without Desktop, add a `network` object to `~/.magnitude/config.json` (`%USERPROFILE%\.magnitude\config.json` on Windows) with a long, randomly generated key, then restart Magnitude:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "network": {
    "enabled": true,
    "apiKey": "YOUR_LONG_RANDOM_KEY"
  }
}
```

A server set up with `magnitude server setup` turns this on itself; see [Remote server](/remote-server). All fields are documented in [Configuration file](/reference/configuration-file).

## Choose an address

| Connection | Address |
| - | - |
| Same local network | The server's Wi-Fi or Ethernet IP, such as `192.168.1.20`. It can change when the server joins another network. |
| Private network, such as Tailscale | The server's address on that network, such as `100.x.y.z`. Both computers must be connected to it. |

Select that address in Settings or use it as `network.bind`. Use `http://ADDRESS:10100/inference/v1` as the base URL. A private network can make the server reachable when you are away from home.

## Open the app from another device

With network access on, open `http://ADDRESS:10100` in a browser on the other device, using the same address as the base URL. Sign in with the **API key**. The app works as it does on the server: download and load models, watch usage, and change Settings. In a browser, **Connections** doesn't change any computer's agents itself: each agent has **Copy setup prompt**, which you paste into that agent, or any coding agent, on the computer you're using.

* A browser stays signed in until it goes 30 days unused. **Settings → This browser → Sign out** ends it sooner.
* Browsers stay signed in when Magnitude restarts or updates. Changes to network settings apply when Magnitude restarts, so a regenerated key takes effect then and signs every browser out.
* Turning network access off, regenerating the key, changing the address, or restarting from that browser asks first, because it disconnects the browser.
* After five wrong keys, each further attempt waits longer, up to one minute.

The connection is plain HTTP. Use it on a network you trust or a private network such as Tailscale, or put an HTTPS reverse proxy in front of Magnitude and add its name to [`network.allowedHosts`](#custom-hostnames).

## SSH tunnel

Keep Magnitude running on the server. On your own computer, run:

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
ssh -N -L 10101:127.0.0.1:10100 user@server
```

Use `http://127.0.0.1:10101/inference/v1` in your client. SSH forwards that local port to Magnitude on the server. Network access can stay off, and no Magnitude API key is required through the tunnel. If your client requires a key, any value works. Through the tunnel, `http://127.0.0.1:10101` also opens the app without signing in, because Magnitude sees the connection as coming from the server itself.

Keep the tunnel running while using inference. You must be able to reach the server over SSH, for example through your local network or Tailscale.

## Containers

From a container on this computer, use `http://host.docker.internal:10100/inference/v1` with the API key. Network access must be on, because the container connects from its own address.

## Windows with WSL

See [Windows and WSL](/api/windows-wsl) for mirrored and NAT networking.

## Configure the app or agent

Use the server URL as the base URL and its API key as the key. For an app that is not a supported agent, the settings are the same as in [Other agents](/integrations/other-agents) with the network address in place of `127.0.0.1`.

**Connections** cannot configure a supported agent on another device, so write its configuration yourself. Each agent page shows the exact block under **Configuration**. Replace `ADDRESS` with the server address, `API_KEY` with the API key, and `MODEL_ID` with the model's exact ID; take the context window and output limit from the model's **Details**.

* [Pi](/integrations/pi#configuration)
* [OpenCode](/integrations/opencode#configuration)
* [Hermes](/integrations/hermes#configuration)
* [OpenClaw](/integrations/openclaw#configuration)
* [Codex](/integrations/codex#configuration)
* [Claude Code](/integrations/claude-code#configuration)
* [Oh My Pi](/integrations/oh-my-pi#configuration)
* [Cline](/integrations/cline#configuration)

Codex and Claude Code route hosted models through Magnitude's gateway. From another device, only local models are available to them.

## Check the connection

From the other device:

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -H "Authorization: Bearer API_KEY" http://ADDRESS:10100/inference/v1/models
```

On Windows PowerShell, use `curl.exe` instead of `curl`. A model list means the connection works.

## Custom hostnames

Magnitude accepts requests addressed to its IP addresses, `localhost`, `host.docker.internal`, and Tailscale MagicDNS names ending in `.ts.net`. To reach it by another name, such as a reverse proxy or a LAN hostname, list the name under `network.allowedHosts` in the [configuration file](/reference/configuration-file).

## Troubleshooting

| Response | Meaning |
| - | - |
| Connection refused | Network access is off, Magnitude is not running, or the chosen address does not include the network you are on. |
| Connection timed out | Check that the server is reachable and its firewall allows TCP port `10100`. |
| `401` | The request did not include the API key, or the key changed. Check the key in Settings or the server configuration. |
| Sign in says no key is set | Network access has no API key. On the server, choose **Regenerate** in Settings, or set `network.apiKey`, then restart Magnitude. |
| Asked to sign in again | The key was regenerated, or this browser went 30 days unused. |
| `421 Invalid Host header` | The request used a hostname Magnitude does not accept. Use an IP address or add the name to `network.allowedHosts`. |


# Overview
Source: https://docs.magnitude.dev/api/overview

Base URLs, keys, and model IDs for the local inference API.

Magnitude serves an HTTP API on port `10100` while Desktop or `magnitude serve` is running. **Connections** uses it to configure supported agents. Any other OpenAI-compatible or Anthropic-compatible client can use it directly.

To run models on another machine, see [Remote server](/remote-server).

## Base URLs

| Client type | Base URL |
| - | - |
| OpenAI-compatible | `http://127.0.0.1:10100/inference/v1` |
| Anthropic-compatible | `http://127.0.0.1:10100/inference/anthropic` |

Clients append their own paths, such as `/chat/completions` or `/v1/messages`. If a client asks for a full endpoint URL instead, use the paths in [Endpoints](/api/endpoints).

From another device, replace `127.0.0.1` with the server's network address. See [Network access](/api/network-access).

## API keys

| Caller | Key |
| - | - |
| This computer | None required. If the client insists on a value, any value works. |
| Other devices | The server’s configured API key, sent as `Authorization: Bearer KEY` or `x-api-key: KEY`. |

## Model IDs

List the models available for inference:

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl http://127.0.0.1:10100/inference/v1/models
```

Use the exact `id` from the response as the model name in requests. Display names are not accepted. Magnitude loads the model on the first request, which takes longer than later requests.

## Scope

The API provides inference only: listing models and generating text. Downloading models, managing them, and the Magnitude app itself are not available over the API.

Opening `http://127.0.0.1:10100` in a browser shows a short text summary of these paths.


# Windows and WSL
Source: https://docs.magnitude.dev/api/windows-wsl

Use Magnitude on Windows from agents inside WSL.

Magnitude runs on Windows. Agents installed inside a WSL distribution run in a separate Linux environment with its own network, so `127.0.0.1` inside WSL is the distribution, not Windows. **Connections** cannot detect or configure agents inside WSL; configure them by hand as shown under **Configuration** on the agent's page; see [Network access](/api/network-access#configure-the-app-or-agent).

## Mirrored networking

On Windows 11 22H2 and later, WSL can mirror the Windows network. With mirrored networking, `http://127.0.0.1:10100` works inside WSL exactly as on Windows, and Magnitude's network access setting is not needed.

Enable it in **WSL Settings → Networking → Networking mode → Mirrored**, or add to `%USERPROFILE%\.wslconfig`:

```ini theme={"theme":{"light":"github-light","dark":"github-dark"}}
[wsl2]
networkingMode=mirrored
```

Then run `wsl --shutdown` in PowerShell and start the distribution again.

Inside WSL, use `http://127.0.0.1:10100/inference/v1` as the base URL. No API key is needed.

## NAT networking

In the default NAT mode, WSL reaches Windows through the host address.

1. In Magnitude, open **Settings → Network access**, turn it on, and copy the API key. Keep **All interfaces** selected. Restart Magnitude.

2. Inside WSL, find the Windows host address:

   ```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
   ip route show default | awk '{print $3}'
   ```

3. Use `http://HOST_ADDRESS:10100/inference/v1` as the base URL and the API key as the key.

If the connection is refused, allow inbound connections through the Hyper-V firewall from an administrator PowerShell:

```powershell theme={"theme":{"light":"github-light","dark":"github-dark"}}
New-NetFirewallHyperVRule -Name "Magnitude" -DisplayName "Magnitude" -Direction Inbound -VMCreatorId '{40E0AC32-46A5-438A-A0B2-2B479E8F2E90}' -Protocol TCP -LocalPorts 10100
```

The host address can change when WSL restarts. Mirrored networking avoids this.

## The CLI inside WSL

WSL can run Windows programs, so `magnitude.exe` works from a WSL shell. It controls the Windows installation and edits Windows configuration files, not files inside the distribution.


# FAQ
Source: https://docs.magnitude.dev/faq

Common questions about running Magnitude.

## What is Magnitude?

An open source inference engine that optimizes each model for your exact hardware. It ships as a desktop app that runs open models and connects them to the agent you already use.

## How is it faster than llama.cpp, Ollama, or LM Studio?

They ship one-size-fits-all kernels, because tuning each model for each chip by hand would take forever. Magnitude tunes them automatically. When you download a model, it spends up to a minute on your actual chip trying different ways to split up the math (how many GPU threads team up, how big a chunk each one takes, how far ahead to load data) and keeps the fastest combination that doesn't change the model's output. [See the benchmarks against Ollama.](https://magnitude.dev/#benchmark)

## What hardware do I need?

Any Apple Silicon, NVIDIA, or AMD GPU, or nothing but a CPU. There is no fixed minimum. Smaller machines run smaller models, and more memory lets you run larger ones.

## What operating systems does it support?

macOS, Linux, and Windows.

## Which models does it support?

See the full list at [magnitude.dev/models](https://magnitude.dev/models). We write optimized kernels for the most popular open-weight families, which is how we beat generalist engines.

## Which agents work with it?

One click connects Pi, OpenCode, Hermes, OpenClaw, Codex, Claude Code, Oh My Pi, and Cline. Anything else works through the OpenAI-compatible API.

## Is it private?

Yes. Prompts, files, and models stay on your machine. No internet needed once a model is downloaded.

## Can I use Magnitude from another computer, a container, or WSL?

Yes. Enable **Network access** for direct connections and use the server address and API key. SSH tunnels and mirrored WSL networking can use the local endpoint without enabling it. Only inference is available from other devices. See [Network access](/api/network-access) and [Windows and WSL](/api/windows-wsl).

## Can I keep models on another drive?

Yes. Change **Model storage** in Settings, then move the existing models with the command it shows. See [Settings](/settings#model-storage).

## Why is the first response slow and later ones fast?

Models load on demand and unload when idle, so the first request after a pause includes loading. Later turns reuse cached context, and supported models use speculative decoding. Click **Load model** in **My Models** to load ahead of time.


# Quick start
Source: https://docs.magnitude.dev/get-started

Download a model and use it with your agent.

## 1. Install Magnitude

[Download Magnitude](https://magnitude.dev/download), install it, and open the app.

Need help installing? See the guide for [macOS](/installation/macos), [Windows](/installation/windows), or [Linux](/installation/linux).

## 2. Download a model

Open **Discover**, select a recommendation, and click **Download**. Start with **Balanced**, or adjust the slider toward speed or intelligence.

## 3. Connect your agent

Open **Connections**, find your installed agent, and click **Connect**. Open or restart the agent, select a Magnitude model, and start working.

See your agent’s [integration guide](/integrations/overview) for details. Keep Magnitude running; it loads the model when needed.

Using a dedicated machine for inference? See [Remote server](/remote-server).


# Hardware
Source: https://docs.magnitude.dev/hardware

Understand what your machine can run and what affects performance.

Magnitude assesses your machine and recommends models that fit. Start with those recommendations rather than choosing a model by parameter count alone.

## Supported configurations

| Machine | Inference support |
| - | - |
| Apple Silicon Mac | Metal GPU acceleration |
| Intel Mac | CPU |
| Windows x64 | CPU, supported NVIDIA CUDA GPUs, or supported Vulkan GPUs |
| Linux x64 or ARM64 | CPU, supported NVIDIA CUDA GPUs, or supported Vulkan GPUs |

See [macOS](/installation/macos), [Windows](/installation/windows), and [Linux](/installation/linux) for OS requirements and installers.

## Apple Silicon

Apple Silicon shares memory between the CPU and GPU. That gives the GPU access to a larger memory pool than a typical laptop's dedicated graphics memory, but macOS and other apps use the same pool.

For example, a Mac with 32 GB of unified memory does not have all 32 GB available for a model. Use Discover's fit assessment and close memory-heavy apps if loading fails.

Metal support is supplied by macOS; you do not need a separate GPU toolkit.

## NVIDIA GPUs

On Linux and Windows, Magnitude can use its CUDA backend with a compatible NVIDIA GPU and driver. The current CUDA builds target Ampere-class and newer GPUs; older CUDA-capable cards are not automatically supported.

Install your GPU's supported NVIDIA driver. You can check that the driver sees it with:

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
nvidia-smi
```

Magnitude acquires compatible runtime components; you do not need the CUDA development toolkit. If acceleration is unavailable, check the hardware and compatibility information in the app before downloading a large model.

## AMD and other Vulkan GPUs

Linux and Windows GPU support uses Vulkan for compatible devices. Magnitude does **not** currently ship a ROCm backend.

Use your operating system's supported graphics driver and Vulkan runtime. The backend requires Vulkan 1.1 or later, but the version alone does not guarantee that a particular GPU supports every model. Check the model's compatibility in Catalog.

## CPU-only machines

Magnitude can run models without a supported GPU, including on Intel Macs and Windows machines without a compatible GPU. Smaller models and lower-bit quantizations are usually more practical when response speed matters.

CPU inference uses system RAM. Having enough memory to fit a large model does not mean it will generate quickly; use the speed estimates when choosing.

## Memory and speed trade-offs

* **More memory** lets you consider larger models, higher-fidelity quantizations, or larger contexts.
* **GPU memory** matters on dedicated-GPU systems. A machine with 64 GB of system RAM and an 8 GB GPU does not have 72 GB of interchangeable GPU memory.
* **Longer context** increases memory demand and can slow responses.
* **Other applications** reduce available memory and can affect speed after assessment.

For a faster starting point, move Discover's slider toward **Faster**. For a model that needs less memory, compare the Memory values and quantized variants. See [Models](/models).


# Linux
Source: https://docs.magnitude.dev/installation/linux

Choose and install the Linux package for your distribution.

## Choose your package

Visit [Download Magnitude](https://magnitude.dev/download) and choose:

| Distribution family | Package |
| - | - |
| Ubuntu / Debian | `.deb` |
| Fedora / Red Hat | `.rpm` |
| Arch Linux / Omarchy and other Arch-based distributions | `.pkg.tar.zst` |

Choose **Intel / AMD (x64)** for an x86-64 processor or **ARM64** for an ARM64 processor. The Arch package is available for x64 only. If you need to check, run `uname -m`: `x86_64` means x64; `aarch64` means ARM64.

## Requirements

Magnitude requires **glibc 2.34 or later**. Ubuntu 22.04, Debian 12 and RHEL 9 (and its rebuilds) meet the glibc requirement. The desktop window needs a graphical session; `magnitude serve` can run without one, including over SSH.

Your package manager installs required desktop libraries. GPU inference also needs a supported driver; see [Hardware](/hardware). Alpine/musl packages are not available.

## Install

The quickest way is the install command. It picks the right package, verifies it, and asks whether to run Magnitude as a [server](/remote-server):

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -fsSL https://magnitude.dev/install.sh | sh
```

Or open the downloaded package in your distribution's software installer, or use the terminal. Replace the filename below with the file you downloaded.

<Tabs>
  <Tab title="Ubuntu / Debian">
    ```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
    sudo apt update
    sudo apt install ./magnitude-desktop.deb
    ```
  </Tab>

  <Tab title="Fedora">
    ```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
    sudo dnf install ./magnitude-desktop.rpm
    ```
  </Tab>

  <Tab title="Arch / Omarchy">
    ```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
    sudo pacman -U ./magnitude-desktop.pkg.tar.zst
    ```
  </Tab>
</Tabs>

Open **Magnitude** from your applications menu and follow [Quick start](/get-started).

## Updates and removal

App updates use your system package manager. Click **Restart** to install a downloaded update; at your desktop it installs without a password, while over SSH it asks for administrator authentication. Use **Settings → Application updates** for the available actions. A [server](/remote-server) installs its updates by itself.

Remove Magnitude through your distribution's software manager. Downloaded models and settings live in `~/.magnitude` and are separate from the installed application package. On a server, run `magnitude server remove` before removing the package; reinstalling the package without it keeps the server set up.


# macOS
Source: https://docs.magnitude.dev/installation/macos

Install Magnitude on an Apple Silicon or Intel Mac.

## Requirements

* macOS 13 Ventura or later.
* An Apple Silicon or Intel Mac.
* Free disk space for the app and the models you download.

Apple Silicon uses Metal GPU acceleration. Intel Macs use CPU inference. See [Hardware](/hardware) for memory and performance guidance.

## Download and install

1. Visit [Download Magnitude](https://magnitude.dev/download).
2. Choose the download for your Mac. If you're unsure, open **Apple menu → About This Mac**: a chip named Apple M1, M2, or another M-series chip is Apple Silicon; an Intel processor uses the Intel download.
3. Open the `.dmg` and drag **Magnitude** into **Applications**.
4. Open Magnitude from Applications, then follow [Quick start](/get-started).

Or install from Terminal; it verifies the app and puts it in Applications:

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -fsSL https://magnitude.dev/install.sh | sh
```

To run Magnitude as a service on a Mac that serves other computers, see [Remote server](/remote-server).

## Updates and removal

Check **Settings → Application updates** to download and install updates. Restarting to update stops the running model and service.

To remove the app, quit Magnitude and move it from Applications to Trash. Your downloaded models and settings live separately under `~/.magnitude`; removing the app does not mean that data has been deleted. Keep that folder if you intend to reinstall.


# Windows
Source: https://docs.magnitude.dev/installation/windows

Install Magnitude on Windows.

## Requirements

* Windows 10 version 1809 or later, or Windows 11.
* An x64 system for the native Windows build.
* Free disk space for the app and downloaded models.

The current Windows build supports CPU inference and compatible NVIDIA CUDA or Vulkan GPUs on Windows. See [Hardware](/hardware).

## Download and install

1. Download the Windows installer from [Download Magnitude](https://magnitude.dev/download).
2. Run the `.exe` and complete installation.
3. Open Magnitude and follow [Quick start](/get-started).

Or install from PowerShell; it verifies the installer and installs for your user account:

```powershell theme={"theme":{"light":"github-light","dark":"github-dark"}}
irm https://magnitude.dev/install.ps1 | iex
```

The installer installs for your user account under `%LOCALAPPDATA%\Programs\Magnitude`.

## Updates and removal

Use **Settings → Application updates** to check for updates. **Restart to update** stops local inference while the application is replaced.

Uninstall Magnitude through Windows **Settings → Apps**. Downloaded models and settings are stored separately in `%USERPROFILE%\.magnitude`; keep them if you intend to reinstall.

Agents installed inside WSL need a small amount of configuration; see [Windows and WSL](/api/windows-wsl).


# Claude Code
Source: https://docs.magnitude.dev/integrations/claude-code

Connect Claude Code to your downloaded Magnitude models.

## Connect

1. [Install Claude Code](https://code.claude.com/docs/en/overview) if needed.
2. Download a compatible model in Magnitude.
3. Open **Connections → Claude Code** and click **Connect**.
4. Select a downloaded model on the connected card, then click the command to copy it.
5. Paste it into your terminal from your project folder. On Windows, use PowerShell.

Magnitude configures Claude Code’s gateway. Local model IDs use the `anthropic-local/` prefix. Keep Magnitude running while connected, including for hosted models: hosted requests still go to their provider through the gateway. Disconnect and restart Claude Code before using it independently again.

If Claude Code isn’t signed in, **Connect** also adds a placeholder credential, and Magnitude serves every request from it with your loaded model, including the Claude models that built-in subagents ask for. If you sign in to Claude Code later, connect again so your own login is used for Claude models.

## Run Claude Code

After connecting in Magnitude, start Claude Code with:

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
claude --model anthropic-local/MODEL_ID
```

Replace `MODEL_ID` with the exact model ID, such as `gemma-4-e2b-it-qat:gguf:q4`, rather than its display name. The command shown in **Connections** already includes the correct ID for your selected model, so you can copy it without editing. Keep Magnitude running; it loads the model when the agent requests it.

## Configuration

**Connect** writes `~/.claude/settings.json`. Location overrides: `CLAUDE_CONFIG_DIR`.

### On another computer

1. In Magnitude, turn on **Settings → Network access**.
2. On the other computer, open `http://ADDRESS:10100` in a browser, using the address from **Reachable at**, and sign in with the **API key**.
3. In **Connections**, click **Copy setup prompt** on Claude Code and send it to your agent.

### Edit the files yourself

Use the address from **Reachable at** for `ADDRESS` and the **API key** for `API_KEY`.

`~/.claude/settings.json`:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "env": {
    "ANTHROPIC_BASE_URL": "http://ADDRESS:10100/inference/anthropic/proxies/claude-code",
    "ANTHROPIC_AUTH_TOKEN": "API_KEY",
    "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1"
  },
  "model": "anthropic-local/MODEL_ID"
}
```

Only local models are available from another device.


# Cline
Source: https://docs.magnitude.dev/integrations/cline

Connect Cline to your downloaded Magnitude models.

## Connect

1. [Install Cline](https://docs.cline.bot/getting-started/installing-cline) if needed.
2. Download a compatible model in Magnitude.
3. Open **Connections → Cline** and click **Connect**.
4. Select a downloaded model on the connected card, then click the command to copy it.
5. Paste it into your terminal from your project folder. On Windows, use PowerShell.

This connector detects the `cline` executable and manages its provider configuration. Having only an editor extension installed does not necessarily make this CLI integration available. Magnitude configures the OpenAI-compatible provider.

## Run Cline

After connecting in Magnitude, start Cline with:

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
cline --tui --provider openai-compatible --model MODEL_ID
```

Replace `MODEL_ID` with the exact model ID, such as `gemma-4-e2b-it-qat:gguf:q4`, rather than its display name. The command shown in **Connections** already includes the correct ID for your selected model, so you can copy it without editing. Keep Magnitude running; it loads the model when the agent requests it.

## Configuration

**Connect** writes `~/.cline/data/settings/providers.json` and `~/.cline/data/settings/models.json`. Location overrides: `CLINE_DATA_DIR` and `CLINE_PROVIDER_SETTINGS_PATH`.

### On another computer

1. In Magnitude, turn on **Settings → Network access**.
2. On the other computer, open `http://ADDRESS:10100` in a browser, using the address from **Reachable at**, and sign in with the **API key**.
3. In **Connections**, click **Copy setup prompt** on Cline and send it to your agent.

### Edit the files yourself

Use the address from **Reachable at** for `ADDRESS` and the **API key** for `API_KEY`.

`~/.cline/data/settings/providers.json`:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "providers": {
    "openai-compatible": {
      "settings": {
        "provider": "openai-compatible",
        "client": "openai-compatible",
        "protocol": "openai-chat",
        "baseUrl": "http://ADDRESS:10100/inference/v1",
        "apiKey": "API_KEY",
        "model": "MODEL_ID"
      },
      "updatedAt": "2026-01-01T00:00:00.000Z",
      "tokenSource": "manual"
    }
  },
  "lastUsedProvider": "openai-compatible"
}
```

Set `updatedAt` to the current time. Cline replaces a provider entry that has no `updatedAt` with its own stored settings the next time it starts.


# Codex
Source: https://docs.magnitude.dev/integrations/codex

Connect Codex to your downloaded Magnitude models.

## Connect

1. [Install Codex](https://developers.openai.com/codex/cli) if needed.
2. Download a compatible model in Magnitude.
3. Open **Connections → Codex** and click **Connect**.
4. Select a downloaded model on the connected card, then click the command to copy it.
5. Paste it into your terminal from your project folder. On Windows, use PowerShell.

Magnitude configures Codex’s local gateway and model catalog. Local model IDs use the `magnitude-local/` prefix inside Codex. Keep Magnitude running while connected, including when you select a hosted model: hosted requests pass through the gateway to their provider. Disconnect in Magnitude and restart Codex before using it independently again.

## Run Codex

After connecting in Magnitude, start Codex with:

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
codex -c model_provider=magnitude --model magnitude-local/MODEL_ID
```

Replace `MODEL_ID` with the exact model ID, such as `gemma-4-e2b-it-qat:gguf:q4`, rather than its display name. The command shown in **Connections** already includes the correct ID for your selected model, so you can copy it without editing. Keep Magnitude running; it loads the model when the agent requests it.

## Configuration

**Connect** writes `~/.codex/config.toml`, `~/.codex/magnitude.config.toml`, and `~/.codex/magnitude.models.json`. Location overrides: `CODEX_HOME`.

### On another computer

1. In Magnitude, turn on **Settings → Network access**.
2. On the other computer, open `http://ADDRESS:10100` in a browser, using the address from **Reachable at**, and sign in with the **API key**.
3. In **Connections**, click **Copy setup prompt** on Codex and send it to your agent.

### Edit the files yourself

Use the address from **Reachable at** for `ADDRESS` and the **API key** for `API_KEY`.

`~/.codex/config.toml`:

```toml theme={"theme":{"light":"github-light","dark":"github-dark"}}
model_provider = "magnitude"
model = "magnitude-local/MODEL_ID"

[model_providers.magnitude]
name = "Magnitude"
base_url = "http://ADDRESS:10100/inference/v1/proxies/codex"
wire_api = "responses"
env_key = "MAGNITUDE_API_KEY"
```

Export `MAGNITUDE_API_KEY` with the API key before starting Codex. Codex warns that model metadata is not found and continues. Only local models are available from another device.


# Hermes
Source: https://docs.magnitude.dev/integrations/hermes

Connect Hermes to your downloaded Magnitude models.

## Connect

1. [Install Hermes](https://hermes-agent.nousresearch.com/docs/getting-started/installation/) if needed.
2. Download a compatible model in Magnitude.
3. Open **Connections → Hermes** and click **Connect**.
4. Select a downloaded model on the connected card, then click the command to copy it.
5. Paste it into your terminal from your project folder. On Windows, use PowerShell.

Magnitude adds a custom provider named `magnitude`. The command below starts Hermes with a model from that provider.

## Run Hermes

After connecting in Magnitude, start Hermes with:

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
hermes --provider custom:magnitude --model MODEL_ID
```

Replace `MODEL_ID` with the exact model ID, such as `gemma-4-e2b-it-qat:gguf:q4`, rather than its display name. The command shown in **Connections** already includes the correct ID for your selected model, so you can copy it without editing. Keep Magnitude running; it loads the model when the agent requests it.

## Configuration

**Connect** writes `~/.hermes/config.yaml`. Location overrides: `HERMES_HOME`.

### On another computer

1. In Magnitude, turn on **Settings → Network access**.
2. On the other computer, open `http://ADDRESS:10100` in a browser, using the address from **Reachable at**, and sign in with the **API key**.
3. In **Connections**, click **Copy setup prompt** on Hermes and send it to your agent.

### Edit the files yourself

Use the address from **Reachable at** for `ADDRESS` and the **API key** for `API_KEY`.

`~/.hermes/config.yaml`:

```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}}
providers:
  magnitude:
    name: Magnitude
    base_url: http://ADDRESS:10100/inference/v1
    api_key: API_KEY
    transport: chat_completions
model:
  provider: custom:magnitude
  default: MODEL_ID
```


# Oh My Pi
Source: https://docs.magnitude.dev/integrations/oh-my-pi

Connect Oh My Pi to your downloaded Magnitude models.

## Connect

1. [Install Oh My Pi](https://github.com/can1357/oh-my-pi#installation) if needed.
2. Download a compatible model in Magnitude.
3. Open **Connections → Oh My Pi** and click **Connect**.
4. Select a downloaded model on the connected card, then click the command to copy it.
5. Paste it into your terminal from your project folder. On Windows, use PowerShell.

Restart Oh My Pi and choose a Magnitude model. If you use named profiles, connect the profile you actually run: check the paths shown in Connections rather than editing a different profile.

## Run Oh My Pi

After connecting in Magnitude, start Oh My Pi with:

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
omp --model magnitude/MODEL_ID
```

Replace `MODEL_ID` with the exact model ID, such as `gemma-4-e2b-it-qat:gguf:q4`, rather than its display name. The command shown in **Connections** already includes the correct ID for your selected model, so you can copy it without editing. Keep Magnitude running; it loads the model when the agent requests it.

## Configuration

**Connect** writes `~/.omp/agent/models.yml` and `~/.omp/agent/config.yml`. Location overrides: `OMP_PROFILE`, `PI_PROFILE`, `PI_CONFIG_DIR`, and `PI_CODING_AGENT_DIR`.

### On another computer

1. In Magnitude, turn on **Settings → Network access**.
2. On the other computer, open `http://ADDRESS:10100` in a browser, using the address from **Reachable at**, and sign in with the **API key**.
3. In **Connections**, click **Copy setup prompt** on Oh My Pi and send it to your agent.

### Edit the files yourself

Use the address from **Reachable at** for `ADDRESS` and the **API key** for `API_KEY`.

`~/.omp/agent/models.yml`:

```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}}
providers:
  magnitude:
    baseUrl: http://ADDRESS:10100/inference/v1
    apiKey: API_KEY
    api: openai-completions
    models:
      - id: MODEL_ID
        name: MODEL_ID
        reasoning: false
        input: [text]
        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }
        contextWindow: 32768
        maxTokens: 8192
```


# OpenClaw
Source: https://docs.magnitude.dev/integrations/openclaw

Connect OpenClaw to your downloaded Magnitude models.

## Connect

1. [Install OpenClaw](https://docs.openclaw.ai/install) if needed.
2. Download a compatible model in Magnitude.
3. Open **Connections → OpenClaw** and click **Connect**.
4. Select a downloaded model on the connected card, then click the command to copy it.
5. Paste it into your terminal from your project folder. On Windows, use PowerShell.

Restart your running OpenClaw instance after changing its connection, then select a Magnitude model. The configuration is persistent; connecting does not start OpenClaw for you.

## Run OpenClaw

After connecting in Magnitude, start OpenClaw with:

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
openclaw tui
```

Then select your model inside the OpenClaw TUI:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
/model magnitude/MODEL_ID
```

Connections shows both commands for your selected model. Run the `/model` command inside OpenClaw, not in your shell.

Replace `MODEL_ID` with the exact model ID, such as `gemma-4-e2b-it-qat:gguf:q4`, rather than its display name. The command shown in **Connections** already includes the correct ID for your selected model, so you can copy it without editing. Keep Magnitude running; it loads the model when the agent requests it.

## Configuration

**Connect** writes `~/.openclaw/openclaw.json`. Location overrides: `OPENCLAW_CONFIG_PATH` and `OPENCLAW_STATE_DIR`.

### On another computer

1. In Magnitude, turn on **Settings → Network access**.
2. On the other computer, open `http://ADDRESS:10100` in a browser, using the address from **Reachable at**, and sign in with the **API key**.
3. In **Connections**, click **Copy setup prompt** on OpenClaw and send it to your agent.

### Edit the files yourself

Use the address from **Reachable at** for `ADDRESS` and the **API key** for `API_KEY`.

`~/.openclaw/openclaw.json`:

```json5 theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  models: {
    providers: {
      magnitude: {
        baseUrl: "http://ADDRESS:10100/inference/v1",
        apiKey: "API_KEY",
        api: "openai-completions",
        models: [
          {
            id: "MODEL_ID",
            name: "MODEL_ID",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 32768,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}
```


# OpenCode
Source: https://docs.magnitude.dev/integrations/opencode

Connect OpenCode to your downloaded Magnitude models.

## Connect

1. [Install OpenCode](https://opencode.ai/docs/#install) if needed.
2. Download a compatible model in Magnitude.
3. Open **Connections → OpenCode** and click **Connect**.
4. Select a downloaded model on the connected card, then click the command to copy it.
5. Paste it into your terminal from your project folder. On Windows, use PowerShell.

Choose a Magnitude model in OpenCode’s model selector. If you use JSONC or an explicit OpenCode config, check the configuration paths shown in Connections: OpenCode can merge more than one file.

## Run OpenCode

After connecting in Magnitude, start OpenCode with:

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
opencode --model magnitude/MODEL_ID
```

Replace `MODEL_ID` with the exact model ID, such as `gemma-4-e2b-it-qat:gguf:q4`, rather than its display name. The command shown in **Connections** already includes the correct ID for your selected model, so you can copy it without editing. Keep Magnitude running; it loads the model when the agent requests it.

## Configuration

**Connect** writes `~/.config/opencode/opencode.json`. Location overrides: `OPENCODE_CONFIG` and `XDG_CONFIG_HOME`.

### On another computer

1. In Magnitude, turn on **Settings → Network access**.
2. On the other computer, open `http://ADDRESS:10100` in a browser, using the address from **Reachable at**, and sign in with the **API key**.
3. In **Connections**, click **Copy setup prompt** on OpenCode and send it to your agent.

### Edit the files yourself

Use the address from **Reachable at** for `ADDRESS` and the **API key** for `API_KEY`.

`~/.config/opencode/opencode.json`:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "provider": {
    "magnitude": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Magnitude",
      "options": { "baseURL": "http://ADDRESS:10100/inference/v1", "apiKey": "API_KEY" },
      "models": {
        "MODEL_ID": { "name": "MODEL_ID", "limit": { "context": 32768, "output": 8192 } }
      }
    }
  }
}
```


# Other agents
Source: https://docs.magnitude.dev/integrations/other-agents

Use Magnitude from any OpenAI-compatible or Anthropic-compatible app or agent.

Magnitude runs an OpenAI-compatible API on this computer. **Connect** points supported agents at it, and any other app or agent that lets you set a custom base URL can use it too. The bottom of **Connections** shows the base URL and an example request. For an app or agent on another device, in a container, or inside WSL, see [Network access](/api/network-access). When you open the app in a browser on another device, this card shows the server's address and an example request that sends the API key.

## OpenAI-compatible apps

| Setting | Value |
| - | - |
| Provider | OpenAI-compatible |
| Base URL | `http://127.0.0.1:10100/inference/v1` |
| API key | Any value. Magnitude does not check it on this computer. |
| Model | An exact ID from `/inference/v1/models` |

If the app asks for a full endpoint URL instead of a base URL, use `http://127.0.0.1:10100/inference/v1/chat/completions`.

## Anthropic-compatible apps

Use `http://127.0.0.1:10100/inference/anthropic` as the base URL. Requests must include `max_tokens`.

## Check the connection

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl http://127.0.0.1:10100/inference/v1/models
```

A model list means Magnitude is running and the API is available. See [Endpoints](/api/endpoints) for the full route list.


# Overview
Source: https://docs.magnitude.dev/integrations/overview

Use Magnitude models with your agent.

Download a model in Magnitude, then open **Connections** to configure your agent. Magnitude supports Pi, OpenCode, Hermes, OpenClaw, Codex, Claude Code, Oh My Pi, and Cline.

For apps and agents that are not listed, see [Other agents](/integrations/other-agents). For an agent inside WSL, in a container, or on another computer, see [Network access](/api/network-access).

## Connect an agent

1. Install the agent using its official instructions.
2. Find it in **Connections** and click **Connect**.
3. Select a downloaded model on the connected card.
4. Click the displayed command to copy it, then paste it into your terminal from your project folder. On Windows, use PowerShell.

Connecting configures the agent; it does not launch it. The copied command starts the agent with your selected model. OpenClaw uses a separate `/model` command inside its TUI; its card shows both commands. Keep Magnitude running while you use its local models.

## Connection states

| State | What to do |
| - | - |
| Not installed | Follow the installation link, install the agent, and return to Connections. |
| Not connected | Click Connect. |
| Connected | Select a model, copy the command, and run it in your terminal. |
| Connection needs repair | Click Repair connection, then reload the agent. |
| Could not verify connection | Check the reported problem, such as an inaccessible configuration file, before trying again. |

Connected means the configuration is present and valid. It does not mean a model is currently loaded or that an inference request has succeeded.

## Refresh or disconnect

Use the **Refresh connection** icon to refresh a connected agent's Magnitude configuration. Use **Disconnect** to remove the Magnitude connection. Restart the agent if it still has the old settings loaded.

The connected card lists its configuration files. Prefer the app's actions over deleting the agent's configuration: those files may also contain unrelated settings.

## Choose your agent

* [Pi](/integrations/pi)
* [OpenCode](/integrations/opencode)
* [Hermes](/integrations/hermes)
* [OpenClaw](/integrations/openclaw)
* [Codex](/integrations/codex)
* [Claude Code](/integrations/claude-code)
* [Oh My Pi](/integrations/oh-my-pi)
* [Cline](/integrations/cline)


# Pi
Source: https://docs.magnitude.dev/integrations/pi

Connect Pi to your downloaded Magnitude models.

## Connect

1. [Install Pi](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent#quick-start) if needed.
2. Download a compatible model in Magnitude.
3. Open **Connections → Pi** and click **Connect**.
4. Select a downloaded model on the connected card, then click the command to copy it.
5. Paste it into your terminal from your project folder. On Windows, use PowerShell.

Use Pi’s `/model` selector to choose a model from the Magnitude provider. Normal Magnitude connections install the model configuration and skill; you do not need to install the Magnitude Pi extension.

## Run Pi

After connecting in Magnitude, start Pi with:

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
pi --provider magnitude --model MODEL_ID
```

Replace `MODEL_ID` with the exact model ID, such as `gemma-4-e2b-it-qat:gguf:q4`, rather than its display name. The command shown in **Connections** already includes the correct ID for your selected model, so you can copy it without editing. Keep Magnitude running; it loads the model when the agent requests it.

## Configuration

**Connect** writes `~/.pi/agent/models.json`. Location overrides: `PI_CODING_AGENT_DIR`.

### On another computer

1. In Magnitude, turn on **Settings → Network access**.
2. On the other computer, open `http://ADDRESS:10100` in a browser, using the address from **Reachable at**, and sign in with the **API key**.
3. In **Connections**, click **Copy setup prompt** on Pi and send it to your agent.

### Edit the files yourself

Use the address from **Reachable at** for `ADDRESS` and the **API key** for `API_KEY`.

`~/.pi/agent/models.json`:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "providers": {
    "magnitude": {
      "baseUrl": "http://ADDRESS:10100/inference/v1",
      "api": "openai-completions",
      "apiKey": "API_KEY",
      "models": [
        {
          "id": "MODEL_ID",
          "name": "MODEL_ID",
          "reasoning": false,
          "input": ["text"],
          "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
          "contextWindow": 32768,
          "maxTokens": 8192
        }
      ]
    }
  }
}
```


# Introduction
Source: https://docs.magnitude.dev/introduction

Run open models as fast as your hardware allows

Magnitude is an open source inference engine that tunes its kernels on your hardware to find the fastest way to run each model. It's over 2x faster than Ollama and works on Apple Silicon, NVIDIA, AMD, or just a CPU. One click connects it to the agent you already use (Pi, OpenCode, Hermes, Codex, and more).

<video aria-label="Magnitude demo: run local models on your machine">
  <source type="video/mp4" />

  <a href="https://magnitude.dev/videos/demo9-29.mp4">Watch the Magnitude demo</a>
</video>

## Why Magnitude?

* **2x faster than Ollama:** on average across popular local models, on Mac and NVIDIA
* **Tuned on your hardware:** kernels are tuned for each model when you download it
* **Best drafter built in:** each model ships with the fastest speculative decoding drafter
* **Memory that flexes:** quantized KV halves memory per agent, freed when agents stop
* **Fast concurrent sessions:** sessions share prefix caches to prevent slowdown
* **Works with your agent:** one click to connect Pi, OpenCode, Hermes, Codex, and more
* **Free, private, open source:** no token costs, nothing leaves your machine, Apache 2.0


# Models
Source: https://docs.magnitude.dev/models

Find, compare, download, and manage local models.

## Choose a recommendation

**Discover** assesses your hardware and shows up to five recommendations. Start with **Balanced**, or choose Fastest, Faster, Smarter, or Smartest to shift the speed–intelligence trade-off.

## Read the model details

| Detail | How to use it |
| - | - |
| Intelligence | Compare model capability using its benchmark index. The displayed percentage is an index score, not an accuracy percentage. |
| Speed | Compare estimated generation throughput on your machine. It is an estimate, not a benchmark of your current task. |
| Memory | Check expected runtime memory, which is different from download size. |
| Fidelity / quantization | Lower-bit variants generally use less memory and disk space; higher fidelity preserves more of the original model. |
| Context | Check how much conversation and working material the serving configuration can accommodate. |
| Capabilities | Check whether the model supports features your task needs, such as vision or tool use. |
| Speculation | See the speculative-decoding method prepared for the model. Magnitude handles its setup. |

Use **Details** for source, license, and configuration information. Model licenses are separate from Magnitude's license.

## Browse Catalog

**Catalog** lets you search beyond the recommendations, filter by compatibility, and sort models. A model appearing in Catalog does not guarantee it fits your machine. Read its compatibility information before downloading.

## Download and manage models

Click **Download** for the selected model. **My Models** shows downloaded models and acquisition progress; its search, filters, and sorting help you find them later.

* **Load model** puts a downloaded model into memory. Replacing a running model asks for confirmation.
* **Stop model** unloads it without deleting the download. A later request can load it again.
* **Remove** deletes the installed model files to recover disk space.

Downloading and loading are different steps. A downloaded model uses disk space even while stopped; a loaded model also uses inference memory. Magnitude loads a model on demand when an agent requests it and unloads it when idle or memory is tight, so the first response after a while takes longer. Supported models use speculative decoding (MTP, DFlash, or DSpark) and prompt caching automatically.

Models are stored in `~/.magnitude/models`. To use another folder, see [Settings](/settings#model-storage).

## Change your agent's model

Choose a downloaded Magnitude model in your agent's model selector. If it isn't listed, reconnect the agent from **Connections**, then reload or restart it as described in its [integration guide](/integrations/overview).

For terminal control, see [CLI reference](/reference).

## Usage

**Usage** shows local inference activity by model for **Today** or **All time**.

| Metric | Meaning |
| - | - |
| Input tokens | Prompt and conversation tokens, including cached input. |
| Cached input | Tokens reused from cache; a subset of input tokens. |
| Output tokens | Generated tokens. |
| Generation speed | Output tokens per second. |
| Time to first token | Time before the response starts. Loading and prompt processing can delay it even when generation is fast. |


# CLI reference
Source: https://docs.magnitude.dev/reference

Run Magnitude, manage models, and install updates from your terminal.

The Magnitude installation includes the `magnitude` CLI. In a new terminal, run:

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
magnitude --help
```

Running `magnitude` without a subcommand prints help. No npm installation is required.

## Run Magnitude

| Command | Purpose |
| - | - |
| `magnitude app open` | Show the desktop window. |
| `magnitude serve` | Run the service in the foreground without opening Desktop. |
| `magnitude status` | Check whether Magnitude is running and inspect service and model status. |

Model, catalog, hardware, and connection setup commands require a running Desktop or `magnitude serve`.
Stop a foreground server with Ctrl+C. Opening Desktop takes over from a foreground server.
Only one Desktop or `serve` instance can run under the same user account. Fully quit Desktop or stop the existing `serve` command before starting another server. See [Remote server](/remote-server) for setup.

Use **Launch at login** in Desktop Settings for login startup, and **Quit Magnitude** to stop Desktop.

## Find and download models

Assessment and downloads run in the background. Use status commands to check progress.

| Command | Purpose |
| - | - |
| `hardware` | Inspect detected hardware and memory. |
| `catalog status` | Check catalog preparation and assessment. |
| `catalog list` | List compatible catalog models. |
| `catalog show <model-id>` | Read model details. |
| `catalog recommendations` | Rank recommendations; defaults to Balanced and a limit of 10. |
| `catalog pull <model-id>` | Download or update a catalog model. |
| `catalog cancel <model-id>` | Cancel a download or model update. |
| `catalog remove <model-id>` | Remove an installed model. |
| `models status [model-id]` | Inspect downloaded models and loading state. |
| `models load <model-id>` | Load a downloaded model into memory. |
| `models stop` | Stop the active model without deleting it. |

Prefix each command with `magnitude`. Recommendation preferences are `fastest`, `faster`, `balanced`, `smarter`, and `smartest`; use `--preference` and `--limit` to choose.

## Connections

| Command | Purpose |
| - | - |
| `magnitude connections list` | Inspect installed agents and connection state. |
| `magnitude connections connect <harness>` | Configure an agent on this computer, for you. |
| `magnitude connections sync [harness]` | Refresh one or all configured integrations. |
| `magnitude connections remove <harness>` | Disconnect an agent. |

`connections connect` accepts `--set-model <model-id>` to select a model and `--install-skill` to install or refresh its Magnitude skill. Skill installation is automatic for Pi.

Harness IDs: `pi`, `opencode`, `hermes`, `openclaw`, `codex`, `claude-code`, `oh-my-pi`, and `cline`. See [Integrations](/integrations/overview) for agent-specific instructions.

## Updates

| Command | Purpose |
| - | - |
| `magnitude update` or `magnitude update check` | Check for a newer Magnitude release. |
| `magnitude update status` | Read update state without starting the app. |
| `magnitude update download` | Download the available update and wait until it is ready to install. |
| `magnitude update install` | Install a prepared update; stop inference and restart Desktop if it was running. |
| `magnitude update discard` | Remove a retained update download. |

These commands update Desktop, the server, and CLI together. Checking, downloading, inspecting, or discarding an update does not open Desktop.

`update install` refuses to interrupt a running `serve` command. Stop the server first. Installation leaves a stopped server stopped; run `magnitude serve` afterward. A prepared update is also installed at the next startup unless an earlier installation attempt failed. Failed attempts require an explicit `update install` retry. Linux installation may require administrator authorization.

## Help

Use `--help` after any command to see its options. `magnitude --version` prints the installed CLI version. `magnitude docs` lists documentation bundled with the CLI, and `magnitude docs cli` prints its command guide.

## Configuration

Settings are stored in `~/.magnitude/config.json`. See [Configuration file](/reference/configuration-file).


# Configuration file
Source: https://docs.magnitude.dev/reference/configuration-file

Every key in config.json.

Magnitude reads `~/.magnitude/config.json`, or `%USERPROFILE%\.magnitude\config.json` on Windows. **Settings** writes the same file. Keys Magnitude does not know are preserved.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "appearance": "system",
  "autoDownloadUpdates": true,
  "modelsDirectory": "/Volumes/SSD/Magnitude/models",
  "network": {
    "enabled": true,
    "bind": "100.64.1.5",
    "apiKey": "mag-…",
    "requireApiKey": true,
    "allowedHosts": ["my-mac.local"]
  },
  "contextLimits": { "softCapRatio": 0.9, "softCapMaxTokens": 200000 },
  "providers": {}
}
```

| Key | Values | Applies |
| - | - | - |
| `appearance` | `system`, `light`, `dark` | Immediately |
| `autoDownloadUpdates` | `true`, `false` | Immediately |
| `modelsDirectory` | Absolute path of the model folder. Absent means `~/.magnitude/models`. A symbolic link is followed. | Next start |
| `network.enabled` | `true` to accept connections from other devices. Absent or `false` means this computer only. | Next start |
| `network.bind` | One IP address of this computer. Absent means all interfaces. | Next start |
| `network.apiKey` | The key other devices must send. Generated when enabled through Settings. When editing this file, supply a long, randomly generated secret. | Next start |
| `network.requireApiKey` | `false` lets other devices connect without a key. Default `true`. | Next start |
| `network.allowedHosts` | Hostnames accepted in requests from other devices, in addition to IP addresses, `localhost`, `host.docker.internal`, and `.ts.net` names. | Next start |
| `contextLimits.softCapRatio` | Fraction of a model's context window used before compaction. Default `0.9`. | Next model load |
| `contextLimits.softCapMaxTokens` | Absolute cap on context tokens, or `null`. | Next model load |
| `providers` | OpenAI-compatible endpoints to expose alongside local models. Run `magnitude docs custom-endpoints` for the schema. | Immediately |

Invalid values are ignored and logged. A relative `modelsDirectory` or a `network.bind` that is not an IP address falls back to the default, and **Settings** shows the reason.

## Other files in `~/.magnitude`

| Path | Contents |
| - | - |
| `models/` | Downloaded models, unless `modelsDirectory` points elsewhere. |
| `cache/` | Cached and derived data. Safe to delete while Magnitude is not running. |
| `harness-connections.json` | Connection records for **Connections**. |

Do not delete the whole directory to fix one problem. Removing the app and removing model data are separate actions.


# Remote server
Source: https://docs.magnitude.dev/remote-server

Run models on a dedicated machine and use them from another computer.

Use a machine such as a Mac Studio, a DGX Spark or a Linux box with a GPU for inference while your agent runs on your laptop. The server needs to be reachable from your laptop, through your local network or a private network such as Tailscale.

On Linux and macOS, Magnitude runs as a service: it starts at boot, keeps running after you log out, restarts if it crashes, and installs its own updates between requests. On Windows, run `magnitude serve` under a service wrapper; see [Windows](#windows).

## Install on the server

Run this on the server, over SSH if needed:

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -fsSL https://magnitude.dev/install.sh | sh
```

On Linux, the installer first asks whether to run Magnitude as a server, then asks for your password once, and does the rest without further questions. Answer **y** to set the server up right away. If you answer no, or don't answer within a minute, set it up later with `magnitude server setup`.

On macOS the installer installs the app without asking. Then run:

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
magnitude server setup
```

You can also install the package for [Linux](/installation/linux) or the app for [macOS](/installation/macos) yourself and run `magnitude server setup` afterwards. Run it as yourself, not with `sudo`: it asks for your password once, for the one step that needs it.

## What setup does

`magnitude server setup` registers Magnitude as a service, turns on [network access](/api/network-access), creates a network access key, and prints how to reach the server:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Magnitude is running as a server on this machine.

Open it in a browser on another computer:
  http://192.168.1.20:10100

Network access key: mag_…
```

Save the key; `magnitude status` never shows it. Afterwards it is in **Settings → Network access** in the browser app on this machine, and setting the server up again keeps it.

<Tabs>
  <Tab title="Linux">
    Magnitude runs as the `magnitude.service` systemd unit under its own `magnitude` system account. Its models, settings and logs live in `/var/lib/magnitude`, and its configuration in `/var/lib/magnitude/config.json`. Any account on the machine can run `magnitude status`, `magnitude update` and `magnitude models` right away; the models, settings and keys stay readable only by the service.

    Setup creates the `magnitude` account as a system account with no login. If the machine already has an account or group named `magnitude` that isn't one, such as a person's account, setup leaves it alone and stops without changing anything.

    Logs: `journalctl -u magnitude`
  </Tab>

  <Tab title="macOS">
    Magnitude runs as a LaunchDaemon, `dev.magnitude.server`, as you. It uses your own `~/.magnitude`, so the desktop app and the server share models and settings. It starts at boot before anyone logs in and keeps running after you log out.

    * macOS lists it in **System Settings → General → Login Items** as Magnitude. If you switch it off there, it no longer starts at boot.
    * With FileVault on, nothing starts until someone unlocks the disk after a restart.
    * As a background service it can't read privacy-protected folders such as Desktop and Documents without Full Disk Access. Serving models isn't affected.

    Logs: `~/.magnitude/logs/server.log`
  </Tab>
</Tabs>

If setup stops partway, for example because the server didn't start within two minutes, it says where to look; run `magnitude server setup` again to finish once that's fixed.

Check on the server at any time with:

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
magnitude status
```

It shows each address other devices can use, without the key.

## Download a model

On the server:

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
magnitude hardware
magnitude catalog recommendations --preference balanced --limit 5
magnitude catalog pull "MODEL_ID"
magnitude models status "MODEL_ID"
```

If recommendations are not ready, run `magnitude catalog status` to check preparation, then request recommendations again. Magnitude loads the model on the first inference request. To load it ahead of time, run `magnitude models load "MODEL_ID"`.

Or do all of this from the browser app on your laptop.

## Use the app from your laptop

Open `http://SERVER_IP:10100` in a browser on your laptop and sign in with the network access key. From there you can browse recommendations, download and load models, watch usage, and change settings. See [Open the app from another device](/api/network-access#open-the-app-from-another-device).

## Connect from your laptop

Use these settings in your agent or app:

| Setting | Value |
| - | - |
| OpenAI-compatible base URL | `http://SERVER_IP:10100/inference/v1` |
| API key | The network access key |
| Model | The exact model ID you downloaded |

Use your agent's [configuration instructions](/api/network-access#configure-the-app-or-agent), then [check the connection](/api/network-access#check-the-connection) from your laptop.

To use an agent on the server itself, connect it from your own terminal there:

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
magnitude connections connect pi
```

This writes the agent's configuration into your home folder, pointing at the server on `localhost`.

## Updates

The server checks for updates about once an hour, downloads them, and installs them when no request or agent turn is running. Clients reconnect after a short pause. If an update needs something only you can do, `magnitude status` and the logs say so. To install a downloaded update right away, restart the server (`sudo systemctl restart magnitude` on Linux, `sudo launchctl kickstart -k system/dev.magnitude.server` on macOS); it installs the update as soon as it is idle. Running the install script again upgrades a Linux server in place; on macOS it asks you to remove the server first, since the server keeps itself up to date.

## The desktop app on the same machine

The app and the server can't run at the same time. Opening the app while the server runs shows a screen that offers to keep the server, which opens it in your browser instead, or to stop it and use the app. On Linux, stopping it from the app at your desktop needs no password; over a remote session, and on macOS, it asks for administrator authorization.

## Stop and remove the server

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
magnitude server remove
```

It stops the service and removes it, and asks for your password once. Its data stays: in `/var/lib/magnitude` on Linux, now owned by root, or in `~/.magnitude` on macOS. Run `magnitude server setup` again to bring the server back with the same models. If removal stops partway, run it again to finish.

## Without the service

To serve only until you stop it, for example to try things out:

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
magnitude serve
```

It runs in the foreground and Ctrl+C stops it. On Linux, `nohup magnitude serve &` keeps it serving after you disconnect, until the machine restarts; on macOS, closing the terminal stops it. Opening the desktop app stops it and takes over serving. Like the service, it installs downloaded updates between requests whenever it can without asking for a password: on Linux when `sudo` doesn't ask you for one, on macOS when you can write to the Applications folder. Otherwise it prints a line saying the update is downloaded; stop it, run `magnitude update install`, and start it again. For network access without the service, see [Network access](/api/network-access).

## Windows

Magnitude has no server mode on Windows; `magnitude server setup` explains this and changes nothing. To run Magnitude as a service, wrap `magnitude serve` with [NSSM](https://nssm.cc), as you might for Ollama. Download NSSM and use the full path to its `nssm.exe` (for example `C:\nssm\win64\nssm.exe`) wherever these steps say `nssm`, unless you put it on your `PATH`.

1. Sign in as the account that will run the server and install Magnitude for [Windows](/installation/windows). The service must run as this same account: the installation is private to it, so other accounts, including `LocalSystem`, can't start it. This account doesn't need to be an administrator.
2. Still signed in as that account, turn on network access: create or edit `%USERPROFILE%\.magnitude\config.json` with a `network` object and a long, random key. All fields are in [Configuration file](/reference/configuration-file).

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "network": {
    "enabled": true,
    "apiKey": "YOUR_LONG_RANDOM_KEY"
  }
}
```

Then create the folder for the service's log in PowerShell:

```powershell theme={"theme":{"light":"github-light","dark":"github-dark"}}
New-Item -ItemType Directory -Force "$env:USERPROFILE\.magnitude\logs"
```

3. In an administrator PowerShell, register the service to run as that account. An administrator can do this from their own session: set `$account` to the account from step 1 (`COMPUTERNAME\user`, or `DOMAIN\user` for a domain account) and `$userProfile` to its profile folder. `magnitude serve` must be started through the Magnitude command in `Magnitude CLI`, as below; the app's own `resources\magnitude.exe` refuses to serve.

```powershell theme={"theme":{"light":"github-light","dark":"github-dark"}}
$account = "$env:COMPUTERNAME\alice"
$userProfile = "C:\Users\alice"
$cred = Get-Credential $account
nssm install Magnitude "$userProfile\AppData\Local\Programs\Magnitude CLI\magnitude.exe" serve
nssm set Magnitude ObjectName $account $cred.GetNetworkCredential().Password
nssm set Magnitude AppStdout "$userProfile\.magnitude\logs\server.log"
nssm set Magnitude AppStderr "$userProfile\.magnitude\logs\server.log"
nssm set Magnitude AppExit Default Restart
nssm start Magnitude
```

`Get-Credential` asks for the account's password in a prompt, so it isn't typed on the command line or saved in your PowerShell history. Don't write the password into the `nssm set` command itself. If the account's password changes, run the `Get-Credential` and `ObjectName` lines again.

4. If other computers need to reach the server, allow inbound TCP port 10100 in Windows Defender Firewall from the administrator PowerShell:

```powershell theme={"theme":{"light":"github-light","dark":"github-dark"}}
New-NetFirewallRule -DisplayName "Magnitude" -Direction Inbound -Protocol TCP -LocalPort 10100 -Action Allow -Profile Private
```

This allows connections on networks Windows treats as private. If the server's network is set to Public, change its profile to Private in Settings, or use `-Profile Private,Public` only if you trust that network.

5. Download a model. Models download through the running server, so do this once the service is running: use the commands in [Download a model](#download-a-model) on the server, or the browser app from your laptop.

The service keeps running when you or another user log off. Don't open the desktop app while it runs: the app can't serve until you stop the service, and says so. To install an update, stop the service (`nssm stop Magnitude`), run `magnitude update install`, then start it again. To remove the service, stop it first, then remove it; a running service keeps serving, including on the network, until it stops:

```powershell theme={"theme":{"light":"github-light","dark":"github-dark"}}
nssm stop Magnitude
nssm remove Magnitude confirm
```


# Settings
Source: https://docs.magnitude.dev/settings

What each setting does and where it is saved.

Open **Settings** in the sidebar. Every setting is a key in `config.json`; editing the file and using Settings are equivalent. See [Configuration file](/reference/configuration-file).

## Theme

System, Light, or Dark. Applies immediately.

## Launch at login

Starts Magnitude in the background with its tray icon when you log in. The window stays closed. On macOS, the first enable may ask you to allow Magnitude under **System Settings → General → Login Items**.

## Model storage

Downloaded models are kept in `~/.magnitude/models`, or `%USERPROFILE%\.magnitude\models` on Windows. Click **Change…** to choose another folder, or **Use default** to return to it. The new folder is used after Magnitude restarts; a **Restart required** notice appears until then.

Changing the folder does not move models. Models in the previous folder stay there and are not listed until you move them. To move them, quit Magnitude, run the command shown in the notice, then open Magnitude again:

<Tabs>
  <Tab title="macOS / Linux">
    ```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
    mv "PREVIOUS_FOLDER/"* "NEW_FOLDER/"
    ```
  </Tab>

  <Tab title="Windows">
    ```powershell theme={"theme":{"light":"github-light","dark":"github-dark"}}
    robocopy "PREVIOUS_FOLDER" "NEW_FOLDER" /E /MOVE
    ```
  </Tab>
</Tabs>

The folder must be on a volume that supports symbolic links and file permissions, such as APFS, ext4, or NTFS. exFAT and FAT32 volumes are not supported. If the folder is itself a symbolic link, Magnitude uses the folder it points to.

## Network access

Off by default. When on, other devices can use Magnitude for inference, and a browser on another device can open this app after signing in with the API key.

| Setting | Meaning |
| - | - |
| Address | **All interfaces** accepts connections on every address this computer has. Choosing one address, such as a Tailscale address, accepts connections only on that network. |
| API key | Generated once. Other devices send it with every request and sign in to the app with it. Turn off **Require key** only on a network you trust; the app always requires it. **Regenerate** replaces it. |
| Reachable at | The base URL to use on other devices. |

These settings also apply to `magnitude serve`. Changes apply after Magnitude restarts. A regenerated key signs out browsers on other devices then.

## This browser

Appears only when the app is open in a browser on another device. **Sign out** ends this browser's session. For how to connect from another computer, a tailnet, a container, or WSL, see [Network access](/api/network-access).

## Automatic updates

Downloads updates in the background when they are available. In Desktop, use **Restart to update** to install. A headless server keeps running and applies a prepared update at its next startup. See [Update the server](/remote-server#update-the-server).


# Troubleshooting
Source: https://docs.magnitude.dev/troubleshooting

Find the problem and take the next useful action.

Start with **Status** in Desktop or `magnitude status` in a terminal. It distinguishes service startup from model loading and downloads.

## The service won't start

Read the error on Status and use **Retry service** when offered. If it reports an occupied port, close the application using that port before retrying. For a headless server, read the error printed by `magnitude serve`.

For terminal diagnostics:

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
magnitude status
```

## Another Magnitude instance is running

Fully quit Desktop before starting `magnitude serve`. Closing its window can leave it running. If another `serve` command is running, stop that command before starting another.

## Magnitude command not found

Open a **new terminal** and run `magnitude --help`.

* **macOS:** open Desktop once to register the CLI in your shell. Without a graphical session, run `/Applications/Magnitude.app/Contents/Resources/magnitude` directly.
* **Windows:** the installer updates your user PATH; existing terminals may retain the old PATH. Rerun the installer if command registration failed.
* **Linux:** install the desktop package through your package manager; it owns `/usr/bin/magnitude`.

If an old CLI still runs, inspect which executable your terminal finds:

<Tabs>
  <Tab title="macOS / Linux">
    ```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
    command -v magnitude
    ```
  </Tab>

  <Tab title="Windows">
    ```powershell theme={"theme":{"light":"github-light","dark":"github-dark"}}
    where.exe magnitude
    ```
  </Tab>
</Tabs>

Don't install the old npm package to repair the desktop CLI.

## A download failed

Check your internet connection and free disk space. Read the failure in **My Models**, then retry the download. Keep completed models; you do not need to erase all downloads to repair one failure.

## A model won't load or was stopped

Read its error in **Status** or **My Models**. Close memory-heavy applications or choose a smaller recommendation. A model's fit assessment does not reserve that memory against other apps. Longer conversations use more memory; a fresh conversation can help.

Stopping a model does not delete its files. Use **Load model** to try again when enough memory is available.

## My agent can't see or use a model

1. Confirm the model has finished downloading.
2. Check **Connections**. Use **Repair connection** if offered, or **Refresh connection** to refresh a connected agent.
3. Restart or reload the agent and select the Magnitude model.
4. Keep Magnitude running and check Status if requests still fail.

See your [integration guide](/integrations/overview) for specific model-selection and gateway behavior.

## My agent runs in WSL, a container, or on another computer

Connections cannot configure agents there. Use the server's base URL and API key in the agent's configuration. See [Network access](/api/network-access) for connection options and errors, or [Windows and WSL](/api/windows-wsl) for WSL networking.

## My models disappeared after changing the model folder

Changing **Model storage** does not move models. They are still in the previous folder. Move them with the command shown in Settings, or switch back with **Use default**. See [Settings](/settings#model-storage).

## An app update failed

Open **Settings → Application updates** and read the error. Use **Retry update** when offered. You can **Discard download** if you want to remove the retained installer and download it again.

On Linux, installation may require package-manager authorization. Do not quit the installer while it is replacing the app.

## Windows cannot save an update

Versions 0.1.4 and 0.1.5 can fail with “The downloaded update could not be saved.” Install a newer version containing the fix using its Windows installer. The affected versions cannot install the fix through their updater. Deleting the updates folder does not repair it; keep your models and settings.

## There's no tray icon

Some Linux desktops do not provide a supported tray host. Open Magnitude from the applications menu. You can stop it with **Quit Magnitude**.

## Responses are slower than expected

Check **Usage** to distinguish generation speed from time to first token. Loading, longer prompts, concurrent agents, and memory pressure can all affect response time. Try a smaller or faster recommendation and reduce simultaneous work. See [Usage](/models#usage).

## Report a problem

Include your app version, OS, hardware, the model involved, the exact error, and the steps to reproduce it. For Linux desktop issues, include your desktop environment and whether you use X11 or Wayland.

Attach the logs from `~/.magnitude/logs` (`%USERPROFILE%\.magnitude\logs` on Windows): `service.log`, `inference.log`, and `desktop.log`.

Remove credentials, prompts, and private project data from anything you share. Don't delete the entire `.magnitude` folder as a general repair step.

[Report an issue](https://github.com/magnitudedev/magnitude/issues) or ask in [Discord](https://discord.gg/EHt48pPWdC).