Set up CloudBridge

Installation

Download the latest build from the Releases page:

Linux and Intel Mac binaries are not published, and source builds on those platforms are not guaranteed to work. Source builds require Rust 1.95 or newer; current stable is recommended for development. CI checks the declared minimum Rust version in a separate, non-blocking job. macOS needs Xcode Command Line Tools and CMake; Windows needs C++ build tools and the Windows SDK's fxc.exe on PATH. See development setup before building:

git clone https://github.com/JetSquirrel/cloudbridge.git
cd cloudbridge
cargo build --release
cargo run --release

Configuration

A source reaches the ledger through a billing API, through the bill export its console produces, or both. Only the first kind needs credentials; for the rest, add the account and go straight to Bill file import.

AWS

1. Create an IAM user with Cost Explorer access.
2. Review the policy below: it grants only the Cost Explorer action used by this client, ce:GetCostAndUsage. STS account validation requires no additional permission grant. Scope permissions to your needs; see permission templates.
3. Generate an Access Key ID and Secret Access Key.
4. Add the account in CloudBridge.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ce:GetCostAndUsage"
            ],
            "Resource": "*"
        }
    ]
}

AWS Cost Explorer charges per API request. The freshness window reduces repeated queries, but cost depends on accounts, periods and manual refreshes; there is no fixed daily cost guarantee. Check AWS pricing for current rates.

Alibaba Cloud

1. Open the RAM console and create a RAM user for API access.
2. Attach the built-in AliyunBSSReadOnlyAccess system policy.
3. Create an AccessKey for the user.
4. Add the account in CloudBridge.

The billing API has no per-query fee documented here; check Alibaba Cloud's current terms. Bill imports can provide finer model-level detail than the API.

DeepSeek

1. Open platform.deepseek.com and create an API key.
2. Add the account in CloudBridge using that key.

DeepSeek's API reports granted and topped-up balances, not a spending breakdown. For spending detail, import the console's download; see Bill file import. A key used for balance queries may also authorize paid model requests, so protect it and review its permissions.

Volcengine, OpenAI and Anthropic

These sources currently use file imports, not billing APIs. Add an account with a name, then import its provider export; no credentials are needed. Azure and Google Cloud are not currently supported. See the roadmap for planned work, without a promised release date.

Bill file import

A bill export downloaded from a provider's console parses into the same ledger rows a fetch produces. Downstream — totals, charts, alerts, attribution — an imported month is indistinguishable from a fetched one. It is often the finer reading: Alibaba Cloud's billing API reports Model Studio (百炼) as one figure a month, while its export reports it per model, with token counts as a real pricing unit.

Importing

1. Download the export from the provider's console.
2. Go to Accounts and click Import bill on the account's row.
3. Pick the file. CloudBridge reports how many charges it wrote and which months it replaced.

DeepSeek's zip

Import DeepSeek's ZIP exactly as downloaded. CloudBridge reads the cost-*.csv inside it and ignores amount-*.csv, whose amount column contains token counts, not money.

Usage exports carry no money

A usage export with token counts but no monetary amounts is recorded with no billed cost and a cost basis of absent. CloudBridge does not turn token counts into estimated spend at list prices. A cost export retains a quantity only where exactly one token column is populated: input and output tokens have different prices and cannot be combined into one priced quantity.

If the import refuses the file

• "not UTF-8 text" — Alibaba Cloud and Volcengine consoles can produce GBK exports. Re-export as UTF-8 or save the file as CSV UTF-8 before importing.
• Unrecognized columns — parsers match known aliases for Chinese and English exports and provider field names. If a format has changed, report the error and column headers in an issue. Redact sensitive values; do not attach an unredacted bill.

Usage

Adding an account

1. Go to Accounts in the sidebar.
2. Pick the source and enter a name, plus credentials if it has a billing API. Volcengine, OpenAI and Anthropic ask for none.
3. Click Save.

Reading the Overview

The header carries a range control — MTD, 30d or 12m — and every number on the page is computed for the window you pick.

• The headline spend is net of credits: what you were actually charged. The gross usage and the credits that took it down are shown beside it.
• The chart, the change percent, Where it went and the biggest movers all run on gross usage. An account whose usage is fully covered by credits nets to about zero, and a trend drawn on that base is noise rather than information.
• The Unallocated figure is the share of usage that reaches no business line — the part of the bill you cannot yet explain.

Hovering a trend chart snaps to the nearest point and draws a guide line, a dot, and a tooltip with that bucket's date and amount.

One account at a time

Click an account's name on the Accounts page to drill into it: the same range control, a net / gross / credits stat row, that one account's daily or monthly usage trend, and a per-service table giving each service's share of the window and its change against the comparison window.

A balance-only source such as DeepSeek has no API-reported usage — see Bill file import for how its service rows arrive; until you import one, the page stays empty.

Attribution

The Attribution page draws the month as a Sankey: source, then service or model, then business line, with an explicit Unallocated node. Flows are gross usage — a net flow can be negative, which means nothing in a Sankey. A charge is assigned to a line by its business_line tag; without one it lands in Unallocated.

Choosing a reporting currency

Open Settings → Reporting to choose USD or CNY; USD is the default. Original charges retain their billing currency. A dated, built-in exchange-rate table converts amounts for display using a rate no later than the charge date. Rates are not live market data. Missing rates are reported rather than treated as 1:1, and changing the reporting currency does not rewrite the original charges.

Refreshing

The default freshness window is 24 hours; Settings → Refreshing offers 6, 12, 24 or 48 hours. Refresh fetches stale API-backed periods; Force Refresh bypasses the window and can incur additional provider charges. Neither overwrites imported months; re-import a corrected export to update them. Provider reporting delays still apply. See Bill file import.

Demo data

Settings → Demo data loads three sample accounts and twelve months of billing history. Demo accounts use a demo- prefix, have no credentials and are skipped by provider refreshes. Use the same page to clear them when you are ready to connect your own data.

Alerts & rules

Rules are evaluated against the ledger when the app opens and after each refresh. They do not run while the app is closed; opening the Alerts page re-checks whether open alerts have resolved. Three rules ship enabled; review their settings on the Rules page and disable rules you do not need.

Alerts include the measurements behind the condition: spend and baseline, balance and floor, or unallocated share. Projections are estimates based on recent data, not guaranteed month-end costs. You can snooze or dismiss an alert; open alerts are marked resolved when the next evaluation finds their resolution condition met.

Data Storage

The desktop app stores billing data and configuration in the application-data directory. Default locations are:

• billing.duckdb — billing ledger, including original charge currencies
• cloudbridge.duckdb — account records, budgets, rules and alert state
• raw/ — retained provider responses and imported files, partitioned by source, account and billing period, for reprocessing after a mapping correction
• config.json — application configuration, including reporting currency, theme and refresh interval

Backups and inspection

Quit CloudBridge before copying or directly opening its databases. Back up the entire application-data directory, including both databases, config.json and raw/, rather than just the ledger. Restore the files with the app closed. Saved credentials are in the OS keyring, not this backup; on another machine, enter provider credentials again.

The app does not encrypt the ledger or raw billing files. Use OS disk encryption and protect backup copies. Query a copy of the DuckDB ledger for analysis rather than modifying the app's live database. Backups from versions before 0.2.0 may also contain legacy encrypted credentials and their configuration key; treat those as sensitive.

Security

• Saved provider credentials are held in the OS keyring, separate from the billing databases: Windows Credential Manager or macOS Keychain. Linux source builds use Secret Service where available.
• The app uses credentials to authenticate requests directly to configured providers. A key's permissions depend on its provider and scope; using it in CloudBridge does not make it read-only.
• There is no CloudBridge sync service or telemetry. Local bill imports do not call provider billing APIs.
• Billing databases and raw files are not encrypted by the app. Protect the machine and backups with OS disk encryption and appropriate access controls.
• Before sharing logs, screenshots or sample exports, redact credentials, account identifiers, resource names, tags and other private billing details.

Questions the docs don't answer? Open an issue.