Tokios 작동 방식: 내 모델, 내 하드웨어, 하나의 엔드포인트

Most networking problems with local models come down to direction: cloud clients want to send traffic in, but home networks, firewalls, and corporate VPNs block inbound connections by default. Tokios solves this by flipping the direction entirely. The tokios-connector dials out to Tokios once on startup and keeps that connection alive. Nothing on your side ever listens for an inbound connection — which means nothing on your side ever needs to be opened up. Connect a model, point a client at api.tokios.com, and your local hardware does the work.

​

Tokios가 메우는 간극

클라우드 AI 게이트웨이는 OpenAI, Anthropic, Azure 같은 호스팅 서비스로의 트래픽 라우팅에 탁월합니다. 하지만 localhost이나 프라이빗 VPC 내에 위치한 모델에 접근하는 것은 불가능합니다. 공용으로 라우팅 가능한 주소가 존재하지 않기 때문입니다. Tokios는 바로 이 간극을 해결하기 위해 설계되었습니다. 외부에서 사용자의 머신에 접근하려는 시도 대신, Tokios는 방향을 역전시킵니다. 사용자의 머신이 Tokios에 접속하는 구조입니다. 클라우드 엔드포인트는 항상 안정적이고 공용으로 제공되며, 그 뒤에 있는 모델은 항상 프라이빗하고 로컬에 존재합니다. 방화벽이나 라우터, DNS 설정 변경 없이도 완전히 활용 가능한 API 환경을 얻게 됩니다.

​

아웃바운드 전용 아키텍처

요청이 들어오기 전, 즉 대기 상태에서 각 구성 요소 간의 관계는 다음과 같습니다: The one connection your machine opens is the connector’s outbound WebSocket (the thick arrow). Every request rides back down that same tunnel (the dotted arrow) — nothing ever connects in. The connector maintains a persistent outbound WebSocket to the Tokios gateway. Claude Code, OpenAI Codex, or any other API client sends its request to api.tokios.com from anywhere on the internet — the Tokios gateway holds that inbound connection and pushes the request down the existing WebSocket to the connector, which forwards it to your local model. Your model never needs to be reachable from the outside world.

​

요청 흐름

코딩 에이전트가 API 호출을 실행할 때 정확히 어떤 과정이 일어나는지 다음과 같습니다: 단계별 설명:

1. 클라이언트가 요청을 전송하여 https://api.tokios.com/v1/chat/completions(또는 /v1/messages, /v1/responses)으로 Authorization: Bearer sk-tok-... 헤더를 함께 보냅니다.
2. Tokios가 API 키를 인증하고 해당 배포 정보를 확인합니다. 게이트웨이는 사용자의 테넌트 정보와 대조하여 sk-tok-... 토큰의 유효성을 검증한 뒤, model 필드에 명시된 배포 이름(예: gemma-tunnel)을 찾아내어 실제 업스트림 모델 ID(예: gemma4:e4b)로 변환합니다.
3. 게이트웨이가 요청을 변환한 뒤 터널로 전송합니다. 만약 클라이언트가 Anthropic Messages나 OpenAI Responses 형식을 사용했다면, 게이트웨이는 이를 먼저 OpenAI Chat Completions 형식으로 변환한 뒤 해당 배포에 할당된 커넥터의 WebSocket을 통해 전달합니다.
4. 이 커넥터는 사용자의 로컬 모델으로 요청을 전달합니다. tokios-connector은 터널을 통해 들어온 채팅 완성 요청을 수신한 뒤 사용자가 설정한 BaseUrl에 대해 표준 HTTP 호출을 수행합니다. 예를 들어 Ollama의 경우 http://127.0.0.1:11434/v1이 해당하죠. 로컬 모델 입장에서는 이 요청이 일반적인 로컬 요청과 다를 바 없습니다.
5. 응답이 다시 클라이언트로 전달됩니다. 로컬 모델에서 생성된 응답은, "stream": true을 요청했을 경우 스트림 형태의 토큰까지 포함하여 터널을 거쳐 Tokios 게이트웨이로 돌아오며, 여기서 클라이언트에게 전달됩니다. 전체 과정은 일반적인 HTTP API 호출과 동일하게 작동합니다.

​

프로토콜 변환에 관하여

코딩 에이전트가 사용하는 API 형식과 로컬 모델의 형식이 일치할 필요는 없습니다. 변환 작업은 모든 요청이 사용자의 머신에 도달하기 전 게이트웨이 단계에서 이루어집니다. Tokios는 클라이언트의 형식을 OpenAI Chat Completions 형식으로 변환한 뒤 터널로 전송하며, 커넥터는 이를 단순히 로컬 서버의 /v1/chat/completions으로 전달할 뿐입니다.

• Anthropic Messages (/v1/messages, Claude Code에서 사용하는 형식)는 Chat Completions 형식으로 변환됩니다.
• OpenAI Responses (/v1/responses, Codex에서 사용하는 형식) 역시 Chat Completions 형식으로 변환됩니다.
• OpenAI Chat Completions (/v1/chat/completions) 형식의 요청은 그대로 통과됩니다.

이러한 구조 덕분에 백엔드는 반드시 OpenAI Chat Completions 형식만 지원하면 됩니다. Ollama, llama.cpp, vLLM, LM Studio 모두 이 형식을 지원합니다. 커넥터 자체는 변환 기능이 없으며 단순히 요청을 전달할 뿐입니다. 변환이 게이트웨이에서 중앙 집중적으로 처리되므로, 배포에 사용되는 모델을 교체하더라도 에이전트 설정을 수정할 필요가 없습니다.

​

보안

아키텍처가 아웃바운드 전용이며 테넌트 범위로 제한되어 있기 때문에 설계 단계부터 공격 표면이 최소화되어 있습니다.

• No inbound ports are opened on your machine. There is nothing for a remote attacker to probe or connect to.
• 모델은 항상 localhost에 머뭅니다. 기본적으로 커넥터는 루프백 주소(127.0.0.1)로만 연결되므로 LAN 내의 모델에 접근하려면 별도로 옵션을 활성화해야 합니다. 모델이 인터넷에 노출되는 일은 결코 없습니다.
• 프롬프트와 응답 내용은 전송 중에 암호화됩니다. 커넥터와 api.tokios.com 사이의 모든 통신은 TLS로 보호된 WebSocket(wss://)을 통해 이루어지며 데이터가 평문 상태로 인터넷을 통과하는 경우는 없습니다.
• 테넌트 범위로 관리되는 API 키가 피해 확산을 방지합니다. 각 sk-tok-... 키는 해당 테넌트와 등록된 배포 환경에만 적용됩니다. 키가 유출되더라도 다른 고객의 모델이나 인프라에 접근할 수 없습니다.
• 기본적으로 어떠한 데이터도 저장되지 않습니다. 메터링 시스템은 토큰 수, 지연 시간, 상태 정보, 식별자만 기록할 뿐 응답 내용은 저장하지 않습니다. 요청 본문은 워크스페이스 관리자가 요청 로깅을 활성화했을 때만 저장되는데 이 경우도 암호화되어 첨부파일은 제거되고 기밀 정보는 마스킹 처리된 뒤 7일 후 삭제됩니다.

사용자 모델과 하드웨어. 단 하나의 엔드포인트만으로 모든 것이 해결됩니다.