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

# 어디서든 안전하게 MLX-LM Server 사용하기

> Apple Silicon의 MLX-LM Server에 어디서든 접근하십시오. Tokios 커넥터와 API 키 인증으로 안전한 원격 접속을 설정하고 5분 만에 서빙을 시작하십시오.

기본적으로 `mlx_lm.server`는 `http://127.0.0.1:8080/v1`에서 수신 대기합니다. 다른 머신에서 접근하려면 더 넓은 범위로 바인딩하거나 포트를 포워딩하지 않는 한 도달할 수 없습니다. MLX-LM Server에는 내장 인증 기능이 없습니다. 포트 `8080`에 접근할 수 있는 모든 것이 인증 없이 API를 호출할 수 있습니다. MLX-LM Server를 로컬호스트에 유지하고 대신 Tokios 커넥터를 바로 옆에서 실행하세요. 커넥터가 `https://api.tokios.com`으로 아웃바운드 연결을 수행하고, 여러분의 도구, 팀원, 또는 에이전트는 어디서든 인증된 엔드포인트 하나를 호출합니다.

> [!NOTE]
>
> 최종 확인: 2026-10-14. MLX-LM Server는 Apple의 ml-explore 팀이 만든 [`mlx-lm`](https://github.com/ml-explore/mlx-lm) Python 패키지에 포함되어 제공됩니다. 이 가이드는 현재 릴리스를 다룹니다.

> [!TIP]
>
> **Apple Silicon 네이티브.** MLX-LM Server는 Apple Silicon용 레퍼런스 추론 서버입니다. MLX 프레임워크의 통합 메모리 아키텍처와 제로카피 데이터 경로를 사용합니다. 모델 가중치가 CPU 및 GPU와 동일한 메모리 풀에 존재하므로 별도의 VRAM을 관리할 필요가 없습니다. M5 칩에서는 Neural Accelerator가 최대 4x 빠른 프롬프트 처리를 제공합니다(M4 대비).

## Apple Silicon 네이티브 추론이란

MLX-LM Server는 Tokios가 지원하는 다른 백엔드와 다릅니다. Apple Silicon Mac(M1 이상)에서만 실행되며, 모든 Apple Silicon 칩이 공유하는 통합 메모리 아키텍처를 직접 활용합니다.

| 기능 | MLX-LM Server | llama.cpp on Mac | vLLM |
| - | - | - | - |
| 하드웨어 | Apple Silicon 전용 | 크로스 플랫폼 (CPU + GPU) | NVIDIA GPU (CUDA) |
| 메모리 모델 | 통합 메모리, 제로카피 | Metal을 통한 통합 메모리 | 별도 VRAM |
| Neural Accelerators (ANE) | 예 — M5에서 자동 | 아니오 | 아니오 |
| 설치 | `pip install mlx-lm` | 소스에서 빌드 또는 사전 빌드 바이너리 | `pip install vllm` + CUDA |
| 양자화 | 4비트, 8비트, BF16 | GGUF (Q2\_K \~ Q8\_0) | AWQ, GPTQ, FP16, BF16 |
| M5에서의 프롬프트 처리 | 최대 4x vs M4 | 기준선 | N/A |

MLX는 통합 메모리를 사용하므로, 192 GB RAM이 탑재된 Mac Studio는 다른 플랫폼에서 필요한 멀티 GPU 설정 없이도 70B 모델을 전체 정밀도로 제공할 수 있습니다. VRAM 경계가 없습니다. 모델, KV 캐시, 작업 메모리가 모두 동일한 풀을 공유합니다.

## MLX-LM Server의 인증은 기본적으로 꺼져 있습니다

`mlx_lm.server`는 포트 `8080`에서 OpenAI 호환 HTTP 서버를 시작합니다. 실행하면 포트에 접근할 수 있는 누구나 요청을 수락합니다. 인증이 필요 없습니다.

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
mlx_lm.server --model mlx-community/Qwen-3.5-4B-8bit
```

MLX-LM Server에는 인증 계층이 포함되어 있지 않습니다. [공식 문서](https://github.com/ml-explore/mlx-lm/blob/main/mlx_lm/SERVER.md)에서도 리버스 프록시 없이 프로덕션에 사용하는 것은 권장하지 않는다고 명시되어 있습니다. 로컬 전용 사용에는 문제없지만, `--host 0.0.0.0`, 포트 포워딩, 또는 터널을 통해 루프백 외부로 포트를 노출하면 접근 가능한 모든 사람에게 인증되지 않은 API 접근이 허용됩니다.

> [!NOTE]
>
> 이것이 MLX-LM Server의 단점은 아닙니다. Apple Silicon 네이티브 경량 추론 서버이며, 인증을 외부 프록시에 맡기는 것이 서버를 단순하게 유지합니다. Tokios는 다른 문제를 해결하기 위해 만들어졌습니다. 로컬 엔드포인트를 인바운드 포트를 열거나 TLS를 직접 구성하지 않고도 어디서든 호출할 수 있는 인증된 API로 변환하는 것입니다.

## 아웃바운드 전용 방식

**1. Install MLX-LM and start the server locally**

MLX-LM Server는 Apple Silicon Mac(M1 이상)에 macOS 14.0 (Sonoma) 이상이 설치되어 있어야 합니다. 패키지를 설치하고 서버를 시작하세요.

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
pip install mlx-lm
mlx_lm.server --model mlx-community/Qwen-3.5-4B-8bit
```

서버는 첫 사용 시 [mlx-community](https://huggingface.co/mlx-community)에서 모델을 다운로드하고 `http://127.0.0.1:8080`에서 수신 대기합니다. 기본값 `127.0.0.1`을 유지하세요. `--host 0.0.0.0`을 전달하지 마세요.

> [!TIP]
>
> **양자화 선택.** mlx-community의 모델은 4비트(기본값, 가장 작음), 8비트, BF16(전체 정밀도) 변형으로 제공됩니다. 70B 모델의 경우 4비트에서 약 35 GB의 통합 메모리가 필요합니다. 8비트에서는 약 70 GB, BF16에서는 약 140 GB입니다. Mac의 메모리에 맞는 양자화를 선택하세요.

**2. Pair the Tokios connector**

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

MLX-LM Server가 실행 중인 Mac에서 macOS 설치 원라이너를 실행하세요.

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
curl -fsSL https://tokios.com/downloads/install/macos | 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 MLX-LM Server's /v1 API**

MLX-LM Server는 이미 Tokios가 기대하는 OpenAI Chat Completions 인터페이스를 지원합니다. 기본 단일 모델 경로의 경우, 콘솔의 Setup 마법사에서 `http://127.0.0.1:8080/v1`을 업스트림으로 자동 사용합니다. `tokios-connector.json` 설정을 통해 여러 모델을 제공하는 경우, 업스트림 `BaseUrl`을 명시적으로 설정하세요.

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

전체 멀티 모델 파일 형식은 [Connector config](/ko/reference/connector-config.md)를 참조하세요.

**4. Register a deployment**

먼저 [Models](https://tokios.com/console/models) 탭에서 MLX-LM 모델을 등록하고 **public name**을 선택하세요. 예를 들어 `mlx-qwen-tunnel`입니다. 클라이언트가 `model` 필드에 전송하는 것은 HuggingFace 모델 id가 아닌 이 public name입니다.

**5. Create an API key**

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

## 어디서든 사용

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

```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": "mlx-qwen-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="mlx-qwen-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 mlx-qwen-tunnel
```

> [!TIP]
>
> 여기서 `model` 필드는 항상 등록된 **deployment** 이름(위 예시의 `mlx-qwen-tunnel`)이며, HuggingFace 모델 id가 아닙니다. 세션 간 환경 변수를 유지하려면 [Use Claude Code](/ko/guides/claude-code.md)를 참조하세요.

## 서버 설정 레퍼런스

MLX-LM Server는 추론 튜닝을 위한 여러 플래그를 제공합니다. 가장 유용한 것들:

| 플래그 | 기본값 | 용도 |
| - | - | - |
| `--model` | (필수) | HuggingFace 모델 id 또는 로컬 경로 |
| `--host` | `127.0.0.1` | 바인딩 주소 — Tokios의 경우 `127.0.0.1`을 유지 |
| `--port` | `8080` | 수신 포트 |
| `--adapter-path` | — | 파인튜닝된 모델 서빙을 위한 LoRA 어댑터 경로 |
| `--max-tokens` | `512` | 생성당 기본 최대 토큰 수 |
| `--temp` | `0.0` | 샘플링 온도 |
| `--top-p` | `1.0` | Top-p (nucleus) 샘플링 |
| `--top-k` | `0` | Top-k 샘플링 (0 = 비활성화) |
| `--kv-bits` | — | KV 캐시 양자화 비트 (메모리 감소) |
| `--kv-group-size` | `64` | KV 캐시 양자화의 그룹 크기 |
| `--prefill-step-size` | `2048` | 긴 컨텍스트를 위한 prefill 청크 크기 |
| `--draft-model` | — | 추측적 디코딩을 위한 모델 |
| `--num-draft-tokens` | `3` | 추측적 디코딩 스텝당 드래프트 토큰 수 |
| `--prompt-cache-size` | `10` | 캐시할 프롬프트 수 |
| `--decode-concurrency` | `32` | 최대 동시 디코드 작업 수 |
| `--prompt-concurrency` | `8` | 최대 동시 프롬프트 작업 수 |
| `--trust-remote-code` | `false` | HuggingFace 저장소의 원격 코드 신뢰 |

서버는 다음 엔드포인트를 노출합니다.

| 엔드포인트 | 용도 |
| - | - |
| `/v1/chat/completions` | Chat Completions (OpenAI 호환) |
| `/v1/completions` | Text Completions (OpenAI 호환) |
| `/v1/models` | 로드된 모델 목록 |
| `/health` | 헬스 체크 |

> [!TIP]
>
> **추측적 디코딩**은 대규모 모델에서 생성 속도를 2-3x 높일 수 있습니다. `--draft-model`에 동일한 패밀리의 더 작은 모델을 전달하세요. 예를 들어, 4B 모델을 드래프트로 사용하여 32B 모델의 속도를 높일 수 있습니다. MLX-LM Server는 드래프트 토큰을 병렬로 검증하고 불일치만 다시 계산합니다.

## FAQ

> **What are the prerequisites for MLX-LM Server?**
>
> Apple Silicon Mac(M1, M2, M3, M4, M5)에 macOS 14.0 (Sonoma) 이상, Python 3.9 이상, 그리고 `pip` 또는 `conda`가 필요합니다. `pip install mlx-lm`으로 설치하세요. MLX 프레임워크는 GPU 가속을 위해 Metal을 사용하고 모델 가중치에 통합 메모리를 사용합니다. 별도의 GPU 드라이버이나 CUDA 툴킷이 필요 없습니다.

> **How do I install MLX-LM Server?**
>
> Python 패키지를 `pip install mlx-lm`(또는 `conda install -c conda-forge mlx-lm`)로 설치하세요. 그런 다음 `mlx_lm.server --model <model-id>`로 서버를 시작합니다. 모델은 첫 사용 시 HuggingFace에서 다운로드됩니다. [mlx-community](https://huggingface.co/mlx-community) 조직의 모델은 사전에 MLX 형식으로 변환되어 바로 사용할 수 있습니다.

> **What port does MLX-LM Server use?**
>
> MLX-LM Server는 기본적으로 포트 **8080**에서 수신 대기하며 `127.0.0.1`(로컬호스트 전용)에 바인딩됩니다. `--port`로 포트를 변경하고 `--host`로 바인딩 주소를 변경할 수 있습니다. Tokios의 경우 기본값을 유지하세요. 커넥터는 `http://127.0.0.1:8080/v1`에서 서버에 접근합니다.

> **Does MLX-LM Server support streaming?**
>
> 예. 요청 본문에 `"stream": true`를 설정하면 서버가 표준 SSE(Server-Sent Events)를 반환합니다. Tokios를 통하면 스트리밍이 엔드투엔드로 작동합니다. `"stream": true`를 설정하면 Tokios는 호출한 API 인터페이스에 따라 OpenAI 또는 Anthropic 형식으로 SSE를 반환합니다.

> **Does MLX-LM Server support tool calling?**
>
> 예. MLX-LM Server는 구조화된 도구 호출을 지원합니다. 도구 정의가 포함된 채팅 템플릿을 지원하는 모델을 사용하세요. [mlx-community](https://huggingface.co/mlx-community)의 Qwen 3.5나 Llama 3와 같은 모델에는 필요한 채팅 템플릿이 포함되어 있습니다. 요청의 OpenAI 호환 `tools` 필드에 도구를 전달하세요.

> **Can I use LoRA adapters with MLX-LM Server?**
>
> 예. LoRA 어댑터 가중치가 포함된 디렉토리를 가리키도록 `--adapter-path`를 전달하세요. `mlx_lm.lora`(동일 패키지에 포함)로 어댑터를 파인튜닝한 다음, 어댑터가 오버레이된 기본 모델을 서빙합니다. 어댑터를 자체적인 public name을 가진 별도의 Tokios 배포로 등록하세요.

> **How does MLX-LM Server compare to llama.cpp on Apple Silicon?**
>
> 둘 다 Apple Silicon에서 통합 메모리를 사용합니다. MLX-LM Server는 Apple 네이티브 경로입니다. Metal GPU 가속을 직접 사용하며, M5 칩에서는 Neural Accelerator를 활용하여 최대 4x 빠른 프롬프트 처리를 제공합니다. llama.cpp는 크로스 플랫폼이며 더 다양한 양자화 형식(GGUF 변형)을 지원합니다. 순수 Apple Silicon 성능에서는 MLX-LM Server가 M 시리즈 칩에서 llama.cpp와 경쟁하거나 약간 앞섭니다.

> **Can I serve more than one model?**
>
> 예. 서로 다른 포트에서 여러 `mlx_lm.server` 프로세스를 실행하거나, [Models](https://tokios.com/console/models) 탭에서 추가 배포를 등록하세요. `tokios-connector.json` 설정 파일을 사용하여 단일 커넥터에 대해 여러 업스트림과 라우트를 정의할 수 있습니다. 전체 멀티 모델 파일 형식은 [Connector config](/ko/reference/connector-config.md)를 참조하세요.

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

> **What models work with MLX-LM Server?**
>
> HuggingFace에서 MLX 형식으로 변환된 모든 모델입니다. [mlx-community](https://huggingface.co/mlx-community) 조직은 Llama, Qwen, Mistral, Gemma, Phi 등 인기 모델의 사전 변환 버전을 4비트, 8비트, BF16 양자화로 유지하고 있습니다. `mlx_lm.convert`로 직접 모델을 변환할 수도 있습니다.

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

MLX-LM Server는 인바운드 포트 없이, 노출된 API 없이 로컬호스트에서 지금과 동일하게 계속 작동합니다. 커넥터는 아웃바운드 연결만 수행합니다. 그 이후의 모든 것 — 인증, 라우팅, 스트리밍 — 은 키를 부여한 머신, 팀원, 또는 에이전트 어디서든 호출할 수 있는 엔드포인트 하나입니다.

> **[Quickstart](/ko/quickstart.md)**
>
> 커넥터를 페어링하고 첫 모델을 엔드투엔드로 등록하세요.

> **[API keys](/ko/setup/api-keys.md)**
>
> 팀원과 에이전트를 위한 `sk-tok-...` 키를 생성, 범위 지정, 로테이션하세요.

> **[Mac Studio setup](/ko/use-cases/mac-studio.md)**
>
> Mac Studio를 70B+ 모델을 위한 통합 메모리가 탑재된 헤드리스 추론 박스로 변환하세요.

## Sources

* [ml-explore/mlx-lm](https://github.com/ml-explore/mlx-lm) — MLX-LM Python 패키지 및 서버의 공식 저장소
* [MLX-LM Server documentation (SERVER.md)](https://github.com/ml-explore/mlx-lm/blob/main/mlx_lm/SERVER.md) — 서버 API 레퍼런스 및 지원 엔드포인트
* [MLX framework](https://github.com/ml-explore/mlx) — Apple Silicon용 기본 배열 프레임워크
* [mlx-framework.org](https://mlx-framework.org/) — MLX 프레임워크 개요 및 생태계 링크
* [mlx-community on HuggingFace](https://huggingface.co/mlx-community) — 서빙 준비가 완료된 사전 변환 MLX 모델
* [Exploring LLMs with MLX and the Neural Accelerators in M5](https://machinelearning.apple.com/research/exploring-llms-mlx-m5) — M5 ANE 성능에 대한 Apple Machine Learning Research
* [Run local agentic AI on the Mac using MLX (WWDC26)](https://developer.apple.com/videos/play/wwdc2026/232/) — MLX-LM Server, 연속 배치팅, 분산 추론에 대한 Apple 세션


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