gori 설치

gori는 Crystal로 작성되었습니다. 아래에서 사전 빌드된 채널을 고르거나, 플랫폼에 맞는 것이 없으면 소스에서 빌드하세요. 모든 채널은 동일한 gori 바이너리를 설치합니다. 바이너리가 PATH에 올라가면 설치 확인으로 넘어가세요.

빠른 설치 (curl)

macOS와 Linux용 한 줄 명령입니다. OS/아키텍처를 감지해 알맞은 GitHub Release 자산을 내려받고 gori를 PATH에 올립니다:

curl -fsSL https://gori.hahwul.com/install.sh | bash

/usr/local에 쓸 수 있으면 그 아래에, 아니면 ~/.local에 설치합니다. GORI_INSTALL_PREFIX로 재정의할 수 있습니다. 설치 후에는 gori update가 바이너리를 스스로 업데이트합니다(설치를 담당하는 채널이 Chocolatey / Homebrew / Snap / AUR인 경우 그쪽으로 안내합니다).

GitHub rate limit에 걸린 경우

설치 스크립트는 최신 릴리스가 무엇인지 GitHub API에 묻는데, 이 API는 비인증 요청을 IP당 시간당 60회만 허용합니다. 공용 CI나 NAT 뒤에서는 403이 돌아올 수 있습니다. 설치 스크립트와 gori update 모두 rate limit이 없는 릴리스 리다이렉트로 자동 폴백하므로 그대로 동작하며, resolved v0.8.1 via ... (no API call) 같은 줄이 보입니다.

인증 시 한도인 5000회/시간을 쓰려면 토큰을 먼저 export하세요. curl 앞에 붙이면 안 되고 반드시 export해야 합니다. 스크립트는 파이프로 연결된 bash에서 실행되므로 curl에만 걸린 변수는 상속되지 않습니다:

export GITHUB_TOKEN=<personal access token>
curl -fsSL https://gori.hahwul.com/install.sh | bash

GORI_GITHUB_TOKEN과 GH_TOKEN도 동일하게 동작하며, gori update도 같은 변수를 읽습니다. 공개 저장소 읽기 권한만 있으면 됩니다.

직접 다운로드 (Dockerfile, CI)

모든 릴리스에는 버전이 없는 사본도 함께 올라갑니다. 버전 조회도 API 호출도 없이 고정된 URL로 최신 빌드를 받을 수 있습니다. v0.2.0부터 제공되며, 그 이전 릴리스에는 버전이 붙은 이름만 있습니다:

# Linux x86_64 / arm64: 정적 바이너리
curl -fsSL -o gori https://github.com/hahwul/gori/releases/latest/download/gori-linux-x86_64 && chmod +x gori

# macOS arm64 / x86_64: gori와 lib/이 담긴 tarball
curl -fsSL -o gori.tar.gz https://github.com/hahwul/gori/releases/latest/download/gori-osx-arm64.tar.gz

# Windows x86_64: 단독 실행 .exe
curl -fsSL -o gori.exe https://github.com/hahwul/gori/releases/latest/download/gori-windows-x86_64.exe

버전이 붙은 이름(gori-v0.8.1-linux-x86_64)도 그대로 유지되니, 특정 빌드에 고정하려면 그쪽을 쓰세요.

각 릴리스에는 두 이름 체계를 모두 담은 SHA256SUMS도 함께 올라갑니다. 설치 스크립트와 gori update는 이 파일로 자동 검증하며, 직접 받은 파일을 확인하려면:

curl -fsSL -O https://github.com/hahwul/gori/releases/latest/download/SHA256SUMS
sha256sum -c --ignore-missing SHA256SUMS       # Linux
shasum -a 256 -c --ignore-missing SHA256SUMS   # macOS

Homebrew

macOS(Apple Silicon 및 Intel)와 Linux(x86_64 및 arm64)에서 동작합니다:

brew install hahwul/gori/gori

이 명령은 tap을 먼저 추가하는 과정을 줄인 형태이며, 나눠서 실행해도 됩니다:

brew tap hahwul/gori
brew install gori

macOS 보틀은 링크된 모든 dylib를 바이너리 옆에 함께 번들한 자립형 tarball이고, Linux 보틀은 정적 빌드입니다. 어느 쪽도 추가 Homebrew 의존성을 끌어오지 않습니다.

Chocolatey (Windows)

Chocolatey 커뮤니티 저장소에서 설치합니다:

choco install gori

패키지는 v0.8.0부터 제공되는 Windows x86_64 바이너리를 설치합니다. gori update는 Chocolatey 설치를 인식해 choco upgrade gori -y를 안내합니다. Windows는 실행 중인 gori.exe를 교체하지 않으므로, gori를 닫고 관리자 셸에서 실행하세요.

Arch Linux (AUR)

x86_64용 바이너리 패키지가 AUR에 게시되어 있습니다. 원하는 AUR 헬퍼로 설치하세요:

yay -S gori
# or
paru -S gori

Snap

릴리스마다 strict confinement 스냅이 Snap Store에 게시됩니다. Linux x86_64용입니다:

sudo snap install gori

strict confinement에서는 홈의 숨김 디렉터리에 접근할 수 없으므로, 스냅의 GORI_HOME(설정, 루트 CA, 프로젝트 데이터베이스)은 ~/.gori가 아니라 ~/snap/gori/common입니다. gori update는 스냅 설치를 알아보고 snap refresh gori를 출력합니다(PATH에 snap 명령이 있으면 gori update --exec가 바로 실행합니다).

Nix

이 저장소는 플레이크(flake)이므로, 설치하지 않고 바로 실행할 수 있습니다:

nix run github:hahwul/gori

프로필에 설치하려면:

nix profile install github:hahwul/gori

NixOS / home-manager 설정에 입력(input)으로 고정할 수도 있습니다:

{
  inputs.gori.url = "github:hahwul/gori";

  # 이후 패키지 목록에서:
  #   inputs.gori.packages.${pkgs.system}.default

  # 또는 오버레이를 한 번 얹으면 어디서든 `pkgs.gori`로 쓸 수 있습니다. 사용할 때마다
  # ${system}을 적을 필요가 없고, gori도 설정의 나머지와 같은 nixpkgs로 빌드됩니다:
  #   nixpkgs.overlays = [ inputs.gori.overlays.default ];
}

다른 채널과 달리 이 채널은 소스에서 빌드합니다. nixpkgs의 Crystal이 gori가 요구하는 버전보다 한 단계 낮아, 플레이크가 컴파일러를 직접 고정하며 첫 빌드는 그것까지 함께 컴파일합니다. 몇 분이 걸리고 이후로는 캐시됩니다. Brotli와 Zstd 디코딩이 포함되며 호스트에 따로 준비할 것은 없습니다.

Linux(x86_64 및 arm64)와 Apple Silicon macOS를 지원합니다. nixpkgs가 Intel macOS 지원을 중단했으므로, 그쪽에서는 Homebrew나 사전 빌드 바이너리를 사용하세요.

nix develop을 실행하면 Crystal, shards, just와 링크되는 라이브러리가 갖춰진 셸로 들어갑니다. gori 자체를 개발하는 데 필요한 것이 모두 들어 있습니다.

Docker

멀티 아키텍처 이미지(x86_64 및 arm64)가 GitHub Container Registry에 ghcr.io/hahwul/gori로 게시되어 있습니다.

TUI는 터미널이 필요하므로 대화식으로 실행하세요. 설정과 루트 CA가 재시작 후에도 유지되도록 /data(컨테이너 내부의 GORI_HOME)에 볼륨을 마운트하고, 호스트에서 프록시에 접근할 수 있도록 0.0.0.0에 바인딩하세요:

docker run --rm -it \
  -v gori:/data \
  -p 8070:8070 \
  ghcr.io/hahwul/gori --listen 0.0.0.0

/data 볼륨을 마운트하지 않으면 루트 CA가 매 실행마다 재생성되며, 매번 다시 신뢰해야 합니다. 기본 바인드 호스트는 127.0.0.1이라 컨테이너 외부에서 접근할 수 없으므로 --listen 0.0.0.0이 필요합니다.

헤드리스 하위 명령은 TTY가 필요 없습니다:

docker run --rm    -v gori:/data ghcr.io/hahwul/gori run history
docker run --rm -i -v gori:/data ghcr.io/hahwul/gori mcp

시간은 기본적으로 UTC로 표시됩니다. 존 이름을 넘기면 로컬 시간으로 나옵니다:

docker run --rm -it -v gori:/data -p 8070:8070 -e TZ=Asia/Seoul \
  ghcr.io/hahwul/gori --listen 0.0.0.0

Apple container

Apple의 container(macOS 26 이상, Apple Silicon)는 같은 이미지를 같은 플래그로 실행합니다. -v gori:/data는 네임드 볼륨을 알아서 만들고, -it는 TUI에 터미널을 주며, gori mcp에는 -i만 있으면 됩니다:

container run --rm -it \
  -v gori:/data \
  -p 8070:8070 \
  ghcr.io/hahwul/gori --listen 0.0.0.0

컨테이너마다 호스트의 vmnet 네트워크에서 자기 IP를 받으므로 포트 게시는 선택입니다. container ls가 출력하는 주소를 클라이언트 프록시에 <ip>:8070으로 바로 지정해도 똑같이 동작합니다.

container build -f packaging/docker/Dockerfile -t gori:dev .로 소스에서 이미지를 빌드할 수 있으며, packaging/docker/Dockerfile.dockerignore를 읽습니다. Dockerfile 옆의 무시 목록만 찾으므로 BuildKit과 달리 컨텍스트 루트의 .dockerignore로 되돌아가지 않습니다. 빌더는 자체 VM에서 동작하므로 호스트의 HTTP_PROXY를 상속하지 않으며, 기본값이 CPU 2개에 2 GB입니다(container builder status). 그 크기에서는 gori의 --release 빌드가 한 시간을 훌쩍 넘기므로, 먼저 늘려 두는 편이 좋습니다:

container builder stop
container builder start --cpus 8 --memory 8g

사전 빌드 바이너리

macOS와 Linux용 독립 실행 바이너리가 모든 GitHub Release에 첨부되며, Windows(x86_64)용은 v0.8.0부터 제공됩니다. 플랫폼별 지원 등급과 Windows에서 알려진 한계는 플랫폼 지원에 정리되어 있습니다.

Linux

Linux 바이너리는 정적으로 링크(musl)된 자립형입니다. 하나를 내려받아 실행 권한을 주고 PATH로 옮기세요:

chmod +x gori-v*-linux-x86_64
sudo mv gori-v*-linux-x86_64 /usr/local/bin/gori

macOS

macOS 아카이브는 자립형입니다. 의존 dylib를 모두 바이너리 옆의 lib/ 폴더에 번들하고, 바이너리를 기준으로 상대 경로를 해석합니다. gori와 lib/를 함께 두세요. 안정적인 위치에 압축을 풀고 바이너리를 PATH에 링크하세요:

tar xzf gori-v*-osx-arm64.tar.gz          # extracts `gori` + `lib/`
sudo mkdir -p /usr/local/opt/gori
sudo cp -R gori lib /usr/local/opt/gori/
sudo ln -sf /usr/local/opt/gori/gori /usr/local/bin/gori

바이너리는 ad-hoc 서명되어 있습니다. Gatekeeper가 다운로드를 차단하면 격리 플래그를 지우세요: xattr -dr com.apple.quarantine /usr/local/opt/gori. Homebrew로 설치하면 이 문제를 피할 수 있습니다.

Windows

Windows 바이너리는 정적 링크되어 있어 따로 설치할 것도, 옆에 둘 DLL도 없습니다. gori.exe로 이름을 바꿔 PATH에 있는 폴더에 두세요:

New-Item -ItemType Directory -Force "$env:LOCALAPPDATA\Programs\gori" | Out-Null
Move-Item gori-v*-windows-x86_64.exe "$env:LOCALAPPDATA\Programs\gori\gori.exe"
# 그다음 그 폴더를 사용자 PATH에 추가합니다 (설정 → 환경 변수)

TUI는 Windows Terminal에서 실행하세요. .exe를 더블클릭하거나 cmd.exe에서 실행할 때 열리는 기본 콘솔 창에서는 글꼴에 따라 테두리 선이 빠지거나 일부 기호가 겹쳐 보일 수 있습니다. gori update는 .exe를 제자리에서 교체합니다. GORI_HOME의 기본값은 %USERPROFILE%\.gori입니다.

소스에서 빌드

사전 요구 사항

• Crystal >= 1.21.0
• pkg-config
• 리포지터리를 클론할 Git

시스템 라이브러리 (Brotli / Zstd)

기본적으로 gori는 네이티브 디코더에 링크하여 Content-Encoding: br(Brotli)와 zstd로 전송된 HTTP 본문을 표시할 수 있습니다. 빌드 전에 설치하세요:

빌드

git clone https://github.com/hahwul/gori
cd gori
shards build --release

릴리스 바이너리는 bin/gori에 생성됩니다. PATH에 있는 위치로 옮기세요:

cp bin/gori /usr/local/bin/

Brotli / Zstd 없이 빌드

해당 라이브러리를 사용할 수 없다면 이를 빼고 빌드하세요. Gzip과 deflate 디코딩(Crystal 표준 라이브러리 제공)은 계속 동작하며, Brotli와 Zstd 본문은 디코드된 텍스트 대신 "decoder not built in" 안내를 표시합니다:

shards build --release -Dwithout_native_codecs

정의되지 않은 BrotliDecoder* 심볼 때문에 링크가 실패하면, libbrotlidec이 없거나 pkg-config가 찾지 못하는 것입니다. brotli를 설치하거나(위 참조) -Dwithout_native_codecs를 사용하세요.

Windows에서 빌드

Crystal의 Windows 설치본에는 SQLite(FTS5 포함), Brotli, Zstd를 뺀 gori의 링크 라이브러리가 모두 들어 있습니다. 이 셋은 vcpkg에서 정적 라이브러리로 받고, 정적 C 런타임이 맞도록 --static으로 빌드하세요:

vcpkg install --triplet x64-windows-static "sqlite3[fts5]" brotli zstd
export CRYSTAL_LIBRARY_PATH="$(crystal env CRYSTAL_LIBRARY_PATH);C:\vcpkg\installed\x64-windows-static\lib"
shards install
crystal build src/main.cr -o bin/gori.exe --release --static

설치 확인

gori --version

gori 0.8.1이 표시되어야 합니다.

설치 없이 실행

개발 중에는 체크아웃한 위치에서 바로 실행할 수 있습니다:

shards run gori

다음 단계

이제 트래픽을 캡처할 준비가 되었습니다. 빠른 시작으로 이동하세요.