HTTP Gateway 설치

Bifrost Gateway는 OpenAI 호환 HTTP API를 제공하는 별도 프로세스입니다.

FastAPI, LangGraph, Batch Worker 같은 애플리케이션은 Provider API를 직접 호출하는 대신 Bifrost Gateway의 endpoint를 호출합니다.

Gateway 설치 방법은 크게 두 가지입니다.

방식	공식 Quickstart 명령	추천 용도
NPX Binary	`npx -y @maximhq/bifrost`	로컬 실습, 빠른 검증, 소규모 내부 사용
Docker	`docker run -p 8080:8080 maximhq/bifrost`	컨테이너 기반 실행, EC2/ECS/EKS 배포 전환

설치 방법 #

1. 가장 간단한 설치: NPX Binary #

NPX 방식은 Node.js/npm 환경만 있으면 Bifrost Gateway를 바로 실행할 수 있는 가장 간단한 방법입니다.

로컬 개발 환경이나 “먼저 띄워서 Web UI와 API endpoint를 확인하는 단계”에 가장 적합합니다.

# 설치 + 실행
npx -y @maximhq/bifrost

# 설치 + 실행
npx -y @maximhq/bifrost

특정 버전을 고정해서 실행할 수도 있습니다.

npx -y @maximhq/bifrost --transport-version v1.5.5

npx -y @maximhq/bifrost --transport-version v1.5.5

실행 후 브라우저에서 다음 주소로 접속합니다.

http://localhost:8080

http://localhost:8080

macOS라면 다음처럼 바로 열 수 있습니다.

open http://localhost:8080

open http://localhost:8080

Linux 환경에서는 다음을 사용할 수 있습니다.

xdg-open http://localhost:8080

xdg-open http://localhost:8080

Windows 환경에서는 다음을 사용할 수 있습니다.

start http://localhost:8080

start http://localhost:8080

npx 실행 시 자주 쓰는 옵션 #

목적	NPX 옵션 예시	의미
포트 변경	`-port 8080`	Gateway HTTP 서버 포트
host 변경	`-host 0.0.0.0`	외부 또는 컨테이너/VM 밖에서 접근 가능하게 bind
로그 레벨	`-log-level info`	`debug`, `info`, `warn`, `error`
로그 형식	`-log-style json`	`pretty` 또는 `json`
데이터 저장 위치	`-app-dir ./bifrost-data`	config DB, logs DB, config.json 저장 위치

예를 들어 EC2나 내부 VM에서 같은 VPC의 다른 애플리케이션이 접근해야 한다면 다음처럼 실행합니다.

npx -y @maximhq/bifrost \\
  -host 0.0.0.0 \\
  -port 8080 \\
  -app-dir ./bifrost-data

npx -y @maximhq/bifrost \\
  -host 0.0.0.0 \\
  -port 8080 \\
  -app-dir ./bifrost-data

-app-dir을 지정하지 않으면 OS 기본 config 디렉터리에 Bifrost 데이터가 생성됩니다.

OS	기본 app-dir 위치
Linux/macOS	`~/.config/bifrost`
Windows	`%APPDATA%\\bifrost`

app-dir에는 다음 데이터가 저장됩니다.

파일	역할
`config.json`	파일 기반 설정을 사용할 때의 설정 파일
`config.db`	Web UI에서 설정한 provider/key/config 저장용 SQLite DB
`logs.db`	요청 로그 저장용 SQLite DB

npx로 소규모 배포해도 되는가? #

결론부터 말하면, 간단한 소규모 내부 사용이라면 npx 방식도 가능합니다.

다만 “프로덕션 표준 배포 방식”으로 보기보다는, 단일 서버에서 적은 사용자가 쓰는 lightweight 배포 방식으로 보는 것이 안전합니다.

상황	npx 사용 판단
개인 로컬 실습	적합
팀 내부 PoC	적합
단일 EC2에서 소규모 내부 사용자만 사용	조건부 가능
외부 고객 대상 서비스	Docker/ECS/EKS 권장
장애 자동 복구, 롤백, 확장, 관측성이 중요한 운영	Docker/ECS/EKS/Kubernetes 권장

npx 방식으로 소규모 배포를 하려면 최소한 다음 조건을 지켜야 합니다.

버전을 고정합니다. 예: --transport-version v1.3.9
-app-dir을 명시해서 설정과 로그 저장 위치를 고정합니다.
-host 0.0.0.0로 열 때는 보안 그룹, 방화벽, VPN, 내부망 접근 제어를 반드시 설정합니다.
터미널에서 직접 실행하고 끝내지 말고 systemd, pm2, supervisor 같은 프로세스 관리 도구로 재시작 정책을 둡니다.
Provider API key는 shell history에 남지 않게 Web UI, 환경변수, secret 파일 등으로 관리합니다.
중요한 운영 환경에서는 SQLite 파일 하나에 의존하지 말고 PostgreSQL 기반 config/log store 전환을 검토합니다.

즉, npx는 “설치가 간단해서 운영에 절대 쓰면 안 된다”가 아니라, 운영 요구사항이 작을 때만 단순 배포 수단으로 허용하는 것이 적절합니다.

사용자가 늘거나 배포 자동화, 롤백, 모니터링, secret 관리가 중요해지면 Docker 또는 ECS/EKS로 전환하는 편이 좋습니다.

2. Docker 설치 #

Node/npm 환경을 신경 쓰지 않고, 동일한 컨테이너 이미지를 로컬·EC2·ECS·Kubernetes로 이어가기 좋습니다.

# 이미지 받기
docker pull maximhq/bifrost

# 실행
docker run -p 8080:8080 maximhq/bifrost

# 이미지 받기
docker pull maximhq/bifrost

# 실행
docker run -p 8080:8080 maximhq/bifrost

특정 버전을 사용할 수도 있습니다.

docker pull maximhq/bifrost:v1.3.9
docker pull maximhq/bifrost:v1.3.9-amd64
docker pull maximhq/bifrost:v1.3.9-arm64

docker pull maximhq/bifrost:v1.3.9
docker pull maximhq/bifrost:v1.3.9-amd64
docker pull maximhq/bifrost:v1.3.9-arm64

설정과 로그를 재시작 후에도 보존하려면 volume을 연결합니다.

mkdir -p ./data

docker run -p 8080:8080 \\
  -v $(pwd)/data:/app/data \\
  maximhq/bifrost

mkdir -p ./data

docker run -p 8080:8080 \\
  -v $(pwd)/data:/app/data \\
  maximhq/bifrost

Docker에서는 mount한 /app/data가 Bifrost의 app-dir로 사용됩니다.

따라서 Web UI에서 등록한 Provider 설정이나 요청 로그를 유지하려면 반드시 /app/data를 외부 volume에 연결해야 합니다.

Docker 환경변수로 기본 옵션을 지정할 수 있습니다.

목적	Docker 예시	의미
포트	`-e APP_PORT=8080 -p 8080:8080`	Gateway HTTP 포트
host	`-e APP_HOST=0.0.0.0`	컨테이너 내부 bind host
로그 레벨	`-e LOG_LEVEL=info`	로그 레벨
로그 형식	`-e LOG_STYLE=json`	로그 출력 형식

실행 확인은 다음처럼 합니다.

docker ps
docker logs -f <container-id-or-name>
curl -i <http://localhost:8080/health>

docker ps
docker logs -f <container-id-or-name>
curl -i <http://localhost:8080/health>

3. Docker Compose #

공식 Quickstart는 docker run까지만 간단히 보여줍니다.

다만 같은 옵션을 매번 명령어로 치기 번거롭다면 Compose 파일로 고정해 둘 수 있습니다.

services:
  bifrost:
    image: maximhq/bifrost:v1.5.5
    container_name: bifrost-gateway
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      APP_HOST: 0.0.0.0
      APP_PORT: 8080
      LOG_LEVEL: info
      LOG_STYLE: json
    volumes:
      - /c/Users/user/Documents/project/bifrost/data:/data

services:
  bifrost:
    image: maximhq/bifrost:v1.5.5
    container_name: bifrost-gateway
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      APP_HOST: 0.0.0.0
      APP_PORT: 8080
      LOG_LEVEL: info
      LOG_STYLE: json
    volumes:
      - /c/Users/user/Documents/project/bifrost/data:/data

docker compose up -d

docker compose up -d

상태와 로그를 확인합니다.

docker compose ps
docker compose logs -f bifrost
curl -i <http://localhost:8080/health>

docker compose ps
docker compose logs -f bifrost
curl -i <http://localhost:8080/health>

중지합니다.

docker compose stop

docker compose stop

컨테이너와 네트워크까지 제거합니다.

docker compose down

docker compose down

데이터까지 완전히 지우려면 다음을 사용합니다.

docker compose down -v

docker compose down -v

주의할 점은 docker compose down -v를 실행하면 volume 데이터까지 삭제될 수 있다는 것입니다.

설정을 보존해야 한다면 ./data:/app/data처럼 호스트 디렉터리를 명확히 지정하고, 삭제 명령을 신중하게 사용합니다.

Web UI에서 설정하는 방식과 파일 기반 설정 #

Bifrost는 크게 두 가지 설정 방식을 지원합니다.

방식	설명	적합한 상황
Web UI 설정	브라우저에서 Provider, API key, routing 등을 설정	로컬 실습, PoC, 빠른 운영 검증
`config.json` 파일 기반 설정	app-dir에 `config.json`을 두고 시작 시 읽게 함	GitOps, 반복 배포, UI 비활성 또는 고정 설정

Web UI를 사용할 수 있으면 처음에는 UI에서 Provider를 등록하는 것이 가장 쉽습니다.

Bifrost는 UI 변경사항을 DB에 저장하므로, Docker volume이 유지되면 재시작 후에도 설정이 남습니다.

파일 기반 설정을 사용할 때는 volume 디렉토리 아래에 config.json을 둡니다.

예시는 다음과 같습니다.

{
  "$schema": "<https://www.getbifrost.ai/schema>",
  "client": {
    "drop_excess_requests": false
  },
  "providers": {
    "openai": {
      "keys": [
        {
          "name": "openai-key-1",
          "value": "env.OPENAI_API_KEY",
          "models": ["gpt-4o-mini", "gpt-4o"],
          "weight": 1.0
        }
      ]
    }
  },
  "config_store": {
    "enabled": true,
    "type": "sqlite",
    "config": {
      "path": "./config.db"
    }
  }
}

{
  "$schema": "<https://www.getbifrost.ai/schema>",
  "client": {
    "drop_excess_requests": false
  },
  "providers": {
    "openai": {
      "keys": [
        {
          "name": "openai-key-1",
          "value": "env.OPENAI_API_KEY",
          "models": ["gpt-4o-mini", "gpt-4o"],
          "weight": 1.0
        }
      ]
    }
  },
  "config_store": {
    "enabled": true,
    "type": "sqlite",
    "config": {
      "path": "./config.db"
    }
  }
}

config_store가 없으면 UI 기반 실시간 설정이 제한될 수 있습니다. (config_store 내용은 뒷 절에서 설명)

반대로 config_store를 사용하면 UI/API 변경사항이 DB에 저장되고, 재시작 후에도 유지됩니다.

첫 API 호출 테스트 #

Web UI에서 Provider를 등록한 뒤 OpenAI 호환 endpoint로 호출합니다.

curl -X POST <http://localhost:8080/v1/chat/completions> \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "Hello, Bifrost!"}
    ]
  }'

curl -X POST <http://localhost:8080/v1/chat/completions> \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "Hello, Bifrost!"}
    ]
  }'

여기서 openai/gpt-4o-mini처럼 provider prefix를 붙이면 Bifrost가 해당 Provider로 요청을 라우팅합니다.

bare model name을 사용할 수도 있지만, 처음 실습에서는 provider prefix를 붙이는 편이 동작을 이해하기 쉽습니다.

AI 코딩 에이전트 Wiki

LangChain/LangGraph

OpenSearch

HTTP Gateway 설치

설치 방법 #

1. 가장 간단한 설치: NPX Binary #

npx 실행 시 자주 쓰는 옵션 #

npx로 소규모 배포해도 되는가? #

2. Docker 설치 #

3. Docker Compose #

Web UI에서 설정하는 방식과 파일 기반 설정 #

첫 API 호출 테스트 #

글이 도움이 되셨나요?

답글 남기기 응답 취소

설치 방법 #

1. 가장 간단한 설치: NPX Binary #

npx 실행 시 자주 쓰는 옵션 #

npx로 소규모 배포해도 되는가? #

2. Docker 설치 #

3. Docker Compose #

Web UI에서 설정하는 방식과 파일 기반 설정 #

첫 API 호출 테스트 #

글이 도움이 되셨나요?

공유하기

답글 남기기 응답 취소