BYOL: SSH 터널링을 통해 원격 서버에서 로컬 LLM 사용하기

섹션별 상세

byol 스크립트는 OpenCode 설정 파일인 ~/.config/opencode/opencode.json을 자동으로 생성하거나 업데이트한다. 실행 시 지정된 API 엔드포인트의 /models 경로에서 사용 가능한 모델 목록을 조회하고, /chat/completions를 통해 실제 추론 가능 여부를 사전에 점검한다. 점검이 성공하면 해당 정보를 provider.byol 항목으로 저장하여 OpenCode 내에서 즉시 선택 가능하게 만든다.

python

python byol https://api.example.com/v1

특정 API URL을 인자로 전달하여 byol 스크립트를 실행하는 방법

SSH 역방향 터널링(-R) 옵션을 사용하여 로컬의 LLM 서버 포트를 원격 서버의 특정 포트로 매핑한다. 예를 들어 로컬의 11434 포트(Ollama 기본값)를 원격의 18080 포트로 연결하면, 원격 서버의 프로세스는 localhost:18080을 통해 로컬 머신의 LLM에 접근한다. 이때 -o SetEnv 옵션을 함께 사용하면 원격 세션 내에서 BYOL_OPENAPI_URL 환경 변수를 자동으로 설정하여 편의성을 높인다.

bash

ssh \
 -o SetEnv=BYOL_OPENAPI_URL=http://127.0.0.1:18080/v1 \
 -R 127.0.0.1:18080:127.0.0.1:11434 \
 user@remote-host

로컬 LLM 포트(11434)를 원격 서버 포트(18080)로 터널링하고 환경 변수를 설정하는 SSH 명령어

원격 서버의 SSH 설정 파일(/etc/ssh/sshd_config)에서 AcceptEnv 항목에 BYOL* 패턴을 추가해야 클라이언트가 보낸 환경 변수가 정상적으로 수용된다. 이 설정이 완료되면 원격 서버에서 추가 인자 없이 python byol 명령만으로 터널링된 LLM 정보를 자동으로 인식한다. 환경 변수가 설정되지 않은 경우 CLI 인자로 직접 URL을 전달하는 방식도 지원한다.

Ollama, vLLM, llama.cpp 등 OpenAI 호환 API 규격을 따르는 모든 로컬 추론 엔진과 호환된다. 스크립트는 외부 라이브러리 의존성 없이 Python 3.10 이상의 표준 라이브러리만 사용하여 구현되었으며, Windows 환경에서도 동일하게 작동한다. PuTTY와 같은 GUI 기반 SSH 클라이언트에서도 포트 포워딩 설정을 통해 동일한 기능을 구현할 수 있다.

PuTTY의 SSH 포트 포워딩(Tunnels) 설정 화면 스크린샷 — Screenshot로컬 포트(Source port: 9991)를 원격 대상(Destination: localhost:1234)으로 매핑하는 구체적인 GUI 설정 방법을 보여준다. 텍스트로 설명된 SSH 터널링 개념을 Windows 사용자가 PuTTY에서 어떻게 구현하는지 시각적으로 보충한다.

용어 해설

SSH 역방향 터널링(SSH Reverse Tunneling): — 원격 서버의 특정 포트로 들어오는 연결을 로컬 머신의 포트로 전달하는 기술이다. 외부에서 접근 불가능한 로컬 네트워크의 서비스를 원격 서버를 통해 안전하게 노출할 때 사용하며, 이 글에서는 로컬 LLM 서버를 원격 개발 환경에 연결하는 핵심 수단으로 쓰인다.
OpenAI 호환 API(OpenAI-compatible API): — OpenAI의 API 규격과 동일한 엔드포인트 구조를 제공하는 인터페이스이다. 이를 지원하는 추론 엔진은 별도의 코드 수정 없이 OpenAI SDK나 관련 도구들을 그대로 사용할 수 있어 범용성이 높다.
추론 엔진(Inference Engine): — 학습된 AI 모델을 실행하여 실제 결과값을 생성하는 소프트웨어 시스템이다. Ollama, vLLM, llama.cpp 등이 대표적이며, 모델 로딩, 메모리 관리, API 엔드포인트 제공 등의 역할을 수행한다.

기술

Python
SSH
Ollama
vLLM
llama.cpp
OpenCode

활용 사례

원격 VS Code/OpenCode 환경에서 로컬 LLM 연동
GPU가 없는 저사양 원격 서버에서 AI 코딩 보조 도구 사용
로컬에서 호스팅하는 커스텀 모델의 원격 테스트

언급된 리소스

GitHubbyol GitHub Repository (OpenCode)

섹션별 상세

python

python byol https://api.example.com/v1

특정 API URL을 인자로 전달하여 byol 스크립트를 실행하는 방법

bash

ssh \
 -o SetEnv=BYOL_OPENAPI_URL=http://127.0.0.1:18080/v1 \
 -R 127.0.0.1:18080:127.0.0.1:11434 \
 user@remote-host

로컬 LLM 포트(11434)를 원격 서버 포트(18080)로 터널링하고 환경 변수를 설정하는 SSH 명령어

용어 해설

SSH 역방향 터널링(SSH Reverse Tunneling): — 원격 서버의 특정 포트로 들어오는 연결을 로컬 머신의 포트로 전달하는 기술이다. 외부에서 접근 불가능한 로컬 네트워크의 서비스를 원격 서버를 통해 안전하게 노출할 때 사용하며, 이 글에서는 로컬 LLM 서버를 원격 개발 환경에 연결하는 핵심 수단으로 쓰인다.
OpenAI 호환 API(OpenAI-compatible API): — OpenAI의 API 규격과 동일한 엔드포인트 구조를 제공하는 인터페이스이다. 이를 지원하는 추론 엔진은 별도의 코드 수정 없이 OpenAI SDK나 관련 도구들을 그대로 사용할 수 있어 범용성이 높다.
추론 엔진(Inference Engine): — 학습된 AI 모델을 실행하여 실제 결과값을 생성하는 소프트웨어 시스템이다. Ollama, vLLM, llama.cpp 등이 대표적이며, 모델 로딩, 메모리 관리, API 엔드포인트 제공 등의 역할을 수행한다.

기술

Python
SSH
Ollama
vLLM
llama.cpp
OpenCode

활용 사례

원격 VS Code/OpenCode 환경에서 로컬 LLM 연동
GPU가 없는 저사양 원격 서버에서 AI 코딩 보조 도구 사용
로컬에서 호스팅하는 커스텀 모델의 원격 테스트

언급된 리소스

GitHubbyol GitHub Repository (OpenCode)

BYOL: SSH 터널링을 통해 원격 서버에서 로컬 LLM 사용하기

섹션별 상세

용어 해설

기술

활용 사례

언급된 리소스

BYOL: SSH 터널링을 통해 원격 서버에서 로컬 LLM 사용하기

섹션별 상세

용어 해설

기술

활용 사례

언급된 리소스

관련 토론

댓글

관련 기사

로컬 LLM 추론 엔진 비교: Llama.cpp vs vLLM

관련 토론

댓글

관련 기사

로컬 LLM 추론 엔진 비교: Llama.cpp vs vLLM