어디서든 안전하게 vLLM 서버를 활용하세요

기본적으로 vLLM의 OpenAI 호환 서버는 http://127.0.0.1:8000/v1 포트에서 작동합니다. 하지만 범위를 넓게 설정하거나 포트 포워딩을 하지 않는 한 다른 기기에서는 접근이 불가능합니다. vLLM에는 --api-key 플래그도 제공되지만 공식 문서에서는 이를 유일한 보호 수단으로 사용하지 말라고 명시하고 있습니다. 따라서 vLLM은 로컬호스트에서 그대로 실행하고 Tokios 커넥터를 병행 운용하는 것이 좋습니다. 이 커넥터가 https://api.tokios.com으로 연결되면 여러분의 도구나 팀원, 에이전트들은 어디서든 인증된 단일 엔드포인트를 통해 접근할 수 있습니다.

고급 런타임 환경. vLLM은 높은 처리량을 목표로 하는 Python 기반 GPU 서버로, 일반 데스크톱 도구에 비해 설정 및 튜닝이 더 필요합니다. 모델 배포를 가장 간편하게 하고 싶다면 Ollama나 LM Studio부터 시작하는 것이 좋습니다. Tokios는 이들 역시 동일한 방식으로 연결할 수 있습니다.

vLLM의 `--api-key` 기능만으로는 충분하지 않습니다

vllm serve --api-key <key>에서는 요청 시 베어러 토큰이 필수이며 이는 기본적인 보안 수단입니다. 하지만 vLLM의 보안 문서에 따르면 범위 제한이 존재합니다. 즉, 해당 키는 오직 /v1 경로에 대해서만 인증을 수행하며 동일 서버 내 다른 엔드포인트들은 보호되지 않습니다. vLLM 측에서는 의도된 엔드포인트만 허용하도록 리버스 프록시를 배치할 것을 권장하고 있습니다. 따라서 --api-key만으로는 보안 경계를 형성하기 어렵습니다.

이는 vLLM 자체에 대한 비판이 아닙니다. --api-key은 지정된 경로에 대해서는 명시된 기능을 충실히 수행합니다. 다만 “어디서든 인증 후 서버로 요청을 라우팅하는” 기능은 별개의 문제입니다. Tokios는 바로 이 목적에 맞게 설계되었으며 vLLM 호스트에 인바운드 포트를 전혀 열지 않으므로 허용 목록을 관리할 대상 자체가 존재하지 않습니다.

아웃바운드 전용 방식 활용하기

평소처럼 vLLM을 로컬에서 실행합니다

vLLM을 127.0.0.1에서 계속 실행하되 루프백 범위 이상으로 설정하지 마세요. 그런 다음 OpenAI 호환 서버를 기동합니다:

vllm serve mistralai/Mistral-7B-Instruct-v0.2

기본 설정인 http://127.0.0.1:8000 포트에서 계속 수신 대기하도록 둡니다.

Tokios 커넥터를 연결합니다

먼저 tokios.com/console에 로그인하고 Setup 탭을 열어 Start pairing을 클릭하세요. Tokios가 일회성 페어링 코드인 TKS-XXXX-XXXX를 표시하며, 약 15분 동안 유효합니다.vLLM이 실행 중인 머신에서 사용 중인 OS에 맞는 설치 명령어를 실행하세요.

Windows

irm https://tokios.com/downloads/install/windows | iex; tokios-install -Code 'TKS-XXXX-XXXX'

macOS

curl -fsSL https://tokios.com/downloads/install/macos | sh -s -- --code TKS-XXXX-XXXX

Linux

curl -fsSL https://tokios.com/downloads/install/linux | sh -s -- --code TKS-XXXX-XXXX

이미 tokios-connector이 설치되어 있다면 코드를 직접 입력해주시면 됩니다.

tokios-connector TKS-XXXX-XXXX

콘솔로 돌아가서 기기를 approve합니다. Setup 또는 Connectors 탭에서 승인할 수 있습니다. 승인이 완료되면 커넥터의 토큰이 터널을 통해 전달되며, 화면에 표시되거나 파일에 직접 입력하는 일은 없습니다.

커넥터가 vLLM의 /v1 API를 가리키도록 설정합니다

vLLM의 OpenAI 호환 서버는 Tokios가 요구하는 형식을 이미 지원합니다. 단일 모델을 사용할 경우 콘솔의 설정 마법사가 자동으로 http://127.0.0.1:8000/v1을 업스트림 모델 ID로 지정합니다. 여러 모델을 tokios-connector.json 설정으로 제공할 때는 업스트림 BaseUrl을 직접 지정해주어야 합니다.

{
  "Upstream": {
    "BaseUrl": "http://127.0.0.1:8000/v1"
  }
}

다중 모델용 파일 형식에 관해서는 커넥터 설정을 참고하세요.

배포 항목을 등록합니다

먼저 Models 탭에서 vLLM 모델을 등록하고 public name을 선택하세요. 예를 들어 mistral-tunnel처럼 지정합니다. 클라이언트가 model 필드에 전송하는 것은 vLLM의 로컬 모델 ID가 아닌 이 공개 이름입니다.

API 키를 생성합니다

다음으로 Keys 탭에서 Create key를 클릭하세요. 필요하면 모델 이름 패턴(쉼표로 구분된 글롭, 전체는 *)으로 특정 배포에만 범위를 지정할 수 있습니다. sk-tok-… 키는 지금 바로 복사하세요. 한 번만 표시됩니다.

LoRA 어댑터를 서비스하시겠습니까? --enable-lora 및 --lora-modules 매개변수를 사용해 vLLM을 실행하면 하나의 프로세스에서 여러 어댑터를 서비스할 수 있으며, 요청 시 model 필드에 각 어댑터의 이름을 지정하면 됩니다. 다른 모델을 등록할 때와 마찬가지로 각 어댑터를 고유한 공개 이름을 가진 별도의 Tokios 배포 항목으로 등록해야 합니다. 게이트웨이가 공개 배포 이름을 어떻게 업스트림 모델 ID에 매핑하는지 알아보려면 모델 라우팅 문서를 참고하시기 바랍니다.

어디서든 사용 가능합니다

배포 이름과 API 키만 확보하면 OpenAI나 Anthropic과 호환되는 모든 클라이언트가 다른 기기나 팀원의 노트북, 혹은 호스팅된 에이전트에서도 귀하의 vLLM 모델에 접근할 수 있습니다.

curl https://api.tokios.com/v1/chat/completions \
  -H "Authorization: Bearer sk-tok-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistral-tunnel",
    "stream": true,
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

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="mistral-tunnel",
    messages=[{"role": "user", "content": "Hello!"}],
    stream=True,
)

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

export ANTHROPIC_BASE_URL=https://api.tokios.com
export ANTHROPIC_API_KEY=sk-tok-YOUR_KEY
claude --model mistral-tunnel

여기서 model 필드는 항상 등록된 deployment 이름(위의 mistral-tunnel)이며 vLLM의 로컬 모델 ID가 아닙니다. 세션 간 환경 변수를 유지하는 방법은 Claude Code 사용하기를 참고하세요.

자주 묻는 질문

스트리밍 기능도 사용 가능한가요?

물론입니다. "stream": true 매개변수를 설정하면 Tokios는 호출된 API 종류에 따라 OpenAI 또는 Anthropic 형식의 표준 서버 전송 이벤트(SSE)를 반환합니다.

vLLM을 통해 하나 이상의 모델이나 어댑터를 서비스할 수 있나요?

가능합니다. Models 탭에서 추가 배포 항목을 등록하거나 tokios-connector.json 설정 파일을 활용해 단일 커넥터에 여러 업스트림 모델과 경로를 정의할 수 있습니다. 이 방식은 여러 vLLM 프로세스를 운영하거나 --lora-modules 매개변수를 통해 하나의 프로세스에서 여러 LoRA 어댑터를 서비스할 때 유용합니다. 자세한 내용은 Connector config 문서를 참고하십시오.

vLLM의 --api-key 플래그도 여전히 필요한가요?

커넥터와 vLLM 간의 루프백 연결 보안을 강화하기 위해 해당 플래그를 계속 사용할 수는 있으나, Tokios를 통해 접근하는 클라이언트를 인증하는 수단은 아닙니다. https://api.tokios.com으로 전송되는 클라이언트 요청은 sk-tok-… API 키로 인증되며, 커넥터 자체만이 127.0.0.1:8000에 접근할 권한을 갖습니다.

vLLM을 직접 노출하지 않고도 팀원들과 접근 권한을 공유할 수 있나요?

네. 팀원별로 별도의 sk-tok-… 키를 Keys 탭에서 생성하고 각 키의 범위를 필요한 배포로만 지정하세요. 키를 취소하면 즉시 인증이 중단되므로 vLLM이나 커넥터를 건드리지 않고도 접근을 차단할 수 있습니다.

사용자의 모델은 절대 외부로 유출되지 않으며, 생성된 엔드포인트는 어디서든 사용 가능합니다.

vLLM은 현재와 동일하게 로컬호스트에서 작동하며, /v1 외에는 어떠한 인바운드 포트나 엔드포인트도 노출되지 않습니다. 커넥터 역시 아웃바운드 연결만 수행합니다. 그 이후의 인증, 라우팅, 스트리밍 등 모든 기능은 키를 부여한 어떤 기기나 팀원, 에이전트에서도 호출 가능한 단일 엔드포인트로 처리됩니다.

빠른 시작 가이드

커넥터를 연동하고 첫 번째 모델 엔드포인트를 등록해보세요.

API 키 관리

팀원 및 에이전트용 sk-tok-… API 키를 생성하고 범위를 지정하며 주기적으로 갱신할 수 있습니다.

하드웨어와 호환성

런타임 서빙과 연결

클라이언트 또는 앱 연결

비교

어디서든 안전하게 vLLM 서버를 활용하세요

vLLM의 `--api-key` 기능만으로는 충분하지 않습니다

아웃바운드 전용 방식 활용하기

어디서든 사용 가능합니다

자주 묻는 질문

사용자의 모델은 절대 외부로 유출되지 않으며, 생성된 엔드포인트는 어디서든 사용 가능합니다.

빠른 시작 가이드

API 키 관리

​vLLM의 --api-key 기능만으로는 충분하지 않습니다

​아웃바운드 전용 방식 활용하기

​어디서든 사용 가능합니다

​자주 묻는 질문

​사용자의 모델은 절대 외부로 유출되지 않으며, 생성된 엔드포인트는 어디서든 사용 가능합니다.

빠른 시작 가이드

API 키 관리

vLLM의 `--api-key` 기능만으로는 충분하지 않습니다

아웃바운드 전용 방식 활용하기

어디서든 사용 가능합니다

자주 묻는 질문

사용자의 모델은 절대 외부로 유출되지 않으며, 생성된 엔드포인트는 어디서든 사용 가능합니다.