> ## 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 원격 접속 — AMD NPU 및 GPU

> 어디서든 Lemonade Server API에 접근하십시오. AMD NPU, Vulkan, ROCm, CUDA를 지원합니다. Tokios 커넥터로 안전한 원격 접속을 설정하고 5분 만에 서빙을 시작하십시오.

기본적으로 Lemonade Server는 `http://127.0.0.1:13305/v1`에서 수신합니다 — 더 넓은 범위로 바인딩하거나 포트를 전달하지 않는 한 다른 머신에서 접근할 수 없습니다. Lemonade Server는 원격 접근을 위한 내장 인증을 제공하지 않습니다. localhost에 두고 Tokios 커넥터를 옆에 실행하세요: 커넥터가 `https://api.tokios.com`으로 아웃바운드 연결을 하고, 도구, 팀원 또는 에이전트는 어디서든 인증된 엔드포인트 하나로 호출합니다.

> [!NOTE]
>
> **마지막 확인: 2026-10-14.** Lemonade Server는 활발히 개발 중입니다 — 최신 릴리스는 [lemonade-server.ai](https://lemonade-server.ai/)를 확인하세요.

> [!TIP]
>
> **AMD NPU 지원.** Lemonade Server는 AMD Ryzen AI NPU(Ryzen AI 300/400 시리즈)에서 추론을 가속하는 유일한 로컬 LLM 서버입니다. 또한 Vulkan, ROCm, CUDA 및 Metal 백엔드를 자동 감지하므로 AMD, NVIDIA 및 Apple Silicon 하드웨어에서 수동 구성 없이 작동합니다.

## Lemonade Server란

Lemonade Server는 AMD가 지원하는 오픈소스 로컬 LLM 서버입니다. `http://localhost:13305/v1`에서 OpenAI 호환 API를 노출하며, 여러 백엔드에서 여러 모델 형식(GGUF, ONNX, FLM)을 지원합니다:

* **AMD Ryzen 7000/8000/200 시리즈** — Vulkan을 통한 GPU 가속(llama.cpp 백엔드)
* **AMD Ryzen AI MAX+ (Strix Halo)** — vLLM 또는 llama.cpp와 ROCm
* **AMD Ryzen AI 300/400 시리즈** — ONNX Runtime GenAI를 통한 NPU 가속(하이브리드 NPU+iGPU 실행)
* **NVIDIA GPU** — CUDA 가속
* **Apple Silicon** — Metal 백엔드

Lemonade Server는 하드웨어를 자동 감지하여 최적의 백엔드를 선택합니다. 필요에 따라 백엔드를 수동으로 오버라이드할 수도 있습니다.

> **Why not just bind Lemonade Server to 0.0.0.0?**
>
> Lemonade Server를 모든 인터페이스(`0.0.0.0`)에 바인딩하면 네트워크에서 접근할 수 있지만, Lemonade Server는 원격 호출자를 위한 내장 인증을 제공하지 않습니다 — 포트 `13305`에 접근할 수 있는 모든 사람이 API를 호출할 수 있습니다. ISP가 CGNAT를 사용하는 경우, 애초에 전달할 안정적인 공개 IP가 없습니다. Tokios는 인바운드 포트를 열지 않고 범위 제한 `sk-tok-…` API 키를 추가합니다.

> **Why not use Tailscale or Cloudflare Tunnel?**
>
> Tailscale은 개인 접근을 잘 해결합니다 — 자체 디바이스가 비공개 메시 네트워크에 참여하여 안전하게 서로 접근할 수 있습니다. 하지만 개인 용도 이상에서는 문제가 있습니다: 모델을 호출해야 하는 팀원이나 SaaS 클라이언트가 먼저 tailnet에 참여해야 하며, 이는 공개 API 키 모델에 맞지 않습니다. Cloudflare Tunnel은 인바운드 포트 없이 Cloudflare의 엣지를 통해 트래픽을 라우팅하지만, 기본적으로 Cloudflare는 응답이 `text/event-stream` 콘텐츠 타입 헤더를 가지지 않는 한 스트리밍 대신 버퍼링하며, 프록시된 요청은 Cloudflare의 프록시 타임아웃(무료 티어에서 약 100초)의 영향을 받습니다 — 긴 생성은 스트리밍 중간에 끊길 수 있습니다.

> [!NOTE]
>
> 이 도구들을 비판하는 것은 아닙니다 — 다른 문제를 해결하고 있습니다(디바이스 메시 네트워킹, 엣지 프록싱). Tokios는 한 가지 목적으로 특별히 구축되었습니다: 로컬 모델 엔드포인트를 어디서든 호출할 수 있는 인증된 API로 변환하는 것.

## 사전 요구사항

시작하기 전에 다음이 있는지 확인하세요:

* **Lemonade Server 설치 완료** — 아래 [Lemonade Server 설치 방법](#how-to-install-lemonade-server) 참조
* **모델 다운로드 완료** — `lemonade pull <model>`을 사용하여 모델을 다운로드하세요
* **Tokios 커넥터** — 설정 중에 설치하게 됩니다

## Lemonade Server 설치 방법

Lemonade Server는 Windows, Linux, macOS 및 Docker용 설치 프로그램을 제공합니다. v10.1 기준으로, CLI 명령은 `lemonade`입니다(이전 `lemonade-server` CLI는 지원 중단).

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

설치 후 Lemonade Server가 실행 중인지 확인하세요:

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

서버 상태와 감지된 백엔드(Vulkan, ROCm, CUDA, Metal 또는 NPU)가 표시되어야 합니다.

## Lemonade Server로 모델 서빙하기

2개의 명령으로 모델을 다운로드하고 서빙하세요:

```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는 하드웨어를 자동 감지하여 최적의 백엔드를 선택합니다. 모델이 이제 `http://localhost:13305/v1`에서 서빙 중입니다.

> [!TIP]
>
> **AMD Ryzen AI에서 NPU 가속.** AMD Ryzen AI 300/400 시리즈 프로세서가 있는 경우, Lemonade Server는 NPU를 사용하여 추론할 수 있습니다. NPU 실행에 최적화된 ONNX 모델을 가져오세요:
>
> ```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 모델은 하이브리드 NPU+iGPU 실행을 사용하며 `-NPU` 접미사로 식별됩니다.

### 일반적인 Lemonade Server CLI 명령

| 명령 | 설명 |
| - | - |
| `lemonade pull <model>` | 모델 다운로드 |
| `lemonade run <model>` | 모델 서빙 |
| `lemonade run <model> --ctx-size 8192` | 사용자 정의 컨텍스트 크기로 서빙 |
| `lemonade list` | 사용 가능한 모델 목록 |
| `lemonade list --downloaded` | 다운로드된 모델 목록 |
| `lemonade status` | 서버 상태 및 감지된 백엔드 확인 |
| `lemonade status --json` | JSON 형식으로 상태 확인 |
| `lemonade bench <model>` | 모델 벤치마크 |

## 아웃바운드 전용 방식

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

Lemonade Server를 `127.0.0.1`에 유지하세요 — 루프백보다 넓게 바인딩하지 마세요. 모델을 가져오고 실행하세요:

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

기본 `http://127.0.0.1:13305`에서 수신 상태로 두세요.

**2. Pair the Tokios connector**

먼저 [tokios.com/console](https://tokios.com/console)에서 로그인하고, **Setup** 탭을 연 다음, **Start pairing**을 클릭하세요. Tokios는 약 15분 동안 유효한 일회용 **페어링 코드**(`TKS-XXXX-XXXX` 형태)를 표시합니다.

Lemonade Server가 실행 중인 머신에서 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
```

이미 `tokios-connector`가 설치되어 있나요? 코드를 직접 전달하세요:

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

콘솔로 돌아가서 기기를 **approve**하세요. **Setup** 또는 **Connectors** 탭에서 승인할 수 있습니다. 커넥터의 토큰은 승인 후 터널을 통해 전달됩니다 — 화면에 표시되지 않으며 파일에 붙여넣을 필요도 없습니다.

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

Lemonade Server는 `/v1`에서 OpenAI 호환 인터페이스를 노출하며, 이것이 Tokios가 통신하는 대상입니다. 기본 단일 모델 경로의 경우, 콘솔의 Setup 마법사가 자동으로 `http://127.0.0.1:13305/v1`을 업스트림으로 사용합니다. `tokios-connector.json` 설정을 통해 여러 모델을 서빙하는 경우, 업스트림 `BaseUrl`을 명시적으로 설정하세요:

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

전체 다중 모델 파일 형식은 [커넥터 설정](/ko/reference/connector-config.md)을 참조하세요.

**4. Register a deployment**

콘솔의 [Models](https://tokios.com/console/models) 탭에서 Lemonade Server 모델을 등록하고 **공개 이름**을 선택하세요 — 예를 들어 `qwen3-tunnel`. 이 공개 이름이 클라이언트가 `model` 필드에 보내는 값이며, Lemonade의 로컬 모델 ID가 아닙니다.

**5. Create an API key**

콘솔의 [Keys](https://tokios.com/console/keys) 탭에서 **Create key**를 클릭하세요. 선택적으로 모델 이름 패턴(쉼표로 구분된 글롭, 모두는 `*`)으로 특정 배포에만 범위를 제한할 수 있습니다. `sk-tok-…` 키를 지금 복사하세요 — 한 번만 표시됩니다.

## 어디서든 사용하기

배포 이름과 API 키가 있으면, 모든 OpenAI 또는 Anthropic 호환 클라이언트가 Lemonade Server 모델에 접근할 수 있습니다 — 다른 머신, 팀원의 노트북 또는 호스팅 에이전트에서.

```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]
>
> 요청의 `model` 필드는 항상 등록된 **배포** 이름(위의 `qwen3-tunnel`)이며, Lemonade의 로컬 모델 ID가 아닙니다. 세션 간 환경 변수를 유지하려면 [Use Claude Code](/ko/guides/claude-code.md)를 참조하세요.

## AMD NPU 지원이란

AMD Ryzen AI 300/400 시리즈 프로세서에는 AI 워크로드를 위한 전용 Neural Processing Unit(NPU)이 포함되어 있습니다. Lemonade Server는 하이브리드 NPU+iGPU 실행을 사용하여 AMD NPU에서 추론을 가속하는 유일한 로컬 LLM 서버입니다.

### NPU 가속 작동 방식

* **모델 형식**: NPU 최적화 모델은 ONNX 형식을 사용하며(`-NPU` 접미사로 식별, 예: `Llama-3.2-1B-Instruct-NPU`)
* **실행**: Lemonade Server는 OnnxRuntime GenAI를 사용하여 NPU와 iGPU 간에 추론을 분할합니다
* **백엔드**: NPU 백엔드는 자동입니다 — Lemonade Server가 Ryzen AI 프로세서를 감지하고 NPU 최적화 모델을 실행할 때 NPU 실행을 선택합니다
* **성능**: NPU 가속은 CPU와 GPU의 작업을 오프로드하여 전력 소비를 줄이고 다른 작업을 위한 리소스를 확보합니다

### 어떤 AMD 프로세서가 NPU 추론을 지원하는가

| 프로세서 시리즈 | NPU 지원 | 백엔드 |
| - | - | - |
| AMD Ryzen AI 300 시리즈 (Strix Point) | 예 | ONNX를 통한 NPU |
| AMD Ryzen AI 400 시리즈 | 예 | ONNX를 통한 NPU |
| AMD Ryzen AI MAX+ (Strix Halo) | NPU 없음, 하지만 강력한 iGPU | ROCm/vLLM 또는 Vulkan |
| AMD Ryzen 7000/8000 시리즈 | NPU 없음 | Vulkan (llama.cpp) |

> [!NOTE]
>
> NPU 지원에는 AMD Ryzen AI Software 드라이버가 필요합니다. Lemonade Server에 필요한 런타임이 번들되어 있지만, 시스템에 최신 AMD Adrenalin 드라이버가 설치되어 있는지 확인하세요.

## Lemonade Server와 다른 백엔드 비교

Lemonade Server는 Tokios가 지원하는 여러 백엔드 중 하나입니다. 비교는 다음과 같습니다:

| 기능 | Lemonade Server | Ollama | llama.cpp | vLLM |
| - | - | - | - | - |
| **AMD NPU 지원** | 예 (Ryzen AI 300/400) | 아니오 | 아니오 | 아니오 |
| **백엔드 자동 감지** | 예 (Vulkan/ROCm/CUDA/Metal) | 수동 | 수동 | 수동 |
| **설정 복잡도** | 낮음 (설치 프로그램) | 낮음 (명령 하나) | 중간 (빌드) | 높음 (Python GPU 서버) |
| **모델 형식** | GGUF, ONNX, FLM | GGUF | GGUF | Hugging Face |
| **최적 용도** | AMD 하드웨어; 크로스 플랫폼 | 초보자; 가장 빠른 시작 | 수동 GGUF 서빙 | 고처리량 GPU 서빙 |

> [!TIP]
>
> AMD 하드웨어(특히 NPU가 있는 Ryzen AI)가 있거나 백엔드를 자동 감지하는 크로스 플랫폼 서버를 원한다면 Lemonade Server가 좋은 선택입니다. 어떤 하드웨어에서든 가장 빠른 시작을 원한다면, [Ollama](/ko/guides/ollama-remote-access.md)가 여전히 가장 쉽습니다.

## FAQ

> **What port does Lemonade Server use?**
>
> Lemonade Server는 기본적으로 포트 **13305**에서 수신하며, `127.0.0.1`(localhost만)에 바인딩됩니다. OpenAI 호환 API는 `http://localhost:13305/v1`에 있습니다. `lemonade status` 또는 `curl http://localhost:13305/v1/models`로 Lemonade Server가 실행 중인지 확인할 수 있습니다.

> **How do I know which backend Lemonade Server is using?**
>
> 먼저 `lemonade status`를 실행하여 감지된 백엔드(Vulkan, ROCm, CUDA, Metal 또는 NPU)를 확인하세요. Lemonade Server는 하드웨어를 자동 감지하여 최적의 백엔드를 선택합니다. `lemonade status --json`을 사용하여 기계가 읽을 수 있는 출력 형식으로 확인할 수도 있습니다.

> **Does Lemonade Server support AMD NPU?**
>
> 예. Lemonade Server는 AMD Ryzen AI 300/400 시리즈 NPU에서 추론을 가속하는 유일한 로컬 LLM 서버입니다. `lemonade pull <model>-NPU`로 NPU 최적화 모델을 가져오고 `lemonade run <model>-NPU`로 실행하세요. NPU 백엔드는 OnnxRuntime GenAI를 통한 하이브리드 NPU+iGPU 실행을 사용합니다.

> **Can I use Lemonade Server with NVIDIA GPUs?**
>
> 예. Lemonade Server는 NVIDIA GPU를 자동 감지하고 CUDA 백엔드를 사용합니다. Vulkan, ROCm, CUDA 또는 Metal을 지원하는 모든 하드웨어에서 작동합니다 — AMD, NVIDIA 및 Apple Silicon 모두 지원됩니다.

> **How do I expose Lemonade Server to my network?**
>
> Lemonade Server를 직접 노출하지 마세요 — 대신 Tokios를 사용하세요. Tokios는 인바운드 포트를 열지 않고 인증된 원격 접근을 추가합니다. 전체 안내는 [위의 설정 단계](#the-outbound-only-way)를 참조하세요.

> **Does streaming work?**
>
> 예. `"stream": true`를 설정하면 Tokios는 호출한 API 인터페이스에 따라 OpenAI 또는 Anthropic 형식의 표준 서버 전송 이벤트(SSE)를 반환합니다.

> **Can I share access with teammates without exposing Lemonade Server directly?**
>
> 예. 팀원마다 별도의 `sk-tok-…` 키를 [Keys](https://tokios.com/console/keys) 탭에서 생성하고, 각 키가 필요한 배포에만 범위를 제한하세요. 키를 취소하면 인증이 즉시 중지되므로, Lemonade Server나 커넥터를 건드리지 않고 접근을 차단할 수 있습니다.

> **Can I expose more than 1 Lemonade Server model?**
>
> 예. [Models](https://tokios.com/console/models) 탭에서 추가 배포를 등록하거나, `tokios-connector.json` 설정 파일을 사용하여 단일 커넥터에 대한 여러 업스트림과 라우트를 정의하세요. [커넥터 설정](/ko/reference/connector-config.md)을 참조하세요.

> **How do I update Lemonade Server?**
>
> Linux에서 `sudo apt update && sudo apt upgrade lemonade-server`(APT) 또는 `sudo snap refresh lemonade-server`(Snap)를 실행하세요. Windows에서는 [릴리스 페이지](https://github.com/lemonade-sdk/lemonade/releases)에서 최신 MSI 설치 프로그램을 다운로드하세요.

> **What model architectures does the NPU support?**
>
> NPU는 ONNX 실행에 최적화된 특정 모델 아키텍처를 지원합니다. `lemonade list`를 실행하여 사용 가능한 NPU 모델을 확인하세요(`-NPU` 접미사로 식별). 모든 모델이 NPU와 호환되는 것은 아닙니다 — GGUF 모델은 GPU/CPU 백엔드에서 실행됩니다. NPU 지원 아키텍처의 전체 목록은 [Lemonade FAQ](https://lemonade-server.ai/docs/guide/faq/)를 참조하세요.

## 모델은 머신을 떠나지 않습니다 — 엔드포인트는 어디서든 작동합니다

Lemonade Server는 오늘과 동일하게 localhost에서 계속 작동하며, 인바운드 포트도 노출된 API도 없습니다. 커넥터는 아웃바운드 연결만 합니다. 그 이후의 모든 것 — 인증, 라우팅, 스트리밍 — 은 키를 부여하기로 선택한 머신, 팀원 또는 에이전트에서 호출할 수 있는 하나의 엔드포인트입니다.

> **[빠른 시작](/ko/quickstart.md)**
>
> 커넥터를 페어링하고 첫 모델을 끝까지 등록하세요.

> **[API 키](/ko/setup/api-keys.md)**
>
> 팀원 및 에이전트를 위한 `sk-tok-…` 키를 생성, 범위 제한 및 회전하세요.

> **[Strix Halo 설정](/ko/use-cases/strix-halo.md)**
>
> AMD Strix Halo 박스를 Lemonade Server로 모델 엔드포인트로 변환하세요.

> **[지원되는 백엔드](/ko/setup/supported-backends.md)**
>
> Tokios가 지원하는 모든 백엔드를 확인하세요 — Ollama, llama.cpp, vLLM, LM Studio 등.

## 출처

* [Lemonade SDK GitHub 저장소](https://github.com/lemonade-sdk/lemonade)
* [Lemonade Server 공식 문서](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 문서](https://lemonade-server.ai/docs/guide/cli/)


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