클릭 한 번이면 웹 대시보드, API 및 MCP 서버, 원장 서비스, 그리고 Git으로 관리되는 원장을 포함한 Beancount.io 스택 전체가 여러분이 소유한 bex 워크스페이스에 배포됩니다. 이 가이드는 버튼을 누르는 순간부터 작동하는 원장을 갖추는 것까지 다룹니다. 이어서 도구 연결, 계정 추가, 업데이트, 백업, 스택 제거 방법을 설명합니다.
이 스택은 MIT 라이선스이며, 요금제 제한이 적용되지 않고, 호스팅 비용은 월 약 $33으로 여러분의 워크스페이스에 청구됩니다. 발표 내용은 클릭 한 번으로 나만의 Beancount.io 실행하기를 참고하세요.
스택 배포하기
- 실행하세요. Deploy to bex.co를 누르고, 스택을 소유할 워크스페이스를 선택하고, 요금제를 검토한 뒤 적용하세요. 미리보기를 승인하기 전까지는 아무것도 생성되지 않으며, 입력할 것도 없습니다. 모든 시크릿은 여러분의 워크스페이스 내부에서 생성됩니다.
- 첫 빌드를 기다리세요. 저희 실행에서는 27–30분이 걸렸으며, bex의 빌드 대기열이 바쁠 때는 더 오래 걸렸습니다. 롤아웃이 실패로 표시된 서비스는 재시도되지 않으므로, bex 대시보드에서 해당 서비스를 다시 배포하세요.
- 인스턴스를 확보하세요.
beancount-dashboard서비스의 URL을 열고 즉시 가입하세요. 이메일 인증 단계가 없으며, 첫 번째 계정이 생성되면 가입이 닫힙니다. - 원장을 만드세요. 스타터 템플릿에서 시작하거나, 샘플 원장을 불러와 둘러보세요.
첫 계정이 존재하기 전까지는 대시보드의 주소를 아는 누구나 계정을 만들 수 있습니다. 다른 사람이 먼저 가입했다면, 스택의 관리자 토큰으로 해당 계정을 제거하여 가입을 다시 열 수 있습니다.

셀프 호스팅 스택의 모든 계정은 최상위 등급을 받습니다. 원장, 지시문, 협업자, AI 사용량이 무제한입니다.
실행되는 항목과 비용
Blueprint는 워크스페이스에 여섯 개의 리소스를 생성합니다 (가격은 2026-11-18 기준 bex 요금제 미리보기에서 가져옴):
| bex 리소스 | 역할 | 월 비용 (USD) |
|---|---|---|
beancount-dashboard | 웹 앱이자 사용하는 유일한 공개 주소 | 4.90 |
beancount-api | GraphQL, REST, MCP 서버, Git 프록시 | 4.90 |
beancount-ledger | 장부 검증 및 쿼리 (비공개, 공개 주소 없음) | 4.90 |
beancount-gitea | 각 원장을 10 GB 디스크의 Git 저장소로 저장 (비공개) | 6.65 |
beancount-backend-db | 계정, 토큰, 설정용 Postgres | 4.41 |
beancount-cache | 로그인 세션 및 캐시용 Key Value | 7.21 |
| 합계 | 32.97 |
연결하는 모델 제공자, 메일 서비스, S3 버킷은 별도로 청구됩니다.
선택 기능 켜기
스택은 어떤 통합 없이도 부팅됩니다. 통합이 필요한 기능은 어떤 설정이 빠졌는지 알려줍니다. 통합을 추가하려면 bex에서 beancount-api 서비스를 열고 Environment 탭에서 변수를 추가한 뒤 서비스를 다시 배포하세요. 여기서 추가한 변수는 나중에 Blueprint를 동기화해도 유지됩니다.
| 변수 | 켜지는 기능 |
|---|---|
ANTHROPIC_API_KEY 또는 OPENAI_API_KEY | 영수증 스캔, 분류, 어시스턴트. bea ask에는 OPENAI_API_KEY가 필요합니다. |
TEMP_ASSETS_AWS_S3_* 및 PERM_ASSETS_AWS_S3_* (BUCKET, ACCESS_KEY_ID, SECRET_ACCESS_KEY) | 영수증 및 첨부 파일 업로드 |
SEND_GRID_API_KEY | 비밀번호 재설정 링크 등 메일 발송 |
OIDC_ISSUER, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET | 직접 운영하는 ID 제공자를 통한 로그인 및 추가 계정 (추가 계정 추가 참고) |
도구 연결하기
Git을 제외한 모든 곳에는 대시보드의 주소를 사용하세요. Git은 API의 주소를 사용합니다.
bea CLI
uv tool install beancount-io 또는 brew install bex-co/tap/bea로 bea를 설치하거나 업데이트한 뒤, 대시보드를 가리키도록 설정하세요:
export BEA_API_URL=https://<your dashboard address>
export BEA_DASHBOARD_URL=https://<your dashboard address>
bea cloud login # signs in through your browser
bea cloud ledger list두 변수 모두 대시보드의 주소를 받습니다. 대시보드가 API 트래픽을 전달하기 때문입니다. 다른 모든 bea cloud 명령은 Beancount CLI 레퍼런스에 정리되어 있습니다.
MCP를 통한 코딩 에이전트
Claude Code 또는 임의의 MCP 클라이언트에 배포된 MCP 서버를 추가하세요:
claude mcp add --transport http beancount \
https://<your dashboard address>/api-gateway/mcpClaude Code에서 /mcp로 로그인하세요. 동의 페이지는 여러분의 인스턴스가 제공하며, 클라이언트가 사용할 원장을 선택하고 승인하세요. 대신 헤더를 보내는 클라이언트의 경우, 개인 액세스 토큰(아래 참고)을 만들어 Authorization: Bearer <token>으로 전송하세요.
HTTPS를 통한 Git
모든 원장은 https://<your API address>/git/<owner>/<ledger>.git의 Git 저장소입니다. 원장의 Git Clone 메뉴에서 정확한 주소를 복사하세요. bex는 SSH를 라우팅하지 않으므로 Git은 HTTPS로 작동합니다. bea가 설치된 머신에서는 bea가 Git 로그인을 처리하도록 하세요:
bea cloud login # once, if you haven't already
bea cloud git setup # Git now signs in with your bea session
git clone https://<your API address>/git/<owner>/<ledger>.git이후 해당 호스트로의 git clone, git pull, git push는 아무것도 요구하지 않으며, bea cloud logout은 Git의 로그인 정보도 함께 제거합니다. bea cloud ledger clone은 SSH로 복제하므로, 이 스택에서는 위의 명령을 대신 출력합니다.

bea 없이 Git 사용하기
CI 러너나 bea가 없는 머신에서는 개인 액세스 토큰으로 Git에 로그인하세요:
- 토큰을 만드세요. 대시보드에서 Settings → Personal access tokens → New token을 여세요. 실행되는 위치에 맞춰 이름을 짓고(
laptop,nightly-backup), clone 및 pull에는ledger.read를 선택하고, push도 한다면ledger.write를 추가하세요. 무인 스크립트라면 하나의 원장으로 제한하고 만료일을 설정하세요. 지금bcio_토큰을 복사하세요. 한 번만 표시됩니다. - 복제하세요. Git이 사용자 이름과 비밀번호를 요청하면 임의의 비어 있지 않은 사용자 이름과 비밀번호로 토큰을 붙여넣으세요. macOS Keychain과 Windows의 Git Credential Manager는 다음 번을 위해 이를 저장합니다. Linux에서는 먼저 자격 증명 헬퍼를 켜세요. 예를 들어
git config --global credential.helper 'cache --timeout=86400'(하루 동안 메모리에 유지)입니다.

스크립트에서는 토큰을 Git이 .git/config에 저장해버릴 원격 URL이나 셸 기록에 남기지 마세요. 일회성 자격 증명 헬퍼를 통해 Git에 전달하세요:
read -rs BEANCOUNT_TOKEN; export BEANCOUNT_TOKEN
helper='!f() { echo username=token; echo "password=$BEANCOUNT_TOKEN"; }; f'
git -c credential.helper= -c credential.helper="$helper" \
clone --mirror https://<your API address>/git/<owner>/<ledger>.git빈 -c credential.helper=는 저장된 헬퍼가 토큰을 저장하지 못하도록 막습니다. 스크립트의 이후 모든 git fetch 또는 git push에도 두 -c 옵션을 전달하세요.
Git이 이전 비밀번호나 폐기된 토큰을 계속 제시한다면 삭제하세요:
printf 'protocol=https\nhost=<your API address>\n\n' | git credential reject모바일 앱
iOS 또는 Android 앱의 환영 화면에서 설정을 열고, 서버 URL을 대시보드 주소로 설정한 뒤 로그인하세요.
기존 장부 가져오기
대시보드에서 원장을 만들고 복제한 뒤, 여러분의 파일이나 Git 이력을 병합하고 push하세요. 이 스택은 main.bean을 원장의 진입점으로 열므로, 루트 파일의 이름을 main.bean으로 짓거나 main.bean에서 기존 파일을 include하세요.
추가 계정 추가하기
첫 계정 이후로는 가입이 계속 닫혀 있습니다. 추가 인원은 여러분이 연결하는 OpenID Connect 제공자를 통해 참여하며, 이 제공자가 2단계 로그인도 처리합니다. beancount-api 서비스의 Environment 탭에서:
OIDC_ISSUER,OIDC_CLIENT_ID,OIDC_CLIENT_SECRET을 설정하고, 클라이언트의 리디렉션 URI로https://<your dashboard address>/api-gateway/auth/oidc/callback을 등록하세요. 그러면 로그인 페이지에 Sign in with 뒤에OIDC_NAME(기본값SSO)이 표시됩니다.- 누가 참여할 수 있는지
OIDC_ALLOWED_EMAILS에 쉼표로 구분하여 나열하세요: 주소([email protected]), 도메인(@example.com), 또는 그 하위 도메인(@*.example.com). 목록에 있는 검증된 주소는 처음 로그인할 때 계정과 기본 원장을 받습니다. 목록이 없으면 제공자는 이미 연결된 계정만 로그인시킵니다.
허용된 모든 사람이 여러분의 디스크와 모델 키를 공유하며, 요금제 제한은 없습니다. 누구나 가입할 수 있는 제공자라면 @gmail.com과 같은 도메인 대신 주소를 나열하세요.
잊어버린 비밀번호 재설정
SEND_GRID_API_KEY가 없으면 비밀번호 찾기 페이지는 서버가 이메일을 보낼 수 없다고 사용자에게 알려줍니다. 대신 관리자 API에서 일회성 재설정 링크를 발급하세요. beancount-api 서비스의 Environment 탭에서 ADMIN_TOKEN을 복사하고, 대시보드의 주소가 아닌 해당 서비스 자체의 onbex.co 주소를 호출하세요:
read -rs ADMIN_TOKEN; export ADMIN_TOKEN
curl -sS -X POST "https://<your API address>/api/admin/password-reset-link" \
-H "x-admin-token: $ADMIN_TOKEN" -H "Content-Type: application/json" \
-d '{"email":"[email protected]"}'반환된 resetUrl은 신뢰하는 채널을 통해 사용자에게 보내세요. 한 번만 작동하며 한 시간 후 만료됩니다.
관리자 API는 API의 주소에 접근할 수 있는 누구나 도달할 수 있으며, ADMIN_TOKEN만이 이를 보호합니다. 이 토큰은 어떤 사용자로든 로그인할 수 있으므로 루트 비밀번호처럼 취급하세요: 셸 기록과 채팅에 남기지 말고, 유출 가능성이 있다면 교체하세요.
최신 릴리스로 업데이트하기
스택은 여러분이 업데이트할 때까지 배포한 버전에 머뭅니다. 버튼으로 만든 Blueprint는 push 웹훅을 받지 않으므로, 업데이트에는 두 단계가 필요합니다:
- Blueprint를 동기화하여 설정 변경을 적용하세요 (bex API:
POST /v1/blueprints/<id>/sync). - 각 서비스를 새 커밋에서 배포하세요. 코드 변경에는 빌드가 필요하기 때문입니다 (
commitId와 함께POST /v1/services/<id>/deploys).
bex는 한 번에 하나의 서비스를 빌드하고 API는 마지막에 빌드하므로, 전체 롤아웃은 거의 한 시간이 걸릴 수 있습니다. 데이터가 있는 스택에 최신 Blueprint를 동기화하기 전에 이미 실행 중인 스택 업그레이드를 읽고 먼저 백업하세요.
백업 및 복원
원장은 Gitea 디스크의 Git 저장소입니다. 계정, 개인 액세스 토큰, 설정은 관리형 Postgres에 있습니다. 각각 방식에 맞게 백업하세요.
원장
미러 복제는 원장의 파일과 이력을 완전히 백업합니다:
git clone --mirror https://<your API address>/git/<owner>/<ledger>.gitbea cloud git setup을 실행한 머신에서, 또는 bea 없이 Git 사용하기의 토큰 헬퍼를 사용하여 실행하세요. 복원하려면 원장이 목록에 아직 남아 있는 경우 대시보드에서 삭제하고 같은 이름으로 새로 만드세요. 서버는 원장의 main 브랜치로의 강제 push를 거부하므로, bea를 사용하지 않는 경우 ledger.write 권한이 있는 토큰을 사용하여 백업을 새 원장의 첫 커밋 위에 병합하세요:
git clone https://<your API address>/git/<owner>/<ledger>.git restore
cd restore
git fetch ../<ledger>.git main
git merge --allow-unrelated-histories -X theirs -m "Restore from backup" FETCH_HEAD
git push origin HEAD데이터베이스
bex는 beancount-backend-db를 지속적으로 백업하며, 이전 시점의 상태로 복원할 수 있습니다. 복원은 항상 새 데이터베이스로 이루어지고 제자리에서는 절대 이루어지지 않으므로, 해당 데이터베이스를 스택 자체의 데이터베이스로 다시 복사합니다:
-
bex에서
beancount-backend-db를 열고 Recovery를 선택한 뒤, 최소 10분 전의 시점을 골라 복원하세요. bex는 해당 시점 기준 데이터를 담은 새 데이터베이스를 만듭니다. -
복원하는 동안 아무것도 쓰지 않도록
beancount-api와beancount-gitea를 일시 중지하세요. -
PostgreSQL 16의
pg_dump와pg_restore로 데이터를 다시 복사하세요 (postgres:16Docker 이미지에 둘 다 있습니다). 양쪽 끝 모두에beancount-backend-db의 외부 연결 문자열을 사용하고, 복사본 쪽은 호스트만 복사본의 것으로 바꾸세요. bex가 복사본용으로 보여주는 연결 정보는 사용하지 마세요. 복원된 데이터를 읽을 수 없는 데이터베이스와 사용자를 가리킵니다.read -rs DB_URL; export DB_URL # beancount-backend-db's external connection string COPY_URL="${DB_URL/@<database host>/@<copy host>}" pg_dump -Fc --no-owner --no-privileges "$COPY_URL" > backend.dump pg_restore --clean --if-exists --no-owner --no-privileges -d "$DB_URL" backend.dumppg_restore는vector와pg_stat_statements확장을 삭제하지 못할 수 있다고 보고합니다. 이 오류는 예상된 것입니다. 복사본의 인증서가 아직 발급 중이라면COPY_URL에?sslmode=verify-full을 추가하고 bex가 복사본용으로 보여주는 CA를~/.postgresql/root.crt로 저장하세요. 연결이 시간 초과되면 다시 시도하세요. -
beancount-gitea와beancount-api를 재개한 뒤 복사본을 삭제하세요.
워크스페이스 밖으로 나가는 것
이 스택은 Beancount.io로 애널리틱스나 텔레메트리를 전혀 보내지 않으며, 브라우저 애널리틱스 스크립트는 빌드에서 제외됩니다. 저희가 아는 유일한 외부 요청은 다음과 같습니다:
- 비밀번호 유출 확인: k-익명성을 통해 확인되는, 새 비밀번호 SHA-1 해시의 처음 다섯 글자. 따라서 비밀번호와 계정 모두 노출되지 않습니다.
- 아바타: 브라우저가 사용자 이메일 주소의 해시로 Gravatar에 이미지를 요청합니다.
- 피드: Beancount.io 블로그와 변경 로그 피드로, 언어 설정만 전달됩니다.
- 가격 피드: 원장에 관리형 가격 URL이 포함된 경우에만 beancount.io로 요청합니다.
- 여러분의 통합: 모델 제공자, SendGrid, S3, Plaid, ID 제공자 등 연결하는 모든 것.
각 요청이 언제 발생하는지는 PRFAQ006의 개인정보 표에 나와 있습니다. 여러분의 서비스, 디스크, 데이터베이스는 bex의 인프라에서 bex의 개인정보 정책 및 서비스 약관에 따라 실행됩니다. bex는 Beancount.io를 만든 회사인 Stargately, Inc.가 만들었습니다. 호스팅되는 Beancount.io 서비스는 여러분의 스택과 별개이며 스택의 시크릿을 하나도 보유하지 않습니다.
스택 제거하기
리소스를 삭제하면 요금이 중단되는 동시에 데이터도 삭제됩니다. 먼저 모든 원장을 복제하세요.
위에서 설명한 대로 백업한 뒤, bex에서 여섯 개의 리소스를 삭제하고 마지막으로 Blueprint를 삭제하세요. 스택은 유지하고 본인 계정만 제거하려면 호스팅 서비스에서처럼 Settings → General → Danger Zone에서 삭제하세요. 유일한 계정을 삭제하면 가입이 다시 열립니다.
대신 직접 서버에서 실행하기
Docker 배포는 여러분이 제어하는 모든 서버에서 동일한 스택을 실행합니다. bex 배포 노트는 이 가이드의 모든 설정을 더 자세히 다룹니다.
문제가 생겼나요? GitHub 이슈를 열거나 Beancount Telegram 채팅에서 질문하세요.