설치 & 자체 호스팅

Olivares AI는 웹 콘솔이 내장된 하나의 정적 바이너리로 제공됩니다. 제어 평면 — 인프라의 AI 에이전트를 관찰하고 거버넌스하며 감사하는 부분 — 은 경계 내에서 실행되며 에어갭할 수 있습니다. 이 페이지는 프로덕션 형태의 설치를 다룹니다: 하나의 호스트, 보안 기본값, 상태 프로브, 멀티테넌트 배포에 중요한 스토어 선택.

먼저 둘러보고 싶다면 빠른 시작이 약 5분 만에 합성 데모 환경을 부팅합니다. 이 페이지는 실제 자세입니다.

바이너리 가져오기

여기에 복사할 공개 다운로드 URL은 없습니다. olivares 바이너리를 얻는 두 가지 방법:

• 서명된 릴리스 아티팩트 — 실행하기 전에 검증하세요. 서명 및 출처 체인은 릴리스 검증을 참조하세요.
• 소스에서 빌드 — 스토어는 순수 Go SQLite이므로 C 툴체인이 없습니다. task build가 웹 UI와 자사 커넥터가 내장된 ./bin/olivares를 생성합니다; olivares version으로 빌드한 것을 확인합니다.

어느 쪽이든 하나의 파일이 됩니다. 설치하고 루트로 실행하지 말고 전용 서비스 사용자를 만드세요.

보안 기본값

기본값은 플래그를 건드리기 전에 새 설치가 안전하도록 선택되었습니다.

최소한의 첫 부팅:

olivares serve \
  --listen 127.0.0.1:8443 \
  --grpc-listen 127.0.0.1:8444 \
  --data-dir /var/lib/olivares

데이터 디렉토리에는 스토어, 감사 서명 키, TLS 자료가 저장됩니다. 백업하고 제한적 권한으로 보호하세요.

일회용 설정 토큰 수령

새 설치에는 기본 자격증명이 없습니다. 첫 부팅 시 사용자가 없는 동안 엔진이 단일 사용 설정 토큰을 생성하고 stdout에만 출력합니다 — 로그에는 절대 출력하지 않습니다:

=== FIRST-BOOT SETUP ===
No users exist yet. Create the first administrator:
  POST /v1/setup  {"token":"olst_…","email":"you@example.com","password":"..."}
This token is shown ONCE and is single-use.
========================

토큰의 해시만 저장되므로, 놓친 토큰은 복구할 수 없고 재시작 시 다시 출력되지 않습니다. 사용자가 아직 없는 완전히 새로운 설치에서는 데이터 디렉토리에서 저장된 토큰을 제거하고 재시작하면 새 토큰이 생성됩니다. 이 복구는 사용자가 없을 때만 작동하므로, 구성된 설치를 인수할 수 없습니다.

첫 관리자를 생성한 후 설정 엔드포인트는 영구히 닫힙니다.

상태 프로브

HTTP 리스너는 의도적으로 다른 의미를 가진 두 개의 프로브를 노출합니다. 해당 Kubernetes 프로브에 연결하세요 — 두 가지를 혼동하면 재시작 루프나 오래된 라우팅이 발생합니다.

/livez는 생존 확인입니다. 의존성 검사를 실행하지 않습니다: 프로세스가 응답할 수 있으면 살아있는 것입니다. 실패하는 의존성이 생존 재시작을 트리거해서는 안 됩니다.

curl -ks https://127.0.0.1:8443/livez
# {"status":"ok"}

/readyz는 준비 확인이며, 로드 밸런서가 드레인해야 하는 가용성 신호입니다. 두 가지 경우에 503을 반환하며, 로그를 위해 본문에서 구분됩니다:

• 스토어 도달 불가 — {"status":"unavailable","store":"down"}. 스토어 핑은 짧은 타임아웃으로 실행되므로, 멈춘 백엔드가 행이 아닌 인스턴스 드레인을 유발합니다.
• 활성 기록기가 아님 — {"status":"standby","store":"up","leader":false}. 액티브-패시브 클러스터에서 스탠바이는 여기서 503을 보고하여 Service가 라우팅을 중단하도록 하며, 재시작하지 않습니다(그것은 /livez의 역할입니다 — 핫 스탠바이는 인수를 위해 계속 작동해야 합니다). 리더가 죽으면 스탠바이가 리더십을 획득하고 이것이 200으로 전환되어 트래픽이 새 리더를 자동으로 따릅니다.

엔진이 준비되면 200을 반환합니다:

{"status":"ok","store":"up","leader":true,"setup_required":false}

setup_required는 관찰을 위해 보고되지만 준비를 실패시키지 않습니다 — 새로 부팅된 엔진은 설정할 준비가 된 것입니다. 단일 노드 스토어에서 기록기는 항상 활성이므로 /readyz는 단순히 스토어 도달 가능성을 추적합니다.

스토어 선택

스토어는 --engine으로 선택합니다. 선호가 아닌 토폴로지에 따라 선택하세요.

SQLite (기본값)

내장된 순수 Go SQLite 스토어는 외부 의존성이 필요 없으며, 단일 노드, 실험실, 소규모 환경 또는 에어갭 설치에 적합합니다. 전체 상태가 데이터 디렉토리에 있습니다.

Postgres (멀티테넌트)

멀티호스트 또는 멀티테넌트 배포에는 Postgres를 사용하세요. 슈퍼유저나 BYPASSRLS 역할로 연결하지 마세요. 테넌트 격리는 FORCE ROW LEVEL SECURITY로 시행되며, Postgres는 이러한 역할에 대해 모든 행 수준 보안을 조용히 우회합니다 — 이는 테넌트 간에 애플리케이션 레이어 술어만 남깁니다. 엔진은 --allow-privileged-db-role을 명시적으로 전달하지 않으면 권한 있는 역할에 대해 시작을 거부합니다(단일 테넌트 또는 개발 전용).

대신 전용 최소 권한 역할을 프로비저닝하세요 — NOSUPERUSER NOBYPASSRLS NOCREATEROLE NOCREATEDB. 자체 데이터베이스를 소유하므로 스키마 마이그레이션을 적용할 수 있습니다; FORCE ROW LEVEL SECURITY는 테이블 소유자에게도 테넌트 정책을 적용하므로, 소유하지만 우회하지 않는 역할은 완전히 격리됩니다.

olivares serve --engine postgres \
  --dsn "postgres://olivares_app:$DB_PASSWORD@db:5432/olivares?sslmode=verify-full" \
  --data-dir /var/lib/olivares

sslmode=verify-full과 강력한 SCRAM 비밀번호를 사용하세요. 진정한 교차 테넌트 System 읽기(조직 목록, 멀티테넌트 체크포인트 커버리지)에는 별도의 역할이 필요합니다: NOSUPERUSER BYPASSRLS — 최소 권한이지만 테넌트 간 읽기가 가능한 — 역할을 프로비저닝하고 --admin-dsn을 가리키세요. 단일 테넌트 배포에서는 생략하면 해당 읽기가 단순히 RLS 제한됩니다.

완료하기 전에

두 가지가 사고 후 증거의 생존 여부를 결정합니다:

• 감사 서명 키를 오프박스로 백업하세요. 이것이 추가 전용 감사 원장에 서명합니다; 분실하면 원장을 더 이상 재검증할 수 없습니다. 엔진은 첫 부팅 시 경고합니다 — 시행되는 에스크로는 없습니다.
• 원장 공개 키의 오프박스 사본을 보관하세요. 오프호스트 사본이 호스트 침해 후 감사 검증을 탄력적으로 만듭니다.

그런 다음 데이터 디렉토리의 실제 백업을 예약하세요.

어디에서 무엇이 실행되는지

배치할 것은 제어 평면뿐입니다 — 선택하면 에어갭. 수집기(데이터 평면)는 항상 인프라에서 실행됩니다. 명확하게 말할 가치가 있는 한 가지 주의사항: Olivares는 Claude 사용을 거버넌스하고 감사하지만, Claude 추론 자체는 자체 호스팅되지 않습니다 — Anthropic의 API(직접 또는 Bedrock, Vertex, Foundry를 통해)에 도달합니다. 진정으로 자체 호스팅된 모델만 오프라인으로 실행됩니다. 전체 경계는 정직함 & 한계 페이지를 참조하세요.

다음 단계

• 실제 신호 배선: 소스 연결 및 Claude Code 연결.
• 설치 조정: 구성 참조.
• 모델 이해: 읽기/쓰기 접근 맵.