Configuration

burn has no config command. Settings live in a JSON file, and a few environment variables change where the files are and how prices are fetched.

The burn home

Everything is stored in ~/.burn by default. Set BURN_HOME to use another directory:

BURN_HOME=/tmp/burn-ledger burn proxy

The proxy, the reports, and the dashboard all read the same variable. If they use different homes, they see different ledgers.

File	Purpose
`burn.db`	SQLite database with the requests table.
`config.json`	Custom providers, price overrides, the budget, and an optional proxy port.
`prices.json`	The cached price list and its `fetchedAt` timestamp.

config.json and prices.json are created when they are first needed. Reading a report does not create them.

The config file

The file is pretty-printed JSON. Every key is optional; missing keys fall back to the built-in defaults.

{
  "providers": {
    "local": {
      "url": "http://127.0.0.1:11434/v1",
      "format": "openai"
    }
  },
  "prices": {
    "my-model": {
      "in": 0.5,
      "out": 1.5
    }
  },
  "budget": {
    "daily": 5,
    "block": true
  },
  "port": 8787
}

Key	Type	Meaning
`providers`	object	Custom providers, keyed by route name. Each value has `url` and `format` (`openai` or `anthropic`).
`prices`	object	Price overrides in USD per 1 million tokens. Each value has `in` and `out`. A key can be a model or `<provider>/<model>`.
`budget`	object or null	`{ "daily": <usd>, "block": <boolean> }`, or null.
`port`	number	Default proxy port for `burn proxy` and `burn env`. The UI port is separate.

The proxy reads config.json for each request, so changes to providers, prices, or the budget apply to the next request without a restart. If the file is not valid JSON, commands that read it fail with the path and the parse error rather than guessing.

Environment variables

Variable	Values	Effect
`BURN_HOME`	directory path	Base directory for `burn.db`, `config.json`, and `prices.json`. Defaults to `~/.burn`.
`BURN_OFFLINE`	`1` or `true`	Disables the price download. Cached or bundled prices are still used.
`BURN_PRICE_URL`	URL	Replaces the CloudPrice price list URL.
`BURN_DEBUG`	any non-empty value	Prints a stack trace for unexpected errors. Usage errors stay short.

These values are read by the process that runs burn. Setting BURN_OFFLINE in one shell does not change a proxy already running in another shell.

Ports

Service	Default	How to change it
Proxy	`8787`	`burn proxy --port <port>`, or `port` in `config.json`
Dashboard	`4747`	`burn ui --port <port>`

burn env accepts --port too, so the lines it prints match a proxy on a different port. The UI port is not read from config.json.

A port must be a whole number from 0 to 65535. On the proxy and UI, port 0 asks the operating system for a free port; burn prints the port it received. This is what burn run uses internally.

Database

The ledger is a SQLite database with one table, requests. The schema stores metadata only: timestamp, provider, model, tag, token counts, cost, latency, status, and the stream flag. There is no column for a prompt or a response.

The database uses SQLite's WAL journal mode. The file is not encrypted, so treat it like any other local file that contains your usage metadata.

burn reset --yes deletes every row, but leaves the file and the other settings in place. Deleting ~/.burn removes everything, including custom providers and the cached price list. The next command recreates what it needs.

The full field list is on the project page.