# 클릭 한 번으로 나만의 Beancount.io 실행하기

Beancount.io의 전체 스택—웹 앱, API, MCP 서버, 그리고 Git 기반 원장—을 약 30분 만에 나만의 bex 워크스페이스에 배포하세요. 설정은 전혀 필요 없고, 요금제 제한도 없으며, MIT 라이선스이고, 호스팅 비용은 월 약 $33입니다.



Beancount는 평문 텍스트로 재정에 대한 완전한 소유권을 줍니다. 하지만 그 `.bean` 파일들을 둘러싼 소프트웨어를 소유하는 일은 더 어려웠습니다. 원장 위에 웹 UI, CLI, AI 에이전트 엔드포인트를 올리려면 우리의 호스팅 서비스에 장부를 맡기거나, 여섯 개의 서비스를 직접 연결해야 했습니다.

오늘부터 클릭 한 번으로 나만의 프라이빗 Beancount.io 인스턴스를 띄울 수 있습니다.

**Deploy to bex.co**를 누르고, 스택을 소유할 워크스페이스를 선택한 뒤, 요금제를 승인하세요. 설정할 것은 없습니다—모든 시크릿은 워크스페이스 내부에서 자동으로 생성됩니다. 약 30분 후 대시보드가 실행됩니다. 계정을 만들면 가입이 닫히고, 나만의 ID 제공자를 통해 초대하지 않는 한 누구도 들어올 수 없습니다.

[![Deploy to bex.co](/img/blog/run-your-own-beancount-io-from-one-button/deploy-to-bex.svg)](https://dashboard.bex.co/deploy?repo=https://github.com/bex-co/beancount-io&path=bex.yaml)

원장은 워크스페이스 내 디스크의 표준 Git 저장소로 존재합니다. 모든 인터페이스는 우리 주소가 아닌 오직 당신의 주소를 가리킵니다. 웹 대시보드, `bea` CLI, 내장 MCP 서버를 통한 코딩 에이전트, 또는 순수한 `git`(`bea`가 인증을 대신 처리함)이 그렇습니다. 원장, 지시문(directive), AI 사용량에 요금제 제한이 없으며, 스택은 Beancount.io로 분석 데이터를 전혀 보내지 않습니다.

선택적 연동은 필요할 때까지 꺼져 있습니다. 영수증 스캔, 분류, 어시스턴트를 위한 나만의 모델 키, 영수증 업로드를 위한 S3 버킷, 비밀번호 재설정을 위한 메일 키를 가져오면 됩니다. 연동을 추가할 때까지 각 기능은 필요한 설정을 보여줄 뿐이며, 나머지는 모두 기본적으로 작동합니다.

## 무엇을 얻고, 비용은 얼마인가

배포는 bex 워크스페이스에 직접 청구되는 여섯 개의 서비스를 프로비저닝합니다(가격은 2026-11-18 bex의 요금제 미리보기 기준):

| 서비스 | 역할 | 월 비용(USD) |
| --- | --- | --- |
| Dashboard | 웹 앱 및 당신이 사용하는 단일 공개 주소 | $4.90 |
| API | GraphQL, REST, MCP 서버, Git 프록시 | $4.90 |
| Ledger service | 장부 검증 및 쿼리(프라이빗, 공개 주소 없음) | $4.90 |
| Gitea | 10 GB 디스크에 각 원장을 Git 저장소로 저장(프라이빗) | $6.65 |
| Postgres | 계정, 토큰, 설정 | $4.41 |
| Key Value | 로그인 세션 및 캐시 | $7.21 |
| **합계** | | **$32.97** |

연결하는 외부 모델 제공자, 메일 서비스, S3 버킷은 해당 제공자가 별도로 청구합니다.

> **정리하기 전에:** 리소스를 삭제하면 청구가 즉시 중단되지만 **데이터도 함께 삭제됩니다.** 항상 Git 원장을 먼저 클론하세요.

셀프 호스팅 스택의 모든 계정은 자동으로 최상위 등급을 받습니다—인위적인 상한은 없습니다:

![셀프 호스팅 스택의 Settings, Billing: Enterprise 요금제로 AI 토큰, 원장, 지시문, 협업자가 무제한입니다.](/img/blog/run-your-own-beancount-io-from-one-button/no-plan-limits.webp)

## 클릭 한 번에서 첫 원장까지

1. **스택 실행.** **Deploy to bex.co**를 클릭하고(위 또는 [README](https://github.com/bex-co/beancount-io#self-host)), 워크스페이스를 선택하고, 요금제를 검토한 뒤 적용하세요. 승인하기 전에는 아무것도 프로비저닝되지 않습니다.
2. **초기 빌드 대기.** 첫 빌드는 우리 테스트에서 27–30분 걸립니다(bex의 빌드 대기열이 붐빌 때는 더 오래 걸림). 서비스가 실패한 롤아웃을 표시하면 bex 대시보드에서 재배포를 트리거하세요.
3. **인스턴스 점유.** 대시보드 URL을 열고 즉시 가입하세요—이메일 인증 단계는 없습니다.
4. **원장 생성.** 스타터 템플릿에서 새로 시작하거나, 샘플 원장을 불러와 탐색하세요.

> **보안 주의:** 첫 계정이 생성되기 전까지는 URL을 발견한 누구나 이를 점유할 수 있습니다. 누군가 먼저 가져간 경우, 스택의 관리자 토큰을 사용해 [해당 계정을 제거](https://github.com/bex-co/beancount-io/blob/main/docs/prfaqs/PRFAQ006-self-host-on-bex.md#13-someone-signed-up-before-me-what-now)하여 가입을 다시 열 수 있습니다.

![새 셀프 호스팅 배포에서의 가입 화면. 폼 옆에 이 사본은 소유자가 운영하며 장부는 Git의 평문 텍스트라고 표시됩니다.](/img/blog/run-your-own-beancount-io-from-one-button/sign-up.webp)

## 도구를 나만의 주소로 향하게 하기

### `bea` CLI

`uv tool install beancount-io` 또는 `brew install bex-co/tap/bea`로 [`bea`](/docs/Basics/bea-cli)를 설치하거나 업데이트한 뒤, 대시보드를 가리키게 하세요:

```zsh
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
```

두 환경 변수 모두 동일한 대시보드 URL을 사용하며, 이 URL이 API 트래픽을 대신 프록시합니다.

![셀프 호스팅 배포에 연결한 bea 0.4.1: bea cloud login, Enterprise 요금제의 bea cloud status, bea cloud ledger list.](/img/blog/run-your-own-beancount-io-from-one-button/bea-login.webp)

### 코딩 에이전트 (MCP)

Claude Code 또는 MCP 호환 클라이언트를 배포에 직접 연결하세요:

```zsh
claude mcp add --transport http beancount \
  https://<your dashboard address>/api-gateway/mcp
```

Claude Code에서 `/mcp`를 통해 로그인하세요—OAuth 동의 화면은 당신의 인스턴스에서 제공됩니다. 대신 헤더로 인증하는 클라이언트의 경우, **Settings → Personal access tokens**에서 토큰을 생성하고 `Authorization: Bearer <token>`으로 전달하세요. 우리 테스트 스택에서 MCP 클라이언트는 즉시 47개의 도구를 노출하고 원장에 대해 BQL 쿼리를 직접 실행했습니다.

![배포 자체의 주소와 개인 액세스 토큰으로 연결된 MCP 클라이언트: 47개의 도구와 원장에 대한 BQL 쿼리.](/img/blog/run-your-own-beancount-io-from-one-button/mcp-client.webp)

### 순수한 Git

모든 원장은 `https://<your API address>/git/<owner>/<ledger>.git`에 있는 Git 저장소입니다(원장의 **Git Clone** 메뉴에서 정확한 URL을 복사할 수 있습니다). bex는 SSH를 라우팅하지 않으므로 Git은 HTTPS로 작동하며, `bea`가 자격 증명을 대신 처리합니다:

```zsh
bea cloud login            # once, if you haven't already
bea cloud git setup        # configures Git to authenticate 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`은 HTTPS로 직접 클론하지 않습니다. SSH가 없는 서버에서는 이 명령들을 출력합니다.)*

![원장의 Git Clone 메뉴: API의 HTTPS 주소와 비밀번호로 사용하는 개인 액세스 토큰.](/img/blog/run-your-own-beancount-io-from-one-button/git-clone-menu.webp)

#### `bea` 없이 Git 사용하기 (CI 러너 및 스크립트)

머신이나 CI 러너에 `bea`를 설치하고 싶지 않다면, GitHub처럼 개인 액세스 토큰으로 인증하세요:

1. **토큰 생성.** **Settings → Personal access tokens → New token**으로 이동합니다. 환경에 맞게 이름을 짓고(`laptop`, `nightly-backup`), 클론/풀에는 `ledger.read`를 선택하고, 푸시가 필요하면 `ledger.write`를 추가합니다. 무인 스크립트의 경우 단일 원장으로 범위를 한정하고 만료일을 설정하세요. `bcio_...` 토큰을 즉시 복사하세요—한 번만 표시됩니다.

   ![Settings, Personal access tokens: ledger.read와 ledger.write 권한이 있는 토큰, 접두사, 생성 및 마지막 사용 시각.](/img/blog/run-your-own-beancount-io-from-one-button/access-tokens.webp)

2. **클론 및 캐시.** 첫 클론 시 사용자 이름으로 임의의 비어 있지 않은 문자열을 입력하고 비밀번호로 토큰을 붙여넣습니다. macOS(Keychain)와 Windows(Git Credential Manager)는 이를 자동으로 저장합니다. Linux에서는 먼저 자격 증명 헬퍼를 활성화하세요: `git config --global credential.helper store`(`~/.git-credentials`에 평문 저장) 또는 `credential.helper 'cache --timeout=86400'`(24시간 동안 메모리에 저장).

스크립트와 예약된 백업의 경우, 토큰이 원격 URL에 기록되지 않도록(즉 `.git/config`에 기록되지 않도록) 하고 셸 히스토리에도 남지 않도록 일회성 자격 증명 헬퍼를 전달하세요:

```zsh
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=`는 로컬 Keychain이나 `~/.git-credentials`가 토큰을 캐시하지 못하게 합니다. 스크립트의 모든 후속 `git fetch` 또는 `git push`에도 두 `-c` 플래그를 모두 전달하세요.

> **자격 증명 문제 해결:** Git이 오래된 비밀번호나 폐기된 토큰으로 계속 재시도한다면, `printf 'protocol=https\nhost=<your API address>\n\n' | git credential reject`로 지우세요. 비밀번호 기반 Git 인증은 아직 작동하지만 단계적으로 폐지되고 있습니다.

**기존 장부를 이전하시나요?** 새 원장을 만들고 파일이나 Git 히스토리를 병합한 뒤 푸시하세요. 스택은 `main.bean`을 진입점으로 읽으므로, 루트 파일의 이름을 `main.bean`으로 지정하거나 이를 사용해 기존 파일을 `include`하세요.

## 워크스페이스를 떠나는 것들

스택은 Beancount.io로 분석이나 원격 측정 데이터를 보내지 않으며, 브라우저 분석 스크립트는 빌드에서 완전히 제거됩니다. 우리가 아는 유일한 아웃바운드 요청은 다음과 같습니다:

- **비밀번호 유출 검사:** 새 비밀번호의 SHA-1 해시 첫 5자로 k-익명성 검사를 합니다(비밀번호도 계정도 노출되지 않음).
- **아바타:** 사용자 이메일 주소의 해시를 사용한 Gravatar로의 브라우저 요청.
- **피드:** Beancount.io 블로그 및 변경 로그 피드에 대한 요청(언어 설정만 전송, 사용자 데이터 없음).
- **가격 피드:** 원장이 관리형 가격 URL을 명시적으로 포함하는 *경우에만* beancount.io로의 요청.
- **나만의 연동:** 옵트인한 서비스(LLM 제공자, SendGrid, S3, Plaid, 또는 OIDC 제공자)로 전송되는 데이터.

각 요청이 언제 발생하는지에 대한 정확한 내용은 [전체 프라이버시 표](https://github.com/bex-co/beancount-io/blob/main/docs/prfaqs/PRFAQ006-self-host-on-bex.md#12-is-my-data-private)를 참조하세요.

## 누가 머신을 운영하는가

당신의 서비스, 디스크, 데이터베이스는 bex의 인프라에서, 당신의 워크스페이스 내에서, 당신의 청구로 실행됩니다. 완전한 투명성을 위해: bex는 Beancount.io를 만든 회사와 동일한 Stargately, Inc.가 만들었으며, 호스팅은 bex의 [개인정보 처리방침](https://bex.co/privacy-policy)과 [서비스 약관](https://bex.co/terms-of-service)에 따라 규율됩니다. 호스팅된 Beancount.io 서비스는 당신의 스택과 완전히 분리되어 있으며 그 시크릿을 전혀 보유하지 않습니다.

직접 제어하는 하드웨어에서 실행하고 싶으신가요? 우리의 [Docker 배포](https://github.com/bex-co/beancount-io/tree/main/deploy/docker)는 소유한 모든 서버에서 정확히 동일한 스택을 실행합니다.

## 알아두면 좋은 점

- **기본은 단일 사용자, 팀이나 가족을 위해 OIDC.** 첫 계정이 생성되면 가입이 닫힙니다. 다른 사람을 추가하려면 OpenID Connect 제공자를 연결하고 `OIDC_ALLOWED_EMAILS`에 허용할 주소를 나열하세요([설정 가이드](https://github.com/bex-co/beancount-io/tree/main/deploy/bex#more-accounts-your-own-identity-provider)). 2FA는 ID 제공자가 처리합니다.
- **업데이트는 원하는 일정대로.** 스택은 Blueprint를 동기화하고 재배포하기로 선택할 때까지 배포한 버전에 고정됩니다([업데이트 방법](https://github.com/bex-co/beancount-io/tree/main/deploy/bex#rolling-out-a-change)).
- **간단한 백업.** 원장은 그저 Git 저장소입니다—`git clone --mirror`로 전체 히스토리를 백업합니다. 계정, 토큰, 설정은 지속적 백업과 특정 시점 복구(point-in-time recovery)를 갖춘 관리형 Postgres에 저장됩니다([백업 가이드](https://github.com/bex-co/beancount-io/tree/main/deploy/bex#back-up-and-restore)).
- **모바일 앱 지원.** 모바일 앱의 환영 화면에서 설정을 열고 서버 URL을 대시보드 주소로 지정한 뒤 로그인하세요.

업데이트, 백업, 비밀번호 재설정, 스택 제거를 포함한 모든 단계를 한곳에서 보려면 [셀프 호스팅 가이드](/docs/self-host-beancount-io)를 참조하세요.

문제가 생겼나요? [GitHub 이슈](https://github.com/bex-co/beancount-io/issues)를 열거나 [Telegram 채팅](https://t.me/beancount)에 참여하세요.
