어디서든 안전하게 llama.cpp 서버를 활용하세요

기본적으로 llama-server은 http://127.0.0.1:8080/v1에서 수신 대기합니다. 범위를 넓게 설정하거나 포트 포워딩을 하지 않는 한 다른 기기에서는 접근이 불가능합니다. llama-server에는 선택 가능한 --api-key 플래그가 있지만 기본값은 비활성화 상태이며 TLS 설정 역시 사용자 책임입니다. 대신 llama-server을 로컬호스트에서 실행한 뒤 Tokios 커넥터를 병행 운용하세요. 이 커넥터가 https://api.tokios.com으로 연결되면 여러분의 도구나 팀원, 에이전트들이 어디서든 인증된 단일 엔드포인트를 통해 접근할 수 있습니다.

`llama-server`의 인증 기능은 선택 사항이며 기본값은 비활성화 상태입니다

llama-server은 llama.cpp에 포함된 OpenAI 호환 서버로, HTTP를 통해 GGUF 모델을 제공하도록 설계되었습니다. 별다른 설정 없이 실행하면 포트에 접근 가능한 모든 사용자가 인증 없이 요청을 보낼 수 있습니다:

llama-server -m model.gguf --port 8080

필요하면 --api-key <key>를 전달해 Bearer 토큰을 요구할 수 있으며, 이는 합리적인 첫 번째 방어 계층입니다. 하지만 기본값은 없고 TLS 종료는 별도의 수동 작업입니다. llama-server가 이를 대신 설정해 주지 않습니다.

이는 llama-server의 잘못이라는 뜻은 아닙니다. 이 도구는 가볍고 임베딩 가능한 추론 서버이며, 인증과 TLS를 선택적 플래그로 남겨 두어 신뢰할 수 있는 기기나 자체 인프라 뒤에서 간단하게 실행할 수 있습니다. Tokios는 다른 문제를 해결하기 위해 만들어졌습니다. 인바운드 포트를 열거나 TLS를 직접 구축하지 않고도 로컬 엔드포인트를 어디서든 호출할 수 있는 인증된 API로 전환하는 것입니다. llama.cpp는 Tokios의 일급 백엔드입니다.

아웃바운드 전용 방식

평소처럼 로컬 환경에서 llama-server를 실행합니다

항상 llama-server를 127.0.0.1에 유지하세요. 루프백보다 넓게 바인딩하지 마세요. GGUF 모델로 시작합니다:

llama-server -m model.gguf --port 8080

기본 설정된 http://127.0.0.1:8080에서 계속 수신 대기하도록 둡니다.

Tokios 커넥터를 페어링하세요

먼저 tokios.com/console에 로그인하고 Setup 탭을 열어 Start pairing을 클릭하세요. Tokios가 일회성 페어링 코드인 TKS-XXXX-XXXX를 표시하며, 약 15분 동안 유효합니다.이제 llama-server가 실행 중인 기기에서 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 탭에서 승인할 수 있습니다. 승인이 완료되면 커넥터의 토큰이 터널을 통해 전달되며, 화면에 표시되거나 파일에 직접 입력하는 일은 없습니다.

커넥터가 llama-server의 /v1 API를 가리키도록 설정하세요.

llama-server은 Tokios가 기대하는 OpenAI Chat Completions 형식을 이미 지원합니다. 단일 모델을 사용하는 경우 콘솔의 설정 마법사가 자동으로 http://127.0.0.1:8080/v1을 업스트림 모델 ID로 지정합니다. 여러 모델을 tokios-connector.json 설정으로 제공할 때는 업스트림 모델 ID를 BaseUrl로 명시적으로 지정해야 합니다.

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

다중 모델 설정 파일의 전체 형식은 커넥터 설정 문서를 참고하세요.

배포 작업을 등록하세요.

먼저 Models 탭에서 llama.cpp 모델을 등록하고 public name을 선택하세요. 예를 들어 llama-tunnel처럼 지정합니다. 클라이언트가 model 필드에 전송하는 것은 GGUF 파일이나 해당 내부 모델 ID가 아닌 이 공개 이름입니다.

API 키를 생성하세요.

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

어디서든 자유롭게 활용하세요

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

curl https://api.tokios.com/v1/chat/completions \
  -H "Authorization: Bearer sk-tok-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama-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="llama-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 llama-tunnel

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

자주 묻는 질문

스트리밍 기능도 지원되나요?

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

GGUF 모델을 미세 조정했는데, 이를 서비스로 제공할 수 있나요?

가능합니다. llama-server은 -m에 지정된 GGUF 파일을 그대로 서비스합니다. 미세 조정된 모델도 예외가 아니며, 다른 모델과 동일한 절차로 별도의 배포 이름으로 등록하면 됩니다. 미세 조정 모델을 Tokios 배포로 연결하는 전체 과정은 미세 조정 모델 서비스 방법을 참고하세요.

여러 GGUF 모델을 동시에 서비스할 수 있나요?

가능합니다. Models 탭에서 추가 배포를 등록하거나 tokios-connector.json 설정 파일을 활용해 여러 업스트림 모델 ID와 라우트를 정의할 수 있습니다. 각각 다른 포트에서 llama-server 프로세스가 실행되는 경우에 유용합니다. 자세한 내용은 커넥터 설정을 확인하세요.

llama-server의 --api-key 플래그도 계속 사용해야 하나요?

커넥터와 llama-server 간의 루프백 연결 보안을 강화하려면 해당 플래그를 유지해도 무방합니다. 다만 Tokios를 통해 접근하는 클라이언트를 인증하는 수단은 이 플래그가 아닙니다. https://api.tokios.com으로 전송되는 요청은 sk-tok-… API 키로 인증되며, 커넥터 자체만이 127.0.0.1:8080에 접근할 권한을 갖습니다.

사용하시는 모델은 절대 사용자의 기기 밖으로 나가지 않습니다. 하지만 생성된 엔드포인트는 어디서든 작동합니다.

llama-server은 로컬호스트 환경에서 현재와 동일한 방식으로 계속 작동합니다. 인바운드 포트 설정이나 수동 TLS 설정도 필요하지 않습니다. 커넥터는 아웃바운드 연결만 수행할 뿐입니다. 그 이후의 인증, 라우팅, 스트리밍 등 모든 기능은 단 하나의 엔드포인트를 통해 처리되며, API 키를 부여받은 어떤 기기나 팀원, 에이전트에서도 이를 호출할 수 있습니다.

빠른 시작

커넥터를 연결하고 첫 번째 모델 엔드포인트를 전체적으로 등록해보세요.

API 키

팀원이나 에이전트들을 위해 sk-tok-… API 키를 생성하고 권한을 설정하며 주기적으로 교체할 수 있습니다.

하드웨어와 호환성

런타임 서빙과 연결

클라이언트 또는 앱 연결

비교

어디서든 안전하게 llama.cpp 서버를 활용하세요

`llama-server`의 인증 기능은 선택 사항이며 기본값은 비활성화 상태입니다

아웃바운드 전용 방식

어디서든 자유롭게 활용하세요

자주 묻는 질문

사용하시는 모델은 절대 사용자의 기기 밖으로 나가지 않습니다. 하지만 생성된 엔드포인트는 어디서든 작동합니다.

빠른 시작

API 키

​llama-server의 인증 기능은 선택 사항이며 기본값은 비활성화 상태입니다

​아웃바운드 전용 방식

​어디서든 자유롭게 활용하세요

​자주 묻는 질문

​사용하시는 모델은 절대 사용자의 기기 밖으로 나가지 않습니다. 하지만 생성된 엔드포인트는 어디서든 작동합니다.

빠른 시작

API 키

`llama-server`의 인증 기능은 선택 사항이며 기본값은 비활성화 상태입니다

아웃바운드 전용 방식

어디서든 자유롭게 활용하세요

자주 묻는 질문

사용하시는 모델은 절대 사용자의 기기 밖으로 나가지 않습니다. 하지만 생성된 엔드포인트는 어디서든 작동합니다.