Ctrlk
Sign inVisit bito.aiVideo Library
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Set up Bito Governor (self-hosted)

Run Bito Governor inside your own network. Install it on a single host with Docker, configure your workspace, and point your coding tools at it, with all traffic staying local.

Install Bito Governor on one machine, sign in, connect your AI coding tools, and operate it. This is the self-hosted, single-node path (gateway + database on one box, via Docker). No source code or build tools needed — just Docker.

What Bito Governor is: a gateway that sits between your AI coding tools (Claude Code, Cursor, Codex, …) and the LLM providers. You point your tools at one gateway URL + key; the gateway routes to the right provider, and meters usage and cost per workspace.

Prerequisites

You need the following:

  • Docker — Docker Desktop (macOS/Windows) or Docker Engine + Compose (Linux). That's the only prerequisite; the gateway and its database run as containers.

  • A free port — the gateway serves on 8788 by default (set PORT to change it).

  • An API key for each LLM provider you use, such as Anthropic, OpenAI, Groq, or Google. Governor sends requests to your own provider accounts.

  • The model names your coding tools request, such as claude-opus-4-8. Model names are case sensitive.

  • AI Architect MCP URL and access token, if you enable AI Architect. Both are available in your Bito account.

Step 1: Install

Run the one-liner for your OS. It pulls the Bito Governor image, brings up the stack, generates its secrets, signs you in, and prints everything you need.

Linux / macOS

curl -fsSL https://gwinstall.bito.ai/latest/install-standalone.sh | bash

Windows (PowerShell)

irm https://gwinstall.bito.ai/latest/install-standalone.ps1 | iex

Everything installs under a home directory — ~/.bito-gateway (Windows: %USERPROFILE%\.bito-gateway). Set BITO_GW_HOME to install elsewhere.

Prefer a native Linux service (systemd) instead of Docker? See docs/dev/DEPLOY_RUNBOOK.md in your bito-gateway installation folder.

Step 2: What you get

When it finishes you'll see a "ready" block like this — save what it tells you to:

  • The admin token (gw_admin_…) is your Admin UI login — copy it now (it's shown once).

  • The KEK (CRYPTO_ENV_KEK_KEY) is the most important secret to back up: it encrypts every provider key you'll add. Losing it means the stored provider keys can't be decrypted. Copy it to your password manager.

Step 3: Sign in to the admin UI

  1. Go to http://<host>:8788/admin, replacing <host> with the address of the machine running Governor.

  2. Enter the admin token you recorded in Step 2.

  3. Create a workspace and open it — your tenant (like a team/project).

The workspace opens on the Dashboard. The left sidebar contains the following pages: Dashboard, Documentation, Reports, Keys, Members, Accounts, Routes, Features, Limits, Prices, Test, and Audit.

Most configuration pages contain a form at the top and a table of existing entries below it. Complete Steps 4 to 9 in the admin UI.

To perform the same configuration from a terminal instead, run bito-gateway-ctl gwctl quickstart.

Step 4: Add a provider account

A provider account stores one LLM API key. Add an account for every LLM provider you use, such as Anthropic, OpenAI, Groq, Fireworks, OpenRouter, Together, Google, etc. Add more than one account for the same provider when you hold several keys, for example one per team or environment.

  1. In the left sidebar, click Accounts.

  2. In the Add account form, complete the following fields:

Field
Description

provider

The provider you are connecting.

name

A name for this account, for example prod or my-vllm. The name appears in routes, reports, and prices.

key

Your provider API key. Governor stores it envelope encrypted under the key encryption key on your host.

base url

The provider endpoint. The default is filled in for each provider. Override it for a proxy, a regional endpoint, or a self-hosted model server.

  1. Click Add.

The account appears in the Accounts table with the actions edit, test, reveal, and remove, and a toggle to enable or disable it.

  1. Click test on the new account.

test checks the connection to the provider to verify the key and endpoint.

To forward the credential supplied by the caller, leave the key field blank. This is passthrough mode.

Azure accounts can authenticate with an Entra ID service principal instead of an API key.

reveal displays a stored provider key. Every use is recorded in the audit log.

Examples

Expand to view examples

Each example states a goal, then the values to enter in the Add account form.

Connect a provider

Add your organisation's Anthropic key.

provider
name
key
base url

anthropic

prod-anthropic

your Anthropic API key

leave the prefilled value

Governor fills in base url when you select a provider. Change it only for a proxy, a regional endpoint, or a server you host yourself.

Separate production and staging spend

Bill staging traffic to a different key from production.

provider
name
key
base url

anthropic

prod-anthropic

your production key

leave the prefilled value

anthropic

staging-anthropic

your staging key

leave the prefilled value

Add the provider twice under different names. Routes select an account by name, and reports show which account served each request, so spend separates cleanly.

Connect a model you host yourself

Send requests to a model running on your own inference server.

provider
name
key
base url

openai

my-vllm

your server's key, or leave empty if it needs none

your inference server address

Any server that implements the OpenAI API works here.

Forward the caller's own key

Apply routing and reporting to traffic without storing provider keys centrally.

provider
name
key
base url

openai

passthrough-openai

leave empty

leave the prefilled value

An account with no key runs in passthrough mode, where Governor forwards the credential the caller supplied.

Step 5: Add a route

A route maps a model alias your coding tool requests to a provider account and an upstream model.

  1. In the left sidebar, click Routes.

  2. In the Add route form, complete the following fields:

Field
Description

alias

The model name your coding tool requests, for example claude-opus-4-8 or claude-*. Enter * to match any model.

provider

The provider that serves the request.

account

The provider account used.

model (or *)

The upstream model sent to the provider. Enter * to forward the model name the tool requested.

api

The API dialect. Leave it on auto to follow the caller.

priority

The failover tier. Lower numbers are used first. Default 0.

weight

The share of traffic within a tier. Default 1.

retries

Retry attempts for this target. Leave blank to use the gateway default.

  1. Click Add route.

Routes are grouped by alias in the table below the form. Each group lists its targets with provider, model, account, priority, weight, retries, an enable toggle, and a health state. Priority, weight, and retries are editable inline.

A target marked cooling is in a cooldown period after repeated failures. Governor sends its traffic to the next available target until it recovers.

Wildcard and exact aliases

A route with * as both the alias and the upstream model passes every request through to the selected account unchanged.

Exact aliases take precedence over wildcards. A route for claude-opus-4-8 is used instead of the * route, and all other models continue to pass through.

Failover and load balancing

Add the same alias again with a different provider account.

  • Governor uses the lowest priority tier first.

  • Within a tier, traffic is distributed by weight.

  • Targets with the same priority receive requests in turn.

  • If a provider returns errors, Governor sends the request to the next available target.

Examples

Expand to view examples

Each example states a goal, then the values to enter in the Add route form.

Route every model to one provider

Send all traffic to a single account, without naming each model.

alias
provider
account
model
priority

*

anthropic

prod-anthropic

*

0

Type the asterisk in both fields. * in the alias matches any model, and * in the model field forwards the model name your tool sent. Add this route first, so that every request reaches a provider while you configure the rest.

Route a model family to one account

Send every version of Sonnet to an Azure account.

alias
provider
account
model
priority

claude-sonnet-*

azure

azure-prod

*

0

The wildcard matches claude-sonnet-5, claude-sonnet-4-5, and later versions, so new releases need no new route. This alias is more specific than *, so it overrides the catch-all.

Fail over to a second provider

Serve Opus 5 from Anthropic, and switch to Azure while Anthropic is unavailable.

alias
provider
account
model
priority

claude-opus-5

anthropic

prod-anthropic

claude-opus-5

0

claude-opus-5

azure

azure-prod

claude-opus-5

1

Add the alias once per account. Priority 0 takes all traffic. When those requests fail, Governor moves them to priority 1 until the primary account recovers.

Split traffic across two accounts

Spread Opus 5 traffic so that neither account reaches its rate limit.

alias
provider
account
model
priority
weight

claude-opus-5

anthropic

prod-anthropic

claude-opus-5

0

3

claude-opus-5

azure

azure-prod

claude-opus-5

0

1

Equal priorities put both targets in the same tier, and the weights send three requests to Anthropic for every one to Azure. Set both weights to 1 for an even split.

Serve a request with a different model

Serve Opus 5 requests with a lower-cost model, with no change on any developer machine.

alias
provider
account
model
priority

claude-opus-5

anthropic

prod-anthropic

claude-sonnet-5

0

The alias is the model your tool requests. The model is what serves the request. Your tools continue to request Opus 5, and Governor serves those requests with Sonnet 5. Edit the route to reverse it.

Step 6: Create a gateway key

A gateway key authenticates a coding tool to Governor. Provider keys stay in the Bito UI.

  1. In the left sidebar, click Keys.

  2. In the Create key form, enter a name that identifies the team or tool that will use the key.

  3. Click Create.

  4. Copy the key.

The key starts with gw_sk_ and is displayed once. Governor stores keys hashed and cannot display them again.

The Keys table lists each key by ID, prefix, and name, with an enable toggle and a revoke action. Create one key per team or tool so that you can revoke one without affecting the others.

Step 7: Enable features

Features are server-side capabilities that Governor runs inside a request. Two features are available, and both are optional.

The Features table lists each enabled feature with its alias, state, whether a token is stored, and its MCP URL, with edit and disable actions. Enabled features also appear as badges against each alias on the Routes page.

AI Architect

AI Architect serves system context from a live knowledge graph of your engineering system, covering code, business context, and tribal knowledge. Governor applies it inside each request, so your coding tools receive that context as they work.

  1. In the left sidebar, click Features.

  2. In the Configure feature form, select ai_architect from the feature list.

  3. Complete the following fields:

Field
Description

alias

Leave blank to enable the feature across the workspace, or enter a route alias such as claude-* to scope it to that alias.

MCP URL

Your AI Architect MCP endpoint. If left empty, Governor falls back to a built-in stub.

Steering text

Overrides the default instructions Governor sends with AI Architect. Leave blank to use the default.

Tool allowlist

Restricts which AI Architect tools the model may call, one tool name per line. Leave empty to allow all.

Max hops

The server-side hop budget. Default 16. See Max hops below.

Max hops per request

The combined hop budget across every AI Architect lookup in one request. Leave blank to use the gateway default.

Prompt-cache injection

Caches what Governor sends with AI Architect on Anthropic, so repeat hops bill at the cache-read rate. Leave on Use default to follow the gateway-wide setting.

Architect model (sub-agent)

Runs the AI Architect lookups on a cheaper route alias while the route model writes the answer, for example gemini-3.1-flash-lite or gpt-5.6-luna. Leave blank to run them on the request's own route model.

Run Architect in-loop (legacy)

Runs the AI Architect tools inline on the route model instead of the default sub-agent mode. Ignored when an Architect model is set.

Quality mode

Sets how deeply AI Architect researches a question. Choose one of the following:

  • Use default: follows the gateway-wide setting.

  • Normal: uses the standard prompts and hop budget. This is the default.

  • High quality: researches deeper and more thoroughly, at roughly twice the AI Architect cost.

MCP token

Your AI Architect access token. Leave blank to keep the token already stored.

  1. Click Enable.

Changes apply to the next request. Users take no action.

Setting Architect model (sub-agent) to a cheaper alias moves the AI Architect lookups off your main model while the route model still writes the answer. This reduces the cost of a request that takes several hops.

Max hops

Some questions require several passes to answer. A question about how your repositories connect requires Governor to retrieve the repository list, then look up the dependencies of each repository. Each pass is a hop.

Two settings cap this work, and both apply at the same time.

Setting
Scope

Max hops

One AI Architect lookup.

Max hops per request

Every AI Architect lookup in one request, combined.

A single request can trigger more than one lookup, so Max hops per request is what stops a complex request from running up cost through repeated lookups that each stay within their own limit.

Governor stops as soon as it has an answer, so both values are ceilings rather than fixed costs.

Max hops
Use

16

Default. Suitable for most workspaces.

30 or higher

Workspaces with several hundred repositories, or teams that ask broad cross-repository questions.

Raise Max hops if answers come back incomplete. Leave Max hops per request blank to use the gateway default, and set it when you want a firm ceiling on how much AI Architect work a single request can do. Each hop consumes tokens.

Reasoning downgrade

reasoning_downgrade lowers the reasoning effort of a request by exactly one level. Reasoning tokens bill at the output rate, so a lower level reduces the cost of the request.

  1. In the left sidebar, click Features.

  2. In the Configure feature form, select reasoning_downgrade from the feature list.

  3. Leave alias blank to apply the feature across the workspace, or enter a route alias such as claude-* to scope it to that alias.

  4. Click Enable.

Apart from alias, the feature has no settings.

Governor leaves a request unchanged when it already uses the lowest or second-lowest reasoning level, or when it sends no reasoning at all.

Step 8: Connect a coding tool

In the left sidebar, click Documentation. Your own base URL is displayed at the top of the page, and the links below it jump to the four sections on the page.

Section
Contents

Get started

Your base URL, a field for your gateway key, and how to authenticate.

Use it

Ready-made curl, Python, and JavaScript requests, and Try it for sending a live request.

Connect a tool

Copy-paste setup for each supported coding tool.

Reference

Endpoints, your route aliases, and how usage and cost are reported.

To connect a coding tool:

  1. In the Get started section, paste a gateway key into the key field. Every example on the page fills in with your base URL and key. To generate a key here, click + Create test key.

  2. In the Connect a tool section, select your tool.

Setup is provided for Claude Code, Cursor, Cline (VS Code), Continue (VS Code / JetBrains), Aider, Codex CLI, GitHub Copilot CLI, Windsurf, Zed, and any OpenAI-compatible or Anthropic-compatible tool.

To print the same setup from a terminal, run bito-gateway-ctl gwctl connect with your tool name. The command outputs configuration values and changes no state.

The output contains your data-plane URL and the required environment variables, with a <YOUR_GATEWAY_KEY> placeholder. Replace it with the key you created in Step 6.

For Claude Code, set two environment variables and start the tool:

Replace HOST with the hostname or address of the machine running Governor. To configure a team, distribute these two variables using your existing developer environment tooling. If your traffic already passes through a central gateway, set them there instead.

Governor accepts requests on three endpoints:

Path
Dialect
Used by

/v1/messages

Anthropic Messages

Claude Code, Anthropic SDKs

/v1/chat/completions

OpenAI Chat Completions

Codex, most OpenAI-compatible tools

/v1/responses

OpenAI Responses

OpenAI Responses API clients

Authenticate with Authorization: Bearer <GATEWAY_KEY> or X-Api-Key: <GATEWAY_KEY>. The same gateway key works for all three dialects.

Claude Code reports that its connectors are disabled when it runs through Governor, because the session authenticates against Governor rather than a Claude account. This message is expected. AI Architect continues to work, because Governor serves it from the server side.

Operate the Bito Governor

Day-to-day, use the bito-gateway-ctl command (installed on your PATH — Windows too, via a .cmd shim). It works from any directory:

Run gwctl from the command line (it lives inside the gateway container — this wrapper forwards to it):

Uninstall:

On the native/systemd install, use sudo systemctl {start|stop|restart|status} bito-gateway + journalctl -u bito-gateway -f, and gwctl is already on your PATH directly.

Back up

Two things, together, are your whole Bito Governor:

  • The database — mysqldump bito_gateway on a schedule (it holds every workspace, key, account, route, and your encrypted provider secrets).

  • The KEK (CRYPTO_ENV_KEK_KEY, in ~/.bito-gateway/.env) — in your secrets manager. A database dump alone can't be decrypted without it.

Where to go next

  • The Admin UI Documentation tab — connection snippets for every tool, filled with your live URL/key, plus the API reference.

  • bito-gateway-ctl gwctl <command> -h — help for any CLI command.

PreviousSet up Bito Governor (Bito-hosted)NextOverview

Last updated