HTTP 게이트웨이

HTTP 게이트웨이는 동일한 Agent를 REST/SSE API로 노출합니다. 웹 앱, Slack 봇, 또는 사용자 정의 프론트엔드에 Minara를 통합할 때 유용합니다.

서버 시작

minara serve
# listening on http://localhost:8080

기본적으로 포그라운드에서 실행됩니다. Ctrl+C로 서버를 중지합니다. 플래그:

• -p, --port <N>: 수신 포트를 재정의합니다 (GATEWAY_PORT 환경 변수도 읽습니다).
• --auth-token <T>: 모든 /v1/* 요청에 필요한 Bearer 토큰입니다. GATEWAY_AUTH_TOKEN도 읽습니다. 빈 값으로 설정하면 인증을 비활성화합니다 (개발 환경 전용).

환경 변수:

• GATEWAY_PORT (기본값 8080)
• GATEWAY_AUTH_TOKEN: 설정된 경우, 모든 요청에 Authorization: Bearer <token>을 포함해야 합니다. 빈 값으로 설정하면 인증을 비활성화합니다 (개발 환경 전용).

Web UI와 함께 한 번에 실행

minara serve --ui는 HTTP 게이트웨이와 Web UI를 동일한 셸에서 병렬 프로세스로 실행합니다. 게이트웨이는 8080 포트를 유지하며, Web UI는 4173 포트에서 실행됩니다 (apps/web-ui/dist의 Vite 미리보기 서버 빌드).

minara serve --ui
# [gateway] listening on http://localhost:8080
# [ui]      preview ready at http://localhost:4173/

콜드 부트 경로: apps/web-ui/dist/가 없거나 apps/web-ui/apps/agent/src/보다 오래된 경우, Minara는 미리보기 서버를 실행하기 전에 자동으로 빌드합니다. apps/web-ui/dist/.build.lock 아래의 파일 잠금은 두 개의 동시 serve --ui 호출이 빌드를 두고 경쟁하는 것을 방지합니다.

변형:

• --ui-dev: preview 대신 vite를 실행합니다 (핫 리로드, 포트 5173). Web UI 코드를 반복 수정할 때 사용합니다.
• --ui-port <N>: UI 포트를 재정의합니다.
• --no-build: 자동 빌드 검사를 건너뜁니다. apps/web-ui/dist/가 이미 최신 상태라고 가정하며, 그렇지 않은 경우 즉시 실패합니다 (0이 아닌 종료 코드, 명확한 오류 메시지).
• --daemon: 단독 serve --daemon과 동일하게 동작합니다. 게이트웨이와 UI 서브프로세스 모두 PID 파일로 추적됩니다 (server.pid + web-ui.pid). --stop은 PID 재활용 가드를 사용하여 양쪽을 종료하므로, 관련 없는 프로세스를 가리키는 오래된 UI PID 파일은 해당 프로세스에 신호를 보내지 않고 제거됩니다.

전체 플래그 표와 데몬 메커니즘은 minara serve 서브커맨드 참조를 참고하십시오.

데몬으로 실행

--daemon (또는 -d)은 서버를 터미널에서 분리하고, PID 파일을 작성하며, stdout/stderr를 로그 파일로 리디렉션합니다. systemd를 설정하지 않고도 재부팅 후에도 게이트웨이를 계속 실행할 때 유용합니다.

minara serve --daemon              # 백그라운드에서 시작
minara serve --status              # 실행 중인가? PID는?
minara serve --stop                # 정상 종료 SIGTERM, 최대 10초 대기

기본값 (--pid-file / --log-file로 재정의):

• PID 파일: $MINARA_DATA_DIR/server.pid (일반적으로 ~/.minara/server.pid)
• 로그 파일: $MINARA_DATA_DIR/logs/server.log

종료 코드는 LSB init-script 규약을 따릅니다. --status는 데몬이 실행 중이지 않을 때 3을 반환하므로 다음과 같이 연결할 수 있습니다.

minara serve --status || minara serve --daemon

운영 환경 수준의 감독 (충돌 시 재시작, 저널 통합, 부팅 시 시작)이 필요한 경우에는 minara serve를 systemd 또는 선호하는 감독자에 연결하십시오. 샘플 유닛 파일은 배포를 참고하십시오.

헬스 체크

curl http://localhost:8080/healthz
# {"ok":true}

채팅

curl -N -X POST http://localhost:8080/v1/chat/stream \
  -H "Authorization: Bearer $GATEWAY_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message": "buy $50 of SOL"}'

응답은 Server-Sent Events 스트림입니다 (-N은 curl의 버퍼링을 비활성화합니다). 각 이벤트는 JSON 페이로드로, LLM 델타 출력, 도구 호출, 최종 어시스턴트 응답을 담고 있습니다.

모든 라우트, 페이로드 형식, 인증 흐름은 전체 HTTP API 참조를 참고하십시오.