Termux에서 로컬 AI 웹 앱
Android 기기에서 Termux를 실행하여 로컬 웹 애플리케이션을 빌드하고 실행하며, AI API(특히 NaraRouter) 및 선택적으로 Hermes Agent를 추론 백엔드로 통합합니다.
사용 시기
- 사용자가 휴대폰에서 로컬 AI 어시스턴트/채팅 인터페이스를 원할 때
- Python/Flask로 Termux에서 웹 앱을 빌드할 때
- 설명 기반 라우팅으로 여러 AI API를 통합할 때
- 브라우저 Web Speech API를 통해 음성 모드를 추가할 때
- 채팅 간 세션 및 메모리를 관리할 때
- 사용자가 개발 도구(바이너리 릴리스, Rust/cargo, npm/npx, pip) 설치 지침을 붙여넣고 설치 및 사용을 요청할 때 — 먼저 휴대폰/Termux 환경에서의 가능성을 평가한 후, 허가를 받아 설치
아키텍처 패턴
브라우저(Chrome on Android) → Flask 백엔드(Termux) → AI API(들)
↓
Hermes Agent(선택 사항, 두뇌 역할)
핵심 원칙: 웹 앱은 인터페이스 계층입니다. Hermes Agent(사용 시)는 두뇌입니다. Flask 백엔드가 이 둘을 연결합니다.
빠른 시작
# Termux에서
mkdir ~/sayip && cd ~/sayip
mkdir -p templates static/css static/js storage/sessions
# app.py — 최소 Flask 시작 코드
from flask import Flask, render_template, request, jsonify
from pathlib import Path
import json, time, uuid, os
app = Flask(__name__, template_folder="templates")
HERMES_HOME = Path(os.path.expanduser("~/.hermes"))
SAYIP_STORAGE = Path(os.path.expanduser("~/sayip/storage"))
@app.route("/")
def index():
return render_template("chat.html")
@app.route("/api/chat", methods=["POST"])
def chat():
data = request.get_json()
# ... 메시지 처리, API 호출, 응답 반환
if __name__ == "__main__":
app.run(host="127.0.0.1", port=5000)
# 실행
python3 app.py
# Chrome에서 열기: http://127.0.0.1:5000
API 통합 패턴
NaraRouter(기본 권장)
NaraRouter는 53개 이상의 모델을 제공하는 통합 AI 게이트웨이로, 무료 티어를 사용할 수 있습니다.
키 형식: sk-nry-... (sk-nry-로 시작)
엔드포인트(모두 동일한 기본 URL + Bearer 키 사용):
| 엔드포인트 | 유형 | 용도 |
|---|---|---|
https://router.bynara.id/v1/chat/completions | OpenAI 호환 | 채팅, 일반 작업 |
https://router.bynara.id/v1/messages | Anthropic 호환 | Anthropic 형식 요청 |
https://router.bynara.id/v1/responses | OpenAI Responses | 상태 저장 응답 API |
https://router.bynara.id/v1/embeddings | OpenAI Embeddings | 벡터 임베딩 |
https://router.bynara.id/v1/models | LIST | 요금제에서 사용 가능한 모델 조회 |
https://api-images.bynara.id/v1/images/generations | 이미지 생성 | 텍스트-이미지 |
https://api-images.bynara.id/v1/images/edits | 이미지 편집 | 이미지 편집 |
키 사용 전 테스트:
curl -s -X POST https://router.bynara.id/v1/chat/completions \
-H "Authorization: Bearer sk-nry-YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"agnes-2.5-flash","messages":[{"role":"user","content":"hi"}],"max_tokens":10}'
알려진 작동 무료 티어 모델: agnes-2.5-flash, agnes-2.0-flash
요금제의 모델 확인:
curl -s https://router.bynara.id/v1/models \
-H "Authorization: Bearer sk-nry-YOUR_KEY" | python3 -c "import sys,json; [print(m['id']) for m in json.load(sys.stdin).get('data',[])]"
중요: 53개 모델 모두 모든 요금제에 있는 것은 아닙니다. deepseek-v4-pro-0813-bynara는 크레딧이 필요합니다. deepseek-v4-flash-free는 포함되지 않을 수 있습니다. 구성 전에 항상 테스트하세요.
NVIDIA NIM API (integrate.api.nvidia.com/v1)
NVIDIA NIM은 단일 OpenAI 호환 엔드포인트를 통해 82개 이상의 모델을 제공합니다.
기본 URL: https://integrate.api.nvidia.com/v1
엔드포인트: https://integrate.api.nvidia.com/v1/chat/completions
키 형식: nvapi- (예: nvapi-_qJeGmEP...)
키 사용 전 테스트:
curl -s -X POST https://integrate.api.nvidia.com/v1/chat/completions \
-H "Authorization: Bearer nvapi-..." \
-H "Content-Type: application/json" \
-H "Accept: text/event-stream" \
-d '{"model":"nvidia/nemotron-3.5-lightning-30b-a3b","messages":[{"role":"user","content":"hi"}],"max_tokens":10,"stream":true}'
알려진 작동 무료 티어 모델(Termux 모바일 네트워크에서 테스트):
| 모델 ID | 키 | 상태 | 참고 |
|---|---|---|---|
nvidia/nemotron-3.5-lightning-30b-a3b | nvapi-... | 작동 | 빠름(~5-7초 간단 작업), 강력한 추론, 생각 모드 지원. 모바일에서 가장 안정적. |
gpt-oss-20b | nvapi-... | 작동 | OpenAI 호환 |
deepseek-ai/deepseek-v4-pro-0813 | nvapi-... | 시간 초과 위험 | 데스크톱에서는 작동하지만 모바일 Termux 네트워크에서는 자주 시간 초과 발생 |
moonshotai/kimi-k3 | nvapi-... | 시간 초과 위험 | 비전 지원, 모바일 네트워크에서 시간 초과 |
키 비대칭 경고: 모든 키에서 모든 모델을 사용할 수 있는 것은 아닙니다. 키 1(nvapi-_qJeGmEP...)은 더 광범위한 액세스 권한이 있습니다. 키 2(nvapi-WDb7Rr...)는 더 제한적입니다. 일부 모델은 404를 반환합니다. 구성하기 전에 항상 특정 키로 모델을 테스트하세요.
죽은 키 표시:
401 Unauthorized— 키가 유효하지 않음/만료됨- 모델에 대한
404 Not Found— 모델이 이 계정/키에 없음 - 연결 시간 초과(30초 이상) — API가 느리거나 이 네트워크에서 연결할 수 없음
- Teamorouter
sk-teamo-...키 → OpenAI 엔드포인트(https://api.teamorouter.com/v1)에서insufficient_balance; Anthropic 엔드포인트(https://api.teamorouter.com)에서는 모델이 지원되지 않음. 죽은 키.deepseek-v4-pro-free모델을 제공하지만 잔액이 없으면 사용할 수 없음.
자세한 내용은 references/nvidia-api.md를 참조하세요: 모델별 Python 패턴(Nemotron 생각 모드, DeepSeek 비스트리밍, Kimi 비전 멀티모달), 스트리밍 reasoning_content 추출, urllib용 스레드 기반 하드 타임아웃 패턴, 비전 페이로드 형식.
API 디스패치 엔진
여러 API가 구성된 경우 다음 작업을 수행하는 디스패처를 구축하세요:
- 작업 분류(수학, 코딩, 과학, 일반)
- 설명 텍스트를 기반으로 최적의 API 선택
- 호출 및 결과 반환
- 첫 번째 API가 실패하면 다른 API로 폴백
통합 세부 사항은 references/nararouter-api.md를 참조하세요.
stdlib urllib 사용, requests 사용하지 않음
Termux에서 pip install requests는 대용량 다운로드 시 시간 초과될 수 있습니다. Python의 stdlib urllib를 대신 사용하세요. 항상 사용 가능하며 JSON API를 잘 처리합니다:
import urllib.request, json
def call_api(url, payload, api_key):
data = json.dumps(payload).encode()
headers = {"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"}
req = urllib.request.Request(url, data=data, headers=headers, method="POST")
with urllib.request.urlopen(req, timeout=30) as resp:
return json.loads(resp.read())
디자인 선호 사항(사용자별)
최소한의 전문적이고 AI 생성이 아닌 느낌:
- 어두운 테마, 좁은 간격, 그라데이션 없음, 장식용 그림자 없음
- 고정폭 글꼴(코드, API 키, 타임스탬프 등에 적합)
- 채팅 버블은 일반 직사각형 — 기능적이지 않으면 둥근 모서리 없음
- 사이드바 = 일반 목록, 의미 있는 경우가 아니면 아이콘 없음
- 디자인을 처음부터 생성하기보다는 참조 구현 검색
- 의심스러우면 기능을 추가하기보다 제거
구체적인 안티 패턴 — 웹앱이 AI 생성처럼 보이게 만드는 요소, 제거:
- 모든 헤더/타일/버튼의 이모지(
🤖,⚙,🎭,🔌,🧠,💬,🎤) — 제거. 일반 텍스트 레이블만 사용. - 호버 시 악센트 광택/박스 그림자(
box-shadow: 0 0 12px var(--accent-glow)) — 제거. 단색만 사용. - 바운스/펄스/슬라이드다운 키프레임 애니메이션(
@keyframes bounce,@keyframes pulse,@keyframes slideDown) — 제거. 모션 디자인 없음. - 아이콘이 있는 스플래시 화면 환영 카드(
.welcome-screen및welcome-icon,welcome-hints그리드) — 입력 영역의 한 줄 프롬프트 플레이스홀더로 대체. - 로고 옆 장식용 브랜드 아이콘(
.brand-icon및 이모지) — 제거. - 헤더를 장식하는 리본, 배지, 상태 점(
.health-badge,.health-dot) — 제거하거나 순수 기능적으로 만듦. - 그라데이션 배경, 유리 모피즘, 반투명 오버레이 — 절대 사용하지 않음.
경험 법칙: 브라우저에서 페이지를 열고 "인간 개발자가 유틸리티 도구를 위해 이 CSS를 직접 작성했을까?"라고 자문합니다. 답변이 '아니오'(모션, 광택, 이모지 장식이 있기 때문에)라면 제거합니다. 일반 도구는 터미널, 메모 앱 또는 최소한의 채팅처럼 보여야 하며 랜딩 페이지처럼 보이지 않아야 합니다.
음성 모드:
- Web Speech API 사용(
SpeechRecognition+SpeechSynthesis) — 무료, 브라우저 내장 - 텍스트/음성 모드 전환 버튼
- 음성 모드에서: 마이크가 지속적으로 듣고, 음성→텍스트→전송, 응답→말하기
- 음성 품질은 Chrome on Android에서 제공하는 수준으로 제한됨 — "Ultron 음성"을 약속하지 마십시오.
워크플로우 선호 사항(사용자별)
패키지 설치 전에 물어보기: pip install 또는 apt install을 실행하기 전에 사용자에게 먼저 물어보십시오. 이는 양보할 수 없는 사항입니다.
진행 상황을 지속적으로 표시: 작업이 몇 분 이상 걸리면 중간 결과를 표시합니다. 출력 없이 오랜 시간 동안 사라지지 마십시오. 무언가 막히면 그 사실과 시도 중인 내용을 알리십시오.
보안 강연 없음: 사용자는 API 키 위험을 이해하고 있습니다. 명시적으로 요청하지 않는 한 키 보안, 노출 또는 모범 사례에 대해 강연하지 마십시오. 사용자는 관련 시 자신의 설명을 제공했습니다.
완벽한 아키텍처보다 작동하는 솔루션 선호: 먼저 실행되는 것을 만드십시오. NaraRouter 키 테스트에서 이것을 보여주었습니다 — 키를 테스트하고, 작동하는 모델을 찾고, 구성하십시오. 과도하게 계획하지 마십시오.
저장소는 휘발성 — 초기에 GitHub에 백업: Termux/Android에서 앱 저장소(~/sayip/storage/)는 서버 다시 시작, Termux 다시 시작 또는 장치 재부팅 시 지워질 수 있습니다. API 키와 구성을 설정한 후 즉시 SSH를 통해 프로젝트를 GitHub 리포지토리로 푸시하여 구성을 복구할 수 있도록 하십시오. 세션 내에서는 storage/가 다시 시작 후에도 유지된다고 가정하지 마십시오. 다시 시작 후 항상 다시 확인하십시오. 모바일 네트워크가 포트 22를 차단하기 때문에 SSH-over-port-443 트릭( references/termux-git-ssh.md 참조)이 자주 필요합니다.
음성 모드는 완료되었다고 선언하기 전에 종단 간 테스트해야 함: chat.js의 Web Speech API 연결(setupVoice, startListening, speakText)은 음성 모드가 작동하는 것과 같지 않습니다. 실제로 휴대폰 마이크에 말하고 응답이 음성으로 다시 들리는지 테스트하십시오. Chrome on Android가 대상 브라우저입니다 — 데스크톱 Chrome이 아닌 이것이 중요합니다.
디버깅
포트 5000이 이미 사용 중:
fuser -k 5000/tcp # 포트 5000의 프로세스 종료
# 또는 ss로 확인:
ss -tlnp | grep 5000
Flask 앱이 시작되지 않거나 충돌:
- 구문 확인:
python3 -c "import py_compile; py_compile.compile('app.py', doraise=True)" - 시작하기 전에 포트가 비어 있는지 확인
timeout 15 python3 app.py로 실행하여 차단 없이 시작 출력 확인
API가 401/403/payment_required 반환:
- 키가 유효하지 않거나, 만료되었거나, 모델이 요금제에 없을 수 있음
- 앱에서 구성하기 전에 curl로 키를 직접 테스트
/v1/models를 확인하여 요금제에 실제로 포함된 모델 확인
Pip 설치 시간 초과:
- 모바일 Termux는 대용량 패키지의 경우 네트워크가 느리거나 불안정할 수 있음
- 가능하면 stdlib 대안 사용(urllib 대신 requests)
- 설치해야 하는 경우
pip3 install --timeout 30 <package>를 사용하여 빠르게 실패
강제 종료된 백그라운드 Flask 프로세스가 포트를 잠시 유지:
pkill -9 -f "[p]ython3 app.py"후 다시 시작하기 전에 2-3초 기다림.- "Address already in use" 오류가 발생하면 이전 프로세스가 소켓을 완전히 해제하지 않은 것임 — 더 오래 기다림.
코드 변경 사항을 적용하기 위해 Flask 서버를 다시 시작하기 전에 먼저 이전 프로세스를 종료:
- 패턴:
pkill -9 -f "[p]ython3 app.py" && sleep 3 && cd ~/sayip && python3 app.py & - 종료를 건너뛰면 "Address already in use"가 발생하고 새 인스턴스가 시작되지 않음.
- 다시 시작 후 항상
curl -s --max-time 3 http://127.0.0.1:5000/api/health로 확인.
사용자가 웹앱이 고장났다/JS 버그가 있다/작동하지 않는다고 보고할 때, 다음 순서로 진단:
- 서버가 실행 중인지 확인:
curl -s --max-time 3 http://127.0.0.1:5000/api/health - 정적 파일이 200을 반환하는지 확인:
curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:5000/static/style.css(app.js, chat.js, voice.js, settings.js도 확인) - 서버가 실제로 제공하는 HTML 확인:
curl -s http://127.0.0.1:5000/ | grep -E 'static/|style.css|app.js|chat.js|voice.js'— HTML의 경로가 Flask가 제공하는 것과 일치하는지 확인 - 정적 파일이 404를 반환하지만 HTML 링크가
/static/style.css대신 상대 경로style.css를 표시하면 그것이 버그입니다 — 두 템플릿을 모두/static/접두사를 사용하도록 패치 - JS 파일을 읽고 모든
document.querySelector/getElementById/.querySelector호출을 HTML에 실제로 있는 내용과 비교 — 누락된 요소는 전체 스크립트를 중단시킴 - null 참조 충돌 확인: 햄버거 요소가 없는 페이지의
el("hamburger"),.wrap이 존재하지 않을 때messagesEl.querySelector(".wrap"),.composer가 존재하지 않을 때document.querySelector(".composer .wrap")— 이 모든 것이 IIFE를 충돌시키고 페이지 전체의 JS를 중단시킴 - 요소 조회 보호: 결과를 사용하기 전에
var el = document.querySelector(selector); if (!el) return;
HTML/템플릿 편집 후 서버가 실제로 제공하는 것을 확인하여 프론트엔드 수정 사항 확인:
- 페이지 URL에 대한 curl과 정적 경로(
/static/style.css,/static/js/app.js)에 대한 grep은 수정 사항이 적용되었는지 확인합니다. - 정적 파일 URL에 대한 직접 curl과
-o /dev/null -w '%{http_code}'는 200을 제공하는지 확인합니다. - 실행 중인 서버에 대해 두 검사를 모두 통과할 때까지 HTML 편집이 적용되었다고 가정하지 마십시오.
이 프로젝트에서 가장 흔한 "모든 JS 버그" 원인:
- HTML 템플릿이 Flask의
/static/접두사(/static/style.css,/static/js/app.js,/static/js/chat.js) 대신 상대 정적 경로(style.css,app.js,chat.js)를 사용. - 브라우저가
http://127.0.0.1:5000/style.css를 요청 → 404. CSS와 JS가 로드되지 않음 → 페이지 스타일이 지정되지 않고 기능하지 않음. - 수정: 두 템플릿을 모두 패치하여
/static/접두사를 사용하고, 정적 파일을 적절한 위치(templates/대신static/)에 배치.
참고 자료
references/ 디렉토리 구조
sayip/
references/
naraouter-api.md # NaraRouter 통합 세부 사항
nvidia-api.md # NVIDIA NIM 통합 세부 사항
termux-git-ssh.md # Termux에서 SSH를 통한 Git 설정
termux-python-server.md # Termux Python 서버 일반 가이드
zrok-git.md # zrok을 통한 터널링
NaraRouter API 예제
채팅 완료(requests 없이 urllib 사용):
import urllib.request, json
def nara_chat(model, messages, api_key):
url = "https://router.bynara.id/v1/chat/completions"
payload = {"model": model, "messages": messages, "max_tokens": 1024}
data = json.dumps(payload).encode()
headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json"
}
req = urllib.request.Request(url, data=data, headers=headers)
with urllib.request.urlopen(req, timeout=30) as resp:
result = json.loads(resp.read())
return result["choices"][0]["message"]["content"]
모델 목록:
import urllib.request, json
def list_models(api_key):
req = urllib.request.Request(
"https://router.bynara.id/v1/models",
headers={"Authorization": f"Bearer {api_key}"}
)
with urllib.request.urlopen(req) as resp:
data = json.loads(resp.read())
return [m["id"] for m in data.get("data", [])]
세션 관리 패턴
def save_session(session_id, messages):
path = SAYIP_STORAGE / "sessions" / f"{session_id}.json"
path.parent.mkdir(parents=True, exist_ok=True)
with open(path, "w") as f:
json.dump({"messages": messages, "updated": time.time()}, f)
def load_session(session_id):
path = SAYIP_STORAGE / "sessions" / f"{session_id}.json"
if path.exists():
with open(path) as f:
return json.load(f).get("messages", [])
return []
디자인 시스템 기초
CSS 변수(예시):
:root {
--bg-primary: #1a1a1a;
--bg-secondary: #242424;
--text-primary: #e0e0e0;
--text-secondary: #a0a0a0;
--accent: #4a9eff;
--border: #333;
--font-mono: 'JetBrains Mono', 'Fira Code', monospace;
}
레이아웃 최소 사항:
- 왼쪽 사이드바(세션 목록, 새 채팅 버튼, 설정): 260px 고정 너비
- 오른쪽 메인 영역(메시지 목록, 입력 컴포저): flex 1
- 입력 영역: 하단 고정, textarea + 전송 버튼
- 설정: 사이드바 하단의 텍스트 링크, 전체 페이지 설정 보기로 이동
라이선스
이 스킬은 교육 목적으로 제공됩니다. 자신의 책임 하에 사용하십시오.
마지막 업데이트: 2024