Communitygithub.com

V4TIME/V4SKILL

Termux에서 NaraRouter와 통합된 Flask AI 앱을 빌드합니다.

V4SKILL란 무엇인가요?

이 스킬은 Android 기기의 Termux 환경에서 로컬 AI 웹 애플리케이션을 구축하고 실행하는 방법을 제공합니다. 특히 NaraRouter를 기본 AI 게이트웨이로 활용하여 53개 이상의 모델에 접근할 수 있으며, 선택적으로 Hermes Agent를 추론 백엔드로 통합할 수 있습니다. 사용자는 Flask 백엔드, 브라우저 기반 Web Speech API를 통한 음성 모드, 세션 및 메모리 관리 기능을 갖춘 전문적인 다크 테마의 채팅 인터페이스를 구축할 수 있습니다. 이 스킬은 Termux의 네트워크 제약(예: pip 설치 시간 초과)에 대처하기 위해 `urllib` 사용을 권장하며, API 키 보안, 디버깅 방법, GitHub를 통한 휘발성 저장소 백업에 대한 실용적인 지침을 제공합니다.

지원 대상✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/V4TIME/V4SKILL/tree/HEAD/termux-flask

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

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/completionsOpenAI 호환채팅, 일반 작업
https://router.bynara.id/v1/messagesAnthropic 호환Anthropic 형식 요청
https://router.bynara.id/v1/responsesOpenAI Responses상태 저장 응답 API
https://router.bynara.id/v1/embeddingsOpenAI Embeddings벡터 임베딩
https://router.bynara.id/v1/modelsLIST요금제에서 사용 가능한 모델 조회
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-a3bnvapi-...작동빠름(~5-7초 간단 작업), 강력한 추론, 생각 모드 지원. 모바일에서 가장 안정적.
gpt-oss-20bnvapi-...작동OpenAI 호환
deepseek-ai/deepseek-v4-pro-0813nvapi-...시간 초과 위험데스크톱에서는 작동하지만 모바일 Termux 네트워크에서는 자주 시간 초과 발생
moonshotai/kimi-k3nvapi-...시간 초과 위험비전 지원, 모바일 네트워크에서 시간 초과

키 비대칭 경고: 모든 키에서 모든 모델을 사용할 수 있는 것은 아닙니다. 키 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가 구성된 경우 다음 작업을 수행하는 디스패처를 구축하세요:

  1. 작업 분류(수학, 코딩, 과학, 일반)
  2. 설명 텍스트를 기반으로 최적의 API 선택
  3. 호출 및 결과 반환
  4. 첫 번째 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 버그가 있다/작동하지 않는다고 보고할 때, 다음 순서로 진단:

  1. 서버가 실행 중인지 확인: curl -s --max-time 3 http://127.0.0.1:5000/api/health
  2. 정적 파일이 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도 확인)
  3. 서버가 실제로 제공하는 HTML 확인: curl -s http://127.0.0.1:5000/ | grep -E 'static/|style.css|app.js|chat.js|voice.js' — HTML의 경로가 Flask가 제공하는 것과 일치하는지 확인
  4. 정적 파일이 404를 반환하지만 HTML 링크가 /static/style.css 대신 상대 경로 style.css를 표시하면 그것이 버그입니다 — 두 템플릿을 모두 /static/ 접두사를 사용하도록 패치
  5. JS 파일을 읽고 모든 document.querySelector / getElementById / .querySelector 호출을 HTML에 실제로 있는 내용과 비교 — 누락된 요소는 전체 스크립트를 중단시킴
  6. null 참조 충돌 확인: 햄버거 요소가 없는 페이지의 el("hamburger"), .wrap이 존재하지 않을 때 messagesEl.querySelector(".wrap"), .composer가 존재하지 않을 때 document.querySelector(".composer .wrap") — 이 모든 것이 IIFE를 충돌시키고 페이지 전체의 JS를 중단시킴
  7. 요소 조회 보호: 결과를 사용하기 전에 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

Individual skills in this repo

This repo contains 12 individual skills — each has its own dedicated page.

관련 스킬