Skip to content
Busbar Busbar

Deploy the binary (systemd)

Busbar is a single static binary with no runtime dependencies, so the VM / bare-metal deployment is: drop the binary on the host, give it config and secrets, and run it under systemd.

1. Download and verify

Section titled “1. Download and verify”

The one-line installer detects your platform and downloads the binary and the provider catalog:

Terminal window
BUSBAR_INSTALL_DIR=/usr/local/bin curl -fsSL https://getbusbar.com/install.sh | sh

Or fetch a specific release tarball manually and verify its build provenance before trusting it:

Terminal window
ver=1.4.0
base="https://github.com/GetBusbar/busbar/releases/download/v${ver}"
curl -fsSLO "${base}/busbar-x86_64-unknown-linux-gnu.tar.gz"


# Verify the artifact was built by the busbar release workflow (Sigstore/OIDC).
gh attestation verify busbar-x86_64-unknown-linux-gnu.tar.gz --repo GetBusbar/busbar


tar -xzf busbar-x86_64-unknown-linux-gnu.tar.gz
sudo install -m 0755 busbar /usr/local/bin/busbar
busbar --version

2. Place config and the provider catalog

Section titled “2. Place config and the provider catalog”
Terminal window
sudo useradd --system --no-create-home --shell /usr/sbin/nologin busbar
sudo mkdir -p /etc/busbar /var/lib/busbar
sudo curl -fsSL https://getbusbar.com/providers.yaml -o /etc/busbar/providers.yaml
sudo chown -R busbar:busbar /var/lib/busbar

Write /etc/busbar/config.yaml (see Configuration and Getting Started). Reference secrets as ${VAR} — never inline keys.

3. Secrets in an environment file

Section titled “3. Secrets in an environment file”

Keep provider keys and tokens out of the config, in a root-owned, 0600 env file:

Terminal window
# /etc/busbar/busbar.env   (chmod 600, owned by root)
ANTHROPIC_KEY=sk-ant-...
BUSBAR_CLIENT_TOKEN=a-long-random-string

4. The systemd unit

Section titled “4. The systemd unit”

/etc/systemd/system/busbar.service — runs as a non-root user with the rootfs read-only and privileges dropped:

[Unit]
Description=Busbar LLM gateway
After=network-online.target
Wants=network-online.target


[Service]
Type=simple
User=busbar
Group=busbar
EnvironmentFile=/etc/busbar/busbar.env
Environment=BUSBAR_CONFIG=/etc/busbar/config.yaml
Environment=BUSBAR_PROVIDERS=/etc/busbar/providers.yaml
# Fail fast: don't (re)start on an invalid config.
ExecStartPre=/usr/local/bin/busbar --validate
ExecStart=/usr/local/bin/busbar
Restart=always
RestartSec=2


# Hardening
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
PrivateTmp=true
ReadWritePaths=/var/lib/busbar
CapabilityBoundingSet=
AmbientCapabilities=


[Install]
WantedBy=multi-user.target
Terminal window
sudo systemctl daemon-reload
sudo systemctl enable --now busbar
curl -s http://localhost:8080/healthz && echo ok

5. Admin plane, TLS, upgrades

Section titled “5. Admin plane, TLS, upgrades”

  • Admin plane. The admin API (/api/v1/admin) runs on its own listener, loopback (127.0.0.1:8081) by default — reachable from the host, not the network. To manage it remotely, set admin_listen to an exposed address and configure admin_tls (mTLS); it refuses to boot otherwise. See Operations and the Admin API.

  • Inbound TLS. Terminate TLS at Busbar (tls block) or in front of it. See Operations → Inbound TLS.

  • Upgrade / reload. Validate first, then restart (or reload live via the admin API):

    Terminal window
    busbar --validate && sudo systemctl restart busbar

Multiple instances (HA)

Section titled “Multiple instances (HA)”

Busbar is stateless, so for high availability run N hosts behind a load balancer (nginx, HAProxy, or a cloud L4/L7 LB), each with the same config and each health-checked on GET /healthz. Any host serves any request. If you rely on session affinity, enable sticky sessions at the LB; and note that governance budgets/rate limits are enforced per-instance — for strict global enforcement, run a single instance and scale the box. See Running multiple instances (HA).