Quickstart

Install BudgetAI, connect a provider, start the gateway, and run your first budget-bound turn.

BudgetAI is a token-efficient agent runtime for the terminal, a local Web UI, and messaging channels. This guide takes you from zero to your first completed turn.

Prerequisites

BudgetAI installs into an isolated environment and manages its own Python, so you do not need Python set up in advance. You only need uv.

RequirementNotes
uvInstalls and runs BudgetAI in its own tool environment
A provider keyOpenRouter, OpenAI, Anthropic, or any supported backend
Python 3.12+Managed automatically by uv

1. Install uv

curl -LsSf https://astral.sh/uv/install.sh | sh
. "$HOME/.local/bin/env"

On Windows PowerShell:

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
$env:Path = "$env:USERPROFILE\.local\bin;" + $env:Path

2. Install BudgetAI

uv tool install --python 3.12 "budgetai[recommended]"

The recommended profile pulls the on-device router and the local memory stack (ONNX runtime, tokenizers, and the ML router dependencies).

Set BUDGETAI_INSTALL_PROFILE=core to skip the router dependencies for a smaller install. You can enable routing later.

3. Connect a provider

budgetai onboard

Or run it non-interactively by passing the name of an environment variable that holds your key (never the key itself):

export OPENROUTER_API_KEY="sk-..."
budgetai onboard --provider openrouter --api-key-env OPENROUTER_API_KEY

4. Run the gateway

budgetai gateway run
# → http://127.0.0.1:18791/control/

You should see:

✓ gateway live on 127.0.0.1:18791
✓ router: recommended (on-device)
✓ memory + embeddings ready

5. Run your first turn

budgetai chat
# or a single one-shot turn:
budgetai agent -m "Summarize the README in this folder"

Every turn is routed to the cheapest capable model, verified, and recorded with a cost receipt.

Add a budget to any run with --max-usd. BudgetAI will stop or escalate before it breaks the ceiling. See Outcome Contracts.

Next steps

Next Use Cases & Recipes