Available commands
Quick reference for every Bito Governor command, for both the Docker and the Kubernetes self-hosted deployments.
This page is a quick reference for the commands that run and operate a self-hosted Bito Governor, whether you run it with Docker on a single machine or with Kubernetes in a cluster.
Each deployment uses a different set of commands, so go to the section that matches yours:
Commands for self-hosted Bito Governor with Docker, for an install on a single machine, using
bito-gateway-ctl.Commands for self-hosted Bito Governor with Kubernetes, for an install in a cluster, using
helmandkubectl.
Both self-hosted deployments run the same gwctl command inside the gateway, so each section repeats it with the prefix that deployment needs.
The examples use bito-gateway as the namespace and gw as the Helm release name, matching the setup guides. Substitute your own where they differ.
For the full setup procedures, see Set up Bito Governor (self-hosted with Docker) and Set up Bito Governor (self-hosted with Kubernetes).
Commands for self-hosted Bito Governor with Docker
Install
curl -fsSL https://gwinstall.bito.ai/latest/install-standalone.sh | bash
Installs Governor on Linux or macOS.
irm https://gwinstall.bito.ai/latest/install-standalone.ps1 | iex
Installs Governor on Windows, in PowerShell.
Everything installs under ~/.bito-gateway, or %USERPROFILE%\.bito-gateway on Windows. Set BITO_GW_HOME to install elsewhere, and PORT to serve on a port other than 8788.
Manage the service
bito-gateway-ctl is installed on your PATH, including on Windows through a .cmd shim, and runs from any directory.
bito-gateway-ctl status
Reports whether Governor is running.
bito-gateway-ctl health
Runs the /healthz check and a deep self-check.
bito-gateway-ctl logs
Follows the gateway logs. Press Ctrl+C to stop.
bito-gateway-ctl start
Starts Governor, and applies any changes to the .env file.
bito-gateway-ctl stop
Stops Governor and keeps your data.
bito-gateway-ctl restart
Restarts Governor.
bito-gateway-ctl update
Pulls a newer image and restarts.
Configure from the command line
gwctl lives inside the gateway container, and bito-gateway-ctl forwards to it.
bito-gateway-ctl gwctl quickstart
Walks through creating a workspace, key, provider account, and route.
bito-gateway-ctl gwctl connect <tool>
Prints the setup for a coding tool. Accepts claude, cursor, codex, copilot, cline, continue, and aider.
bito-gateway-ctl gwctl doctor
Validates the database, schema, and key encryption key.
bito-gateway-ctl gwctl <command> -h
Shows help for any command.
Manage admins
bito-gateway-ctl gwctl admin create --role global
Creates an admin with full access. Prints the token once.
bito-gateway-ctl gwctl admin create --role workspace --workspace <id>
Creates an admin scoped to one workspace.
bito-gateway-ctl gwctl admin list
Lists existing admins.
bito-gateway-ctl gwctl admin revoke <id>
Revokes an admin.
Back up
mysqldump bito_gateway > backup.sql
Backs up every workspace, key, account, route, and your encrypted provider credentials.
Back up CRYPTO_ENV_KEK_KEY from ~/.bito-gateway/.env alongside the dump. Without it, the credentials in the dump cannot be decrypted.
Uninstall
bito-gateway-ctl uninstall
Removes the containers and keeps your database volume and secrets.
bito-gateway-ctl uninstall --purge
Also deletes the database volume and the key encryption key. This is irreversible.
Native systemd installs
On a native systemd install rather than Docker, manage the service directly. gwctl is on your PATH, so call it without the wrapper.
sudo systemctl start bito-gateway
Starts Governor. Also accepts stop, restart, and status.
journalctl -u bito-gateway -f
Follows the logs.
Commands for self-hosted Bito Governor with Kubernetes
Check your cluster first
kubectl config current-context
Shows which cluster your commands will apply to. Check this before installing.
kubectl config get-contexts
Lists every cluster you can reach.
Install
helm install gw oci://registry-1.docker.io/bitoai/bito-gateway-helm --namespace bito-gateway -f my-values.yaml
Installs with your own values file.
helm show chart oci://registry-1.docker.io/bitoai/bito-gateway-helm
Shows what a chart version contains, without installing it.
helm pull oci://registry-1.docker.io/bitoai/bito-gateway-helm --untar
Downloads and unpacks the chart, including the example values files.
ls bito-gateway-helm/values-*.yaml
Lists the example values files after unpacking.
Add --version X.Y.Z to any of these to pin a chart version.
Check the deployment
kubectl -n bito-gateway rollout status deploy/gw-bito-gateway --timeout=5m
Waits for the gateway to finish rolling out.
kubectl -n bito-gateway get pods
Lists every pod and its status.
kubectl -n bito-gateway get svc
Lists the services and their cluster IPs.
kubectl -n bito-gateway logs deploy/gw-bito-gateway
Shows the gateway logs.
kubectl -n bito-gateway logs deploy/gw-bito-gateway-mysql
Shows the database logs.
helm list -n bito-gateway
Lists the Helm releases in the namespace, with their status and chart version.
Reach the gateway
kubectl -n bito-gateway port-forward svc/gw-bito-gateway 8788:8788
Makes Governor available on your own machine at http://localhost:8788, while the command runs.
kubectl -n bito-gateway get secret bito-gateway-secrets -o jsonpath='{.data.ADMIN_TOKEN}' | base64 -d
Prints your admin token. Kubernetes stores Secret values base64 encoded, so base64 -d decodes it.
Configure from the command line
gwctl ships inside the gateway image and reads the database settings the pod already has. Substitute the workspace ID that workspace create prints.
kubectl -n bito-gateway exec deploy/gw-bito-gateway -- gwctl workspace create --name demo
Creates a workspace and prints its ID.
kubectl -n bito-gateway exec deploy/gw-bito-gateway -- gwctl key create --workspace <ID> --name demo
Creates a gateway key. Prints the gw_sk_ key once.
kubectl -n bito-gateway exec deploy/gw-bito-gateway -- gwctl account add --workspace <ID> --provider anthropic --key <YOUR PROVIDER KEY>
Adds a provider account.
kubectl -n bito-gateway exec deploy/gw-bito-gateway -- gwctl route add --workspace <ID> --alias '*' --provider anthropic
Adds a route.
kubectl -n bito-gateway exec deploy/gw-bito-gateway -- gwctl connect <tool>
Prints the setup for a coding tool.
kubectl -n bito-gateway exec deploy/gw-bito-gateway -- gwctl doctor
Validates the database, schema, and key encryption key.
Manage admins
kubectl -n bito-gateway exec deploy/gw-bito-gateway -- gwctl admin create --role global
Creates an admin with full access. Prints the token once.
kubectl -n bito-gateway exec deploy/gw-bito-gateway -- gwctl admin create --role workspace --workspace <id>
Creates an admin scoped to one workspace.
kubectl -n bito-gateway exec deploy/gw-bito-gateway -- gwctl admin list
Lists existing admins.
kubectl -n bito-gateway exec deploy/gw-bito-gateway -- gwctl admin revoke <id>
Revokes an admin.
Upgrade and roll back
kubectl -n bito-gateway rollout restart deploy/gw-bito-gateway
Rolls the pods. Run this after rotating a value in a Secret you own, because the chart cannot see that change.
helm rollback gw <revision> -n bito-gateway
Returns the pods to a previous revision. The database keeps the newer schema.
helm history gw -n bito-gateway
Lists the revisions you can roll back to.
Uninstall
helm uninstall gw -n bito-gateway
Removes the release and keeps your data. The PersistentVolumeClaims are annotated to be kept.
kubectl -n bito-gateway delete pvc gw-bito-gateway-mysql
Deletes the database volume. This is irreversible.
kubectl -n bito-gateway delete pvc gw-bito-gateway-redis
Deletes the counter store volume.
kubectl -n bito-gateway delete job,configmap,serviceaccount,secret gw-bito-gateway-migrate --ignore-not-found
Removes the migration objects, which Helm leaves behind.
What's next
Contact support@bito.ai for deployment assistance
Last updated