# bex で Beancount.io をワンクリックでセルフホスト

ワンクリックで、ウェブダッシュボード、API と MCP サーバー、台帳サービス、そして Git に裏打ちされた台帳を含む Beancount.io スタック全体を、自分が所有する bex ワークスペースにデプロイできます。このガイドでは、ボタンを押すところから実際に動く台帳までを解説します。さらに、ツールの接続、アカウントの追加、更新、バックアップ、スタックの削除についても取り上げます。

このスタックは MIT ライセンスで、プランの制限は一切なく、ホスティング費用は月額約 \$33 で、請求はあなたのワークスペースに発生します。発表については、[ワンクリックで自分だけのBeancount.ioを運用](/blog/2026/11/18/run-your-own-beancount-io-from-one-button)をお読みください。

## スタックをデプロイする

[![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)

1. **起動します。** **Deploy to bex.co** を押し、スタックを所有するワークスペースを選択し、プランを確認して適用します。プレビューを承認するまで何も作成されず、入力する項目もありません。すべてのシークレットはワークスペース内で生成されます。
2. **最初のビルドを待ちます。** 私たちの実行では 27〜30 分かかり、bex のビルドキューが混み合っているときはさらに長くかかりました。ロールアウトが失敗と表示されたサービスは再試行されません。そのサービスを bex ダッシュボードから再度デプロイしてください。
3. **インスタンスを確保します。** `beancount-dashboard` サービスの URL を開き、すぐにサインアップします。メール認証のステップはなく、最初のアカウントが作成されるとサインアップは閉じられます。
4. **台帳を作成します。** スターターテンプレートから始めるか、サンプル台帳を読み込んで見て回ります。

:::warning
最初のアカウントが存在するまでは、ダッシュボードのアドレスを知った誰でもアカウントを作成できます。もし誰かがあなたより先にサインアップした場合は、[スタックの管理者トークンでそのアカウントを削除して](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)

セルフホストスタック上のすべてのアカウントは、最上位のティアを利用できます。台帳、ディレクティブ、コラボレーター、AI の利用量はすべて無制限です。

## 何が動作し、いくらかかるか

Blueprint はワークスペース内に 6 つのリソースを作成します（価格は 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` | 独自のアイデンティティプロバイダー経由のサインイン、およびより多くのアカウント（**アカウントを追加する**を参照） |

## ツールを接続する

Git を除くすべての場面でダッシュボードのアドレスを使用します。Git は API のアドレスを使用します。

### bea CLI

[`bea`](https://beancount.io/ja/docs/Basics/bea-cli) を `uv tool install beancount-io` または `brew install bex-co/tap/bea` でインストールまたは更新し、ダッシュボードをポイントします。

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

どちらの変数もダッシュボードのアドレスを取ります。ダッシュボードが API トラフィックを転送するからです。その他の `bea cloud` コマンドはすべて [Beancount CLI リファレンス](https://beancount.io/ja/docs/bea-cli-reference)に一覧されています。

### MCP 経由のコーディングエージェント

デプロイの MCP サーバーを Claude Code や任意の MCP クライアントに追加します。

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

Claude Code で `/mcp` を使ってサインインします。同意ページはあなた自身のインスタンスによって提供されます。クライアントが使用できる台帳を選択して承認してください。代わりにヘッダーを送信するクライアントの場合は、パーソナルアクセストークン（後述）を作成し、`Authorization: Bearer <token>` として送信します。

### HTTPS 経由の Git

すべての台帳は `https://<your API address>/git/<owner>/<ledger>.git` にある Git リポジトリです。正確なアドレスは台帳の **Git Clone** メニューからコピーしてください。bex は SSH をルーティングしないため、Git は HTTPS 経由で動作します。`bea` がインストールされたマシンでは、Git のサインインを任せられます。

```zsh
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 経由でクローンするため、このスタックでは上記のコマンドを表示します。

![台帳の Git Clone メニュー: API の HTTPS アドレスと、パスワードとしてのパーソナルアクセストークン。](/img/blog/run-your-own-beancount-io-from-one-button/git-clone-menu.webp)

### bea なしで Git を使う

CI ランナーや `bea` のないマシンでは、パーソナルアクセストークンで Git にサインインします。

1. **トークンを作成します。** ダッシュボードで **Settings → Personal access tokens → New token** を開きます。実行される場所にちなんで名前を付け（`laptop`、`nightly-backup`）、クローンとプルには `ledger.read` を、プッシュする場合は `ledger.write` を追加します。無人スクリプトの場合、単一の台帳に制限し、有効期限を設定します。`bcio_` トークンは今すぐコピーしてください。一度しか表示されません。
2. **クローンします。** Git がユーザー名とパスワードを要求します。空でない任意のユーザー名を入力し、パスワードとしてトークンを貼り付けます。macOS の Keychain と Windows の Git Credential Manager は次回のためにそれを保持します。Linux では、まず認証情報ヘルパーを有効にします。例えば `git config --global credential.helper 'cache --timeout=86400'`（1 日間メモリに保持）です。

![設定、パーソナルアクセストークン: ledger.read と ledger.write を持つトークン、そのプレフィックス、作成日時と最終使用日時。](/img/blog/run-your-own-beancount-io-from-one-button/access-tokens.webp)

スクリプトでは、トークンをリモート URL（Git が `.git/config` に保存してしまう場所）やシェル履歴に入れないでください。一時的な認証情報ヘルパーを通じて Git に渡します。

```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=` は、保存済みのヘルパーがトークンを保存するのを防ぎます。スクリプト内の以降のすべての `git fetch` や `git push` にも両方の `-c` オプションを渡してください。

Git が古いパスワードや取り消されたトークンを提示し続ける場合は、クリアします。

```zsh
printf 'protocol=https\nhost=<your API address>\n\n' | git credential reject
```

### モバイルアプリ

[iOS](/beancount-ios) または [Android](/beancount-android) アプリのウェルカム画面で設定を開き、サーバー URL をダッシュボードのアドレスに設定してサインインします。

## 既存の帳簿を持ち込む

ダッシュボードで台帳を作成し、クローンし、ファイルや Git 履歴をマージしてプッシュします。スタックは `main.bean` を台帳のエントリーポイントとして開くため、ルートファイルを `main.bean` と命名するか、`main.bean` で既存のファイルを `include` してください。

## アカウントを追加する

最初のアカウントの後、サインアップは閉じたままです。他の人は、あなたが接続する OpenID Connect プロバイダーを通じて参加し、そのプロバイダーが二要素サインインも処理します。`beancount-api` サービスの **Environment** タブで次のように設定します。

1. `OIDC_ISSUER`、`OIDC_CLIENT_ID`、`OIDC_CLIENT_SECRET` を設定し、`https://<your dashboard address>/api-gateway/auth/oidc/callback` をクライアントのリダイレクト URI として登録します。その後、サインインページに **Sign in with** に続いて `OIDC_NAME`（デフォルトは `SSO`）が表示されます。
2. `OIDC_ALLOWED_EMAILS` に参加を許可する人をカンマ区切りで列挙します。アドレス（`alice@example.com`）、ドメイン（`@example.com`）、またはそのサブドメイン（`@*.example.com`）です。列挙された、検証済みのアドレスは、初回サインイン時にアカウントとデフォルト台帳を取得します。リストがない場合、プロバイダーは既にリンク済みのアカウントにのみサインインします。

あなたが受け入れた全員が、プランの制限なしに、あなたのディスクとモデルキーを共有します。誰でも参加できるプロバイダーの場合は、`@gmail.com` のようなドメインではなく、アドレスを列挙してください。

## 忘れたパスワードをリセットする

`SEND_GRID_API_KEY` がない場合、パスワードを忘れた場合のページは、サーバーがメールを送信できないことをユーザーに伝えます。代わりに管理者 API からワンタイムリセットリンクを発行します。`beancount-api` サービスの **Environment** タブから `ADMIN_TOKEN` をコピーし、ダッシュボードではなく、そのサービス自身の `onbex.co` アドレスを呼び出します。

```zsh
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":"user@example.com"}'
```

返された `resetUrl` を、信頼できるチャネルでユーザーに送信してください。1 回のみ有効で、1 時間後に失効します。

:::warning
管理者 API は、API のアドレスに到達できる誰からも到達可能で、`ADMIN_TOKEN` のみがそれを守っています。このトークンは任意のユーザーとしてサインインできるため、root パスワードと同様に扱ってください。シェル履歴やチャットに残さず、漏洩した可能性がある場合はローテーションしてください。
:::

## 新しいリリースに更新する

スタックは、更新するまでデプロイしたバージョンのままです。ボタンから作成された Blueprint にはプッシュ webhook がないため、更新には 2 つのステップが必要です。

1. **Blueprint を同期する** と、設定への変更が適用されます（bex API: `POST /v1/blueprints/<id>/sync`）。
2. **各サービスを新しいコミットでデプロイする** と、コードの変更にはビルドが必要です（`commitId` を指定して `POST /v1/services/<id>/deploys`）。

bex は一度に 1 つのサービスをビルドし、API は最後にビルドするため、全体のロールアウトには 1 時間近くかかることがあります。データを保持するスタックに新しい Blueprint を同期する前に、[すでに稼働中のスタックのアップグレード](https://github.com/bex-co/beancount-io/tree/main/deploy/bex#upgrading-a-stack-that-is-already-running)を読み、まずバックアップしてください。

## バックアップと復元

台帳は Gitea のディスク上の Git リポジトリです。アカウント、パーソナルアクセストークン、設定はマネージド Postgres にあります。それぞれを独自の方法でバックアップしてください。

### 台帳

ミラークローンは、台帳のファイルと履歴の完全なバックアップです。

```zsh
git clone --mirror https://<your API address>/git/<owner>/<ledger>.git
```

`bea cloud git setup` を実行したマシンで、または **bea なしで Git を使う**のトークンヘルパーを使って実行します。復元するには、台帳がまだ一覧に表示されている場合はダッシュボードで削除し、同じ名前で作成します。サーバーは台帳の main ブランチへの強制プッシュを拒否するため、`bea` を使わない場合は `ledger.write` を持つトークンを使って、新しい台帳の最初のコミットの上にバックアップをマージします。

```zsh
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` を継続的にバックアップし、以前の時点の状態に復元できます。復元は新しいデータベースに対して行われ、その場では決して行われないため、そのデータベースをスタック自身のデータベースにコピーし直します。

1. bex で `beancount-backend-db` を開き、**Recovery** を選択し、少なくとも 10 分前の時刻を選んで復元します。bex はその時点のデータを持つ新しいデータベースを作成します。
2. 復元中に何も書き込まないよう、`beancount-api` と `beancount-gitea` を一時停止します。
3. PostgreSQL 16 の `pg_dump` と `pg_restore`（`postgres:16` Docker イメージには両方含まれています）でデータをコピーし直します。両端とも `beancount-backend-db` の外部接続文字列を使用し、コピー先にはホストだけをコピーのものに変更します。コピー用に bex が表示する接続情報は使用しないでください。それらは復元されたデータを読み取れないデータベースとユーザーを指しています。

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

   `pg_restore` は `vector` と `pg_stat_statements` 拡張機能を削除できない可能性があると報告しますが、これらのエラーは想定内です。コピーの証明書がまだ発行中の場合、`COPY_URL` に `?sslmode=verify-full` を追加し、コピー用に bex が表示する CA を `~/.postgresql/root.crt` として保存してください。接続がタイムアウトする場合は、再試行してください。
4. `beancount-gitea` と `beancount-api` を再開し、コピーを削除します。

## ワークスペースから出るもの

スタックは Beancount.io にアナリティクスやテレメトリを送信せず、ブラウザのアナリティクススクリプトはビルドから除外されています。私たちが知る限り、唯一の外向きリクエストは次のとおりです。

- **パスワード漏洩チェック:** 新しいパスワードの SHA-1 ハッシュの最初の 5 文字を、k-匿名性によってチェックするため、パスワードもアカウントも明らかになりません。
- **アバター:** ブラウザが、ユーザーのメールアドレスのハッシュによって Gravatar に画像を要求します。
- **フィード:** Beancount.io のブログと変更履歴のフィードで、受け取るのは言語設定のみです。
- **価格フィード:** 台帳がマネージド価格 URL を含む場合にのみ、beancount.io へのリクエストが発生します。
- **あなたの統合機能:** 接続したものすべて、例えばモデルプロバイダー、SendGrid、S3、Plaid、アイデンティティプロバイダーなど。

各リクエストがいつ発生するかは、[PRFAQ006 のプライバシー表](https://github.com/bex-co/beancount-io/blob/main/docs/prfaqs/PRFAQ006-self-host-on-bex.md#12-is-my-data-private)に記載されています。あなたのサービス、ディスク、データベースは bex のインフラストラクチャ上で、bex の[プライバシーポリシー](https://bex.co/privacy-policy)と[利用規約](https://bex.co/terms-of-service)の下で動作します。bex は Beancount.io を手がける Stargately, Inc. が構築しています。ホスト型の Beancount.io サービスはあなたのスタックとは別物で、そのシークレットを一切保持しません。

## スタックを削除する

:::warning
リソースを削除すると、請求が停止し、データも一緒に削除されます。まずすべての台帳をクローンしてください。
:::

上記のとおりにバックアップした後、bex で 6 つのリソースを削除し、続いて Blueprint を削除します。スタックを保持したまま自分のアカウントだけを削除するには、[ホスト型サービス](https://beancount.io/ja/docs/request-to-delete-account)と同様に **Settings → General → Danger Zone** で削除します。唯一のアカウントを削除すると、サインアップが再び開きます。

## 代わりに自分のサーバーで動かす

[Docker デプロイメント](https://github.com/bex-co/beancount-io/tree/main/deploy/docker)は、自分が管理する任意のサーバーで同じスタックを動かします。[bex デプロイメントのノート](https://github.com/bex-co/beancount-io/tree/main/deploy/bex)では、このガイドのすべての設定をより詳しく説明しています。

問題が発生しましたか？ [GitHub issue](https://github.com/bex-co/beancount-io/issues) を開くか、[Beancount Telegram チャット](https://t.me/beancount)で質問してください。
