> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokios.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Tokios exposes private local models through https://api.tokios.com using an outbound-only connector tunnel.
> Use 'connector' for the local tokios-connector process.
> Use 'deployment' for the public model name in the API model field.
> Use 'upstream model id' for the model served by Ollama, llama.cpp, vLLM, LM Studio, or another local backend.
> API keys use the prefix sk-tok-. Connector tokens use the prefix ct-tok-.

# Lemonade Server remote access — AMD NPU and GPU

> Reach your Lemonade Server API from anywhere — AMD NPU, Vulkan, ROCm, CUDA. Set up secure remote access with Tokios connector. Start serving in 5 minutes.

By default, Lemonade Server listens on `http://127.0.0.1:13305/v1` — it isn't reachable from another machine unless you bind it wider or forward the port. Lemonade Server doesn't ship built-in authentication for remote access. Keep it on localhost and run the Tokios connector next to it instead: the connector dials out to `https://api.tokios.com`, and your tools, teammates, or agents call one authenticated endpoint from anywhere.

> [!NOTE]
>
> **Last verified: 2026-10-14.** Lemonade Server is actively developed — check [lemonade-server.ai](https://lemonade-server.ai/) for the latest release.

> [!TIP]
>
> **AMD NPU support.** Lemonade Server is the only local LLM server that accelerates inference on AMD Ryzen AI NPUs (Ryzen AI 300/400 series). It also auto-detects Vulkan, ROCm, CUDA, and Metal backends, so it works across AMD, NVIDIA, and Apple Silicon hardware without manual configuration.

## What is Lemonade Server

Lemonade Server is an open-source local LLM server backed by AMD. It exposes an OpenAI-compatible API at `http://localhost:13305/v1` and supports multiple model formats (GGUF, ONNX, FLM) across multiple backends:

* **AMD Ryzen 7000/8000/200 series** — GPU acceleration via Vulkan (llama.cpp backend)
* **AMD Ryzen AI MAX+ (Strix Halo)** — ROCm with vLLM or llama.cpp
* **AMD Ryzen AI 300/400 series** — NPU acceleration via ONNX Runtime GenAI (hybrid NPU+iGPU execution)
* **NVIDIA GPUs** — CUDA acceleration
* **Apple Silicon** — Metal backend

Lemonade Server auto-detects your hardware and selects the best backend. You can also override the backend manually if needed.

> **Why not just bind Lemonade Server to 0.0.0.0?**
>
> Binding Lemonade Server to all interfaces (`0.0.0.0`) makes it reachable from your network, but Lemonade Server doesn't ship built-in authentication for remote callers — anyone who can reach port `13305` can call the API. If your ISP uses CGNAT, you don't have a stable public IP to forward to in the first place. Tokios adds scoped `sk-tok-…` API keys without opening an inbound port.

> **Why not use Tailscale or Cloudflare Tunnel?**
>
> Tailscale solves personal access well — your own devices join a private mesh network and can reach each other securely. The catch is for anything beyond personal use: teammates or SaaS clients that need to call your model have to join your tailnet first, which doesn't fit a public API key model. Cloudflare Tunnel routes traffic through Cloudflare's edge with no inbound port required, but by default Cloudflare buffers responses rather than streaming them unless the response carries a `text/event-stream` content-type header, and proxied requests are subject to Cloudflare's proxy timeouts (around 100 seconds on the free tier) — long generations can get cut off mid-stream.

> [!NOTE]
>
> None of this is a knock on these tools — they're solving a different problem (device mesh networking, edge proxying). Tokios is purpose-built for one thing: turning a local model endpoint into an authenticated API you can call from anywhere.

## Prerequisites

Before you start, make sure you have:

* **Lemonade Server installed** — see [How to install Lemonade Server](#how-to-install-lemonade-server) below
* **A model downloaded** — use `lemonade pull <model>` to download a model
* **Tokios connector** — you'll install this during setup

## How to install Lemonade Server

Lemonade Server provides installers for Windows, Linux, macOS, and Docker. As of v10.1, the CLI command is `lemonade` (the old `lemonade-server` CLI is deprecated).

```powershell Windows (MSI) theme={"theme":{"light":"github-light","dark":"css-variables"}}
Download the MSI installer from the [Lemonade Server releases page](https://github.com/lemonade-sdk/lemonade/releases) and run it. The `lemond` service auto-starts on install.
```

```bash Linux (Snap) theme={"theme":{"light":"github-light","dark":"css-variables"}}
sudo snap install lemonade-server
```

```bash Linux (APT, Ubuntu/Debian) theme={"theme":{"light":"github-light","dark":"css-variables"}}
sudo apt update
sudo apt install lemonade-server
```

```bash macOS theme={"theme":{"light":"github-light","dark":"css-variables"}}
Download the macOS installer from the [Lemonade Server releases page](https://github.com/lemonade-sdk/lemonade/releases).
```

```bash Docker theme={"theme":{"light":"github-light","dark":"css-variables"}}
docker run -p 13305:13305 lemonade-sdk/lemonade-server
```

After installation, verify Lemonade Server is running:

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
lemonade status
```

You should see the server status and detected backend (Vulkan, ROCm, CUDA, Metal, or NPU).

## How to serve a model with Lemonade Server

Download and serve a model in 2 commands:

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
# Download a model
lemonade pull Qwen3-0.6B-GGUF

# Serve the model
lemonade run Qwen3-0.6B-GGUF
```

Lemonade Server auto-detects your hardware and selects the best backend. The model is now serving at `http://localhost:13305/v1`.

> [!TIP]
>
> **NPU acceleration on AMD Ryzen AI.** If you have an AMD Ryzen AI 300/400 series processor, Lemonade Server can use the NPU for inference. Pull an ONNX model optimized for NPU execution:
>
> ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
> lemonade pull Llama-3.2-1B-Instruct-NPU
> lemonade run Llama-3.2-1B-Instruct-NPU
> ```
>
> NPU models use hybrid NPU+iGPU execution and are identified by the `-NPU` suffix.

### Common Lemonade Server CLI commands

| Command | Description |
| - | - |
| `lemonade pull <model>` | Download a model |
| `lemonade run <model>` | Serve a model |
| `lemonade run <model> --ctx-size 8192` | Serve with custom context size |
| `lemonade list` | List available models |
| `lemonade list --downloaded` | List downloaded models |
| `lemonade status` | Check server status and detected backend |
| `lemonade status --json` | Check status in JSON format |
| `lemonade bench <model>` | Benchmark a model |

## The outbound-only way

**1. Run Lemonade Server locally, as usual**

Keep Lemonade Server on `127.0.0.1` — don't bind it wider than loopback. Pull and run your model:

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
lemonade pull Qwen3-0.6B-GGUF
lemonade run Qwen3-0.6B-GGUF
```

Leave it listening on the default `http://127.0.0.1:13305`.

**2. Pair the Tokios connector**

Sign in at [tokios.com/console](https://tokios.com/console), open the **Setup** tab, and click **Start pairing**. Tokios shows a one-time **claim code** like `TKS-XXXX-XXXX`, valid for about 15 minutes.

On the machine running Lemonade Server, run the install one-liner for your OS:

```powershell Windows theme={"theme":{"light":"github-light","dark":"css-variables"}}
irm https://tokios.com/downloads/install/windows | iex; tokios-install -Code 'TKS-XXXX-XXXX'
```

```bash macOS theme={"theme":{"light":"github-light","dark":"css-variables"}}
curl -fsSL https://tokios.com/downloads/install/macos | sh -s -- --code TKS-XXXX-XXXX
```

```bash Linux theme={"theme":{"light":"github-light","dark":"css-variables"}}
curl -fsSL https://tokios.com/downloads/install/linux | sh -s -- --code TKS-XXXX-XXXX
```

Already have `tokios-connector` installed? Pass the code directly instead:

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
tokios-connector TKS-XXXX-XXXX
```

Back in the console, **approve** the device on the **Setup** or **Connectors** tab. The connector's token is delivered over the tunnel once approved — you never see it on screen or paste it into a file.

**3. Point the connector at Lemonade Server's /v1 API**

Lemonade Server exposes an OpenAI-compatible surface at `/v1`, and that's what Tokios talks to. For the basic single-model path, the console's Setup wizard uses `http://127.0.0.1:13305/v1` as the upstream automatically. If you're serving multiple models through a `tokios-connector.json` config, set the upstream `BaseUrl` explicitly:

```json theme={"theme":{"light":"github-light","dark":"css-variables"}}
{
  "Upstream": {
    "BaseUrl": "http://127.0.0.1:13305/v1"
  }
}
```

See [Connector config](/reference/connector-config.md) for the full multi-model file format.

**4. Register a deployment**

In the [Models](https://tokios.com/console/models) tab, register the Lemonade Server model and choose a **public name** — for example, `qwen3-tunnel`. That public name, not Lemonade's local model id, is what clients send in the `model` field.

**5. Create an API key**

In the [Keys](https://tokios.com/console/keys) tab, click **Create key**. Optionally scope it to specific deployments with model-name patterns (comma-separated globs, `*` for all). Copy the `sk-tok-…` key now — it's shown only once.

## Use it from anywhere

Once you have a deployment name and an API key, any OpenAI- or Anthropic-compatible client can reach your Lemonade Server model — from another machine, a teammate's laptop, or a hosted agent.

```bash curl theme={"theme":{"light":"github-light","dark":"css-variables"}}
curl https://api.tokios.com/v1/chat/completions \
  -H "Authorization: Bearer sk-tok-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-tunnel",
    "stream": true,
    "messages": [{"role": "user", "content": "Hello!"}]
  }'
```

```python Python (OpenAI SDK) theme={"theme":{"light":"github-light","dark":"css-variables"}}
from openai import OpenAI

client = OpenAI(
    base_url="https://api.tokios.com/v1",
    api_key="sk-tok-YOUR_KEY",
)

response = client.chat.completions.create(
    model="qwen3-tunnel",
    messages=[{"role": "user", "content": "Hello!"}],
    stream=True,
)

for chunk in response:
    print(chunk.choices[0].delta.content or "", end="")
```

```bash Claude Code theme={"theme":{"light":"github-light","dark":"css-variables"}}
export ANTHROPIC_BASE_URL=https://api.tokios.com
export ANTHROPIC_API_KEY=sk-tok-YOUR_KEY
claude --model qwen3-tunnel
```

> [!TIP]
>
> The `model` field is always your registered **deployment** name (`qwen3-tunnel` above), never Lemonade's local model id. See [Use Claude Code](/guides/claude-code.md) for persisting the environment variables across sessions.

## What is AMD NPU support

AMD Ryzen AI 300/400 series processors include a dedicated Neural Processing Unit (NPU) for AI workloads. Lemonade Server is the only local LLM server that accelerates inference on the AMD NPU using hybrid NPU+iGPU execution.

### How NPU acceleration works

* **Model format**: NPU-optimized models use ONNX format (identified by the `-NPU` suffix, e.g., `Llama-3.2-1B-Instruct-NPU`)
* **Execution**: Lemonade Server splits inference between the NPU and iGPU using OnnxRuntime GenAI
* **Backend**: The NPU backend is automatic — Lemonade Server detects your Ryzen AI processor and selects NPU execution when you run an NPU-optimized model
* **Performance**: NPU acceleration offloads work from the CPU and GPU, reducing power consumption and freeing resources for other tasks

### Which AMD processors support NPU inference

| Processor series | NPU support | Backend |
| - | - | - |
| AMD Ryzen AI 300 series (Strix Point) | Yes | NPU via ONNX |
| AMD Ryzen AI 400 series | Yes | NPU via ONNX |
| AMD Ryzen AI MAX+ (Strix Halo) | No NPU, but powerful iGPU | ROCm/vLLM or Vulkan |
| AMD Ryzen 7000/8000 series | No NPU | Vulkan (llama.cpp) |

> [!NOTE]
>
> NPU support requires AMD Ryzen AI Software drivers. Lemonade Server bundles the necessary runtime, but make sure your system has the latest AMD Adrenalin drivers installed.

## Lemonade Server vs other backends

Lemonade Server is one of several backends Tokios supports. Here's how it compares:

| Feature | Lemonade Server | Ollama | llama.cpp | vLLM |
| - | - | - | - | - |
| **AMD NPU support** | Yes (Ryzen AI 300/400) | No | No | No |
| **Auto-detect backend** | Yes (Vulkan/ROCm/CUDA/Metal) | Manual | Manual | Manual |
| **Setup complexity** | Low (installer) | Low (one command) | Medium (build) | High (Python GPU server) |
| **Model formats** | GGUF, ONNX, FLM | GGUF | GGUF | Hugging Face |
| **Best for** | AMD hardware; cross-platform | Beginners; quickest start | Hands-on GGUF serving | High-throughput GPU serving |

> [!TIP]
>
> Lemonade Server is a great choice if you have AMD hardware (especially Ryzen AI with NPU) or want a cross-platform server that auto-detects your backend. If you just want the quickest start on any hardware, [Ollama](/guides/ollama-remote-access.md) is still the easiest.

## FAQ

> **What port does Lemonade Server use?**
>
> Lemonade Server listens on port **13305** by default, bound to `127.0.0.1` (localhost only). The OpenAI-compatible API is at `http://localhost:13305/v1`. You can verify Lemonade Server is running with `lemonade status` or `curl http://localhost:13305/v1/models`.

> **How do I know which backend Lemonade Server is using?**
>
> Run `lemonade status` to see the detected backend (Vulkan, ROCm, CUDA, Metal, or NPU). Lemonade Server auto-detects your hardware and selects the best backend. You can also use `lemonade status --json` for machine-readable output.

> **Does Lemonade Server support AMD NPU?**
>
> Yes. Lemonade Server is the only local LLM server that accelerates inference on AMD Ryzen AI 300/400 series NPUs. Pull an NPU-optimized model with `lemonade pull <model>-NPU` and run it with `lemonade run <model>-NPU`. The NPU backend uses hybrid NPU+iGPU execution via OnnxRuntime GenAI.

> **Can I use Lemonade Server with NVIDIA GPUs?**
>
> Yes. Lemonade Server auto-detects NVIDIA GPUs and uses the CUDA backend. It works on any hardware that supports Vulkan, ROCm, CUDA, or Metal — AMD, NVIDIA, and Apple Silicon are all supported.

> **How do I expose Lemonade Server to my network?**
>
> Don't expose Lemonade Server directly — use Tokios instead. Tokios adds authenticated remote access without opening an inbound port. See [the setup steps above](#the-outbound-only-way) for the full walkthrough.

> **Does streaming work?**
>
> Yes. Set `"stream": true` and Tokios returns standard server-sent events (SSE) in OpenAI or Anthropic format, depending on which API surface you called.

> **Can I share access with teammates without exposing Lemonade Server directly?**
>
> Yes. Create a separate `sk-tok-…` key per teammate in the [Keys](https://tokios.com/console/keys) tab, and scope each key to only the deployments they need. Revoking a key stops it from authenticating immediately, so you can cut off access without touching Lemonade Server or the connector.

> **Can I expose more than 1 Lemonade Server model?**
>
> Yes. Register additional deployments in the [Models](https://tokios.com/console/models) tab, or use a `tokios-connector.json` config file to define multiple upstreams and routes for a single connector. See [Connector config](/reference/connector-config.md).

> **How do I update Lemonade Server?**
>
> On Linux, run `sudo apt update && sudo apt upgrade lemonade-server` (APT) or `sudo snap refresh lemonade-server` (Snap). On Windows, download the latest MSI installer from the [releases page](https://github.com/lemonade-sdk/lemonade/releases).

> **What model architectures does the NPU support?**
>
> The NPU supports specific model architectures optimized for ONNX execution. Run `lemonade list` to see available NPU models (identified by the `-NPU` suffix). Not all models are NPU-compatible — GGUF models run on the GPU/CPU backend instead. See the [Lemonade FAQ](https://lemonade-server.ai/docs/guide/faq/) for the full list of NPU-supported architectures.

## Your model never leaves your machine — your endpoint works everywhere

Lemonade Server keeps doing exactly what it does today, on localhost, with no inbound ports and no exposed API. The connector only dials out. Everything past that — auth, routing, streaming — is one endpoint you can call from any machine, teammate, or agent you choose to give a key to.

> **[Quickstart](/quickstart.md)**
>
> Pair a connector and register your first model end to end.

> **[API keys](/setup/api-keys.md)**
>
> Create, scope, and rotate `sk-tok-…` keys for teammates and agents.

> **[Strix Halo setup](/use-cases/strix-halo.md)**
>
> Turn your AMD Strix Halo box into a model endpoint with Lemonade Server.

> **[Supported backends](/setup/supported-backends.md)**
>
> See all backends Tokios supports — Ollama, llama.cpp, vLLM, LM Studio, and more.

## Sources

* [Lemonade SDK GitHub repository](https://github.com/lemonade-sdk/lemonade)
* [Lemonade Server official documentation](https://lemonade-server.ai/docs/guide/faq/)
* [AMD: Unlocking a Wave of LLM Apps on Ryzen AI Through Lemonade Server](https://www.amd.com/en/developer/resources/technical-articles/unlocking-a-wave-of-llm-apps-on-ryzen-ai-through-lemonade-server.html)
* [Getting Started with Lemonade | AMD AI Playbooks](https://developer.amd.com/playbooks/lemonade-getting-started/)
* [Lemonade Server CLI documentation](https://lemonade-server.ai/docs/guide/cli/)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.