Ollama Tunnel - Entity Enricher 문서

Ollama Tunnel

명령어 하나로 노트북의 로컬 Ollama를 Entity Enricher에 연결하세요. 이미 보유한 모델을 사용하고 특정 입력을 기기에 유지하며 즉시 접근을 취소할 수 있습니다 — 모두 단일 아웃바운드 HTTPS 연결로 이루어집니다.

            Production (Hetzner)          Your Laptop / your server
        ┌─────────────────────────┐         ┌────────────────────┐
        │  Org enrichment         │         │  ee-tunnel CLI     │
        │     │                   │         │     │              │
        │     ▼                   │         │     ▼              │
        │  Ollama provider URL:   │         │  Ollama :11434     │
        │  http://ollama.<org>    │         │  ┌──────────────┐  │
        │       .tunnel/v1/chat   │         │  │ qwen3:36b    │  │
        │     │                   │         │  │ llama3:70b   │  │
        │     ▼                   │         │  │ ...          │  │
        │  WebSocket bridge       │◀───────▶│  └──────────────┘  │
        └─────────────────────────┘         └────────────────────┘
                                  one outbound :443/wss connection

합성 호스트 이름 ollama.<org-slug>.tunnel은 DNS로 확인되지 않습니다. Entity Enricher 프로세스의 커스텀 전송 계층이 *.tunnel에 대한 요청을 가로채 일치하는 활성 WebSocket을 통해 라우팅합니다.

왜 터널을 사용할까요?

이미 보유한 모델 사용

서버에 다시 다운로드하지 않고도 노트북에 이미 받아 둔 오픈 웨이트 모델(Llama 3, Qwen, DeepSeek, Mistral, …)로 보강을 실행합니다.

특정 입력을 사용자의 기기에 유지합니다

민감한 prompt의 경우 특정 enrichment를 직접 보유한 GPU를 통해 처리하세요. 플랫폼은 여전히 비용, 토큰, 메타데이터를 기록하며, 추론 자체만 로컬에 유지됩니다.

30초 만에 새 모델을 사용해 보세요

노트북에서 `ollama pull`로 모델을 받고 Discover Models를 클릭하면, 실제 컨텍스트 길이와 기능과 함께 Entity Enricher 선택기에 나타납니다.

급증하는 작업을 분산 처리

호스팅 공급자가 요청 속도를 제한하면 남은 배치는 터널링된 로컬 모델로 전환합니다.

빠른 시작

노트북에서 두 개의 명령, 브라우저에서 한 번의 클릭. 전체 과정은 약 1분이 걸립니다.

1
UI에서 tunnel 생성
API Keys → Ollama Tunnels를 열고 New Ollama Tunnel을 클릭합니다. 나중에 이 기기를 알아볼 수 있도록 레이블을 입력하세요(예: "Anthony's MacBook").
[스크린샷 자리 표시자 — "New Ollama Tunnel" 버튼이 강조된 터널 탭]
2
노트북에 CLI 설치
터미널에 붙여넣으세요. 스크립트는 설치 전에 cosign 서명을 검증합니다.
```
curl -fsSL https://entityenricher.ai/install.sh | sh
```
설치 프로그램은 수행하려는 작업(다운로드 URL, 서명, 설치 경로)을 출력하고 5초간 일시 정지하여 Ctrl+C를 누를 수 있는 시간을 제공합니다. 소스 코드는 TOT-Concept/ee-tunnel(MIT)에 있습니다. Windows 사용자는 대신 install.ps1을 사용하세요.
3
브라우저로 페어링하기
ee-tunnel pair를 실행합니다. 6자 코드가 있는 브라우저 탭이 /tunnel/connect에서 열립니다. 기기 라벨을 확인하고 Connect를 클릭합니다.
```
ee-tunnel pair --server https://entityenricher.ai

Open this URL in your browser to confirm pairing:
   https://entityenricher.ai/tunnel/connect?code=9KV-DU6

  Code: 9KV-DU6

Waiting for confirmation...
```
[스크린샷 자리 표시자 — 장치 코드가 있는 /tunnel/connect 확인 페이지]
토큰을 복사해 붙여넣을 필요가 전혀 없습니다. 브라우저는 터널 메타데이터만 볼 수 있으며, CLI는 자체 폴링 채널을 통해 자격 증명을 수신합니다.
4
연결하고 모델을 검색하세요
ee-tunnel을 실행합니다. Tunnels 탭의 상태 표시가 몇 초 내에 Connected로 바뀝니다. 그런 다음 Models & Pricing에서 Ollama 제공자의 Discover Models를 클릭하여 로컬에 설치된 모든 채팅 모델을 자동으로 가져옵니다.
[동영상 자리 표시자 — Discover Models가 로컬 Ollama 모델 4개를 플랫폼으로 가져오는 모습]

페어링 작동 방식

페어링은 OAuth 방식의 디바이스 코드 흐름(RFC 8628 형태)을 사용합니다. 사용자는 토큰을 복사해 붙여넣는 대신 브라우저에 짧은 코드를 입력합니다. 브라우저는 tunnel 메타데이터만 보며, CLI는 자체 폴링 채널을 통해 리프레시 토큰을 직접 수신합니다 — 일회성 교환입니다.

 laptop                  entity-enricher                  browser
   │                          │                              │
   │── ee-tunnel pair ──────▶ │                              │
   │   --server URL           │                              │
   │                          │                              │
   │  POST /api/tunnel/       │                              │
   │       device-code        │                              │
   │ ───────────────────────▶ │                              │
   │ ◀── { device_code,       │                              │
   │     user_code='9KV-DU6', │                              │
   │     verification_uri }   │                              │
   │                          │                              │
   │  prints URL, opens       │                              │
   │  browser at /tunnel/     │                              │
   │  connect?code=… ──────────────────────────────────────▶│
   │                          │                              │
   │                          │  POST /api/tunnel/confirm/   │
   │                          │       {user_code}            │
   │                          │  body: { label }             │
   │                          │  Authorization: Bearer       │
   │                          │   <user JWT, role=owner>     │
   │                          │ ◀──────────────────────────── │
   │                          │  • create tunnel_credentials │
   │                          │  • mark device_code complete │
   │                          │    with refresh_token        │
   │                          │ ────────────────────────────▶│
   │                          │  200 { tunnel metadata }     │
   │                          │                              │
   │  POST /api/tunnel/poll   │                              │
   │ ───────────────────────▶ │                              │
   │ ◀── { status:'ok',       │                              │
   │     refresh_token,       │                              │
   │     server_url,          │                              │
   │     tunnel_id }          │                              │
   │                          │                              │
   │  persist token mode 0600 │                              │
   │  ✓ Paired                │                              │

요청이 터널을 통해 어떻게 흐르는지

연결되면 터널링된 Ollama는 플랫폼의 나머지 부분 입장에서 보면 또 하나의 LLM 제공자일 뿐입니다. 다중 전문 분야, 융합, 배치 등 모든 것이 변함없이 작동합니다.

  enrichment job
       │
       ▼
  agent_factory  →  Ollama provider, base_url=http://ollama.acme.tunnel
       │
       ▼
  custom httpx transport  ← intercepts *.tunnel hosts
       │
       ▼
  TunnelSession (one per laptop)
       │ frames request: { id, method, path, headers, body_b64 }
       ▼
  WebSocket  ──────────────────────▶  ee-tunnel CLI
                                          │
                                          ▼
                                     localhost:11434
                                     (your local Ollama)
                                          │
                          response_start, response_chunk, ...
       ◀──────────────────────────────────┘
       │
       ▼
  pydantic_ai consumes streaming body  →  enrichment record

다중화

진행 중인 여러 강화 작업이 하나의 터널 WebSocket을 공유합니다. 각 요청에는 UUID가 부여되며, 프레임은 양쪽 끝에서 id로 역다중화되어 동시 호출(예: 다중 전문 분야)이 자연스럽게 작동합니다.

스트리밍 응답(Ollama의 stream=true)은 response_chunk 프레임의 시퀀스로 전달되므로, 터널을 통해서도 토큰 단위 UI 업데이트가 점진적으로 유지됩니다.

수명 주기

생성

조직 소유자가 "New Ollama Tunnel"을 클릭하고 레이블을 입력한 뒤 확인합니다. 플랫폼이 자격 증명을 할당합니다.

페어링

노트북에서 한 줄짜리 설치 프로그램과 `ee-tunnel pair`를 실행합니다. 브라우저 탭이 열리면 동일한 Entity Enricher 계정으로 확인합니다.

연결

`ee-tunnel`을 실행합니다. CLI가 단일 아웃바운드 HTTPS WebSocket을 엽니다. 새 제공자가 몇 초 내에 모델 목록에 표시됩니다.

사용

모델 검색을 클릭하면 로컬 Ollama의 모든 모델이 실제 컨텍스트 길이 및 기능과 함께 자동으로 가져와집니다. 평소처럼 강화하세요.

해지

UI에서 한 번 클릭하면 WebSocket이 종료되고 자격 증명이 즉시 무효화됩니다.

보안

터널은 공격 표면을 최소한으로 추가하도록 설계되었습니다. 이 기능의 초기 초안은 새로운 포트에서 공개 SSH 서버를 사용했지만, SSH 공격 표면을 완전히 제거하기 위해 이를 프로세스 내 WebSocket 멀티플렉서로 교체했습니다.

새로운 공개 포트가 없습니다

모든 것이 기존 :443 인그레스를 통해 처리됩니다 — 웹 앱과 동일한 TLS 엔드포인트입니다. SSH 서버도, 노출된 Ollama 포트도 없습니다.

아웃바운드 전용

CLI가 WebSocket을 시작합니다. 노트북은 인바운드 연결을 절대 수락하지 않으므로 홈 네트워크 방화벽을 변경할 필요가 없습니다.

Organization 범위

터널은 단일 조직에 바인딩됩니다. 플랫폼의 다른 테넌트는 이를 보거나 선택하거나 호출할 수 없습니다. 시스템 관리자는 설계상 조직 간 가시성을 가집니다.

즉시 해지 가능

해지하면 자격 증명이 데이터베이스에서 제거됩니다. 다음 요청은 401로 실패합니다. 활성 WebSocket은 약 1초 이내에 제거됩니다.

복사·붙여넣기한 시크릿 없음

브라우저 OAuth 플로우가 자격 증명을 종단 간으로 처리합니다. 브라우저는 리프레시 토큰을 절대 보지 못하며, CLI가 폴링 채널을 통해 직접 이를 수신합니다.

할당량 및 프레임 상한

기본적으로 조직당 활성 터널 5개, 인바운드 WebSocket 프레임 16MB 제한, 할당량 초과 시 구조화된 402 오류가 발생합니다.

SSRF 방어. tunnel 기능은 기존의 취약점도 함께 해결합니다. Ollama provider의 specific_endpoint 필드는 이제 허용 목록 정규식으로 검증되므로, 사설 IP, 루프백, Docker compose 서비스 이름은 provider URL로 사용할 수 없습니다.

CLI 참조

명령	기능
ee-tunnel pair --server URL	브라우저-OAuth 페어링. 인증 URL을 자동으로 엽니다.
ee-tunnel pair --server URL <token>	UI에서 복사한 새로 고침 토큰으로 수동 페어링(헤드리스 환경용 대체 방법).
ee-tunnel	연결하여 서비스를 제공합니다. 일시적 연결 끊김 시 지수 백오프(1초 → 30초)로 재연결합니다.
ee-tunnel status	페어링 상태, 서버 URL, 구성된 Ollama URL, 레이블을 표시합니다.
ee-tunnel disconnect	로컬 자격 증명을 삭제합니다. 서버 측에서는 취소되지 않으며, 이를 위해서는 UI를 사용하세요.
ee-tunnel version	인쇄 버전.

맞춤형 Ollama URL

Ollama가 다른 포트에서 수신 대기하는 경우, EE_TUNNEL_OLLAMA_URL을 설정하거나 페어링 시 --ollama URL을 전달하세요.

파일이 저장되는 위치

macOS · ~/Library/Application Support/ee-tunnel/
Linux · ~/.config/ee-tunnel/
Windows · %APPDATA%\ee-tunnel\

제한 및 타이밍

조직별 활성 터널	5(기본값)
리프레시 토큰 TTL	365일
액세스 토큰 TTL	15분
페어링 TTL	10분
인바운드 WebSocket 프레임 최대값	16MB
아웃바운드 청크 크기(CLI)	16KB
하트비트 간격	30초

자주 묻는 질문

내 Ollama가 인터넷에 노출되어 있나요?

아니요. CLI가 아웃바운드 WebSocket을 시작합니다. 노트북은 인바운드 연결을 수락하지 않으며, Ollama 포트는 localhost에 바인딩된 상태로 유지됩니다.

노트북이 절전 모드로 전환되면 어떻게 되나요?

CLI는 연결이 끊기면 정상적으로 종료됩니다. 노트북을 재개하고 ee-tunnel을 다시 실행하면 기존 자격 증명으로 재연결됩니다. 터널이 다운된 동안 실행 중인 강화 작업은 깔끔한 ConnectError와 함께 실패합니다.

다른 조직이 내 터널을 사용할 수 있나요?

아니요. 각 터널은 하나의 조직에 바인딩됩니다. 플랫폼의 다른 테넌트는 이를 보거나 선택하거나 호출할 수 없습니다. 시스템 관리자는 설계상 모든 터널을 볼 수 있습니다(전역 API 키와 동일).

회사 방화벽 뒤에서도 작동하나요?

거의 항상 가능합니다 — 아웃바운드 :443만 필요합니다. 웹 앱이 사용하는 것과 동일한 경로입니다.

자격 증명을 어떻게 교체하나요?

터널 탭에서 "토큰 교체"를 클릭하세요. 이전 토큰은 즉시 무효화되며, 모달에 노트북용 새 페어링 명령이 표시됩니다.

Ollama 없이 사용할 수 있나요?

예 — CLI는 임의의 HTTP를 전달합니다. EE_TUNNEL_OLLAMA_URL을 OpenAI 호환 로컬 엔드포인트로 설정하세요. Ollama의 /v1/chat/completions 또는 /api/tags를 지원하는 모든 것이 작동합니다.

오픈 소스

CLI와 설치 프로그램은 MIT 라이선스로 공개 저장소에 있어, 누구나 자신의 컴퓨터에서 실행되는 것을 감사할 수 있습니다.

소스: github.com/TOT-Concept/ee-tunnel

릴리스: github.com/TOT-Concept/ee-tunnel/releases — 각 바이너리는 게시 전에 cosign으로 서명됩니다.

설치 프로그램 검토: curl -fsSL https://entityenricher.ai/install.sh | less