FREE SELF-HOSTING · GET STARTED

From one install command
to your first request.

Self-host on Linux or macOS. Up and running without a sales call.

01

Prepare your environment

Prepare Linux amd64/arm64 or macOS Intel/Apple silicon, plus Docker, Compose v2 with up --wait, Buildx, Bash, OpenSSL, curl, and tar. Start the Docker runtime on Mac and do not use sudo for installation. The installer checks dependencies; it does not install Docker.

02

Install your gateway

Obtain the complete application source from the official repository. Run the command below at the BOS API application root. Go serves both the frontend and API, without Nginx. Allow inbound TCP 18080 for public access; omit --public for local-only access.

Get the source ↗
Run at the application source root
./install.sh --local --public --port 18080

This command shares its source with the maintained installation guide. Before upgrading, back up configuration and data, obtain the target source, then rerun the command. --local does not fetch code.

Full installation and access checks
03

Initialize administration

Find the console and first-login details in the installer output. Complete administrator login and verification in your gateway, then save the client-accessible endpoint under Settings > API address. This website does not request administrator credentials.

Read the guide
04

Connect an upstream and model

Bring your own provider account or channel. Configure the provider, Base URL, protocol, and credential, then add an available model and verify its status. Self-hosted software does not include upstream accounts or model credits.

Read the guide
05

Configure an organization and API key

Assign models and channels to an organization. Create an application key with model restrictions, QPS, and rolling quotas. Save its connection details and keep upstream credentials out of clients.

Read the guide
CONFIGURATION WALKTHROUGH

One connected setup.
Your first model request.

Upstream channel → Organization → API Key → Verification. All data is fictional; this demo never connects to a live gateway.

  1. Connect a provider and model

    Provider
    Demo provider
    Base URL
    https://provider.example.com/v1
    Model
    demo-model
    Upstream credential
    [DEMO ONLY]

    Configure a channel, protocol, and model in provider and model management. Check availability.

    Read the guide
  2. Assign explicit access

    Organization
    Demo Engineering
    Allowed channel
    Demo provider
    Allowed model
    demo-model

    Create Demo Engineering and assign the configured channel and model. Unassigned resources remain outside its access scope.

    Read the guide
  3. Create a scoped application key

    Name
    demo-workspace
    Organization
    Demo Engineering
    Model restriction
    demo-model
    QPS
    5
    Rolling quota
    10,000 tokens / 24h
    Key
    sk-demo-••••

    Select that organization, set the name, model restriction, QPS, and rolling quota, then review connection parameters. These limits are sample settings.

    Read the guide
  4. Close the loop with a request

    Request ID
    req_demo_01
    Model
    demo-model
    Key
    demo-workspace
    Result
    200 OK · 128 tokens

    Use this key with the allowed model, then match the request ID, status, and tokens in usage and request records.

    Read the guide

Illustrative console structure and sample data. Follow your deployed console and its versioned documentation.

06

Make your first request

Set your own gateway endpoint, key, and authorized model in your terminal. These are placeholders; the website domain is not your deployed model API endpoint.

First request · Placeholders
export BOS_BASE_URL='https://gateway.example.com/v1'
export BOS_API_KEY='<YOUR_GATEWAY_KEY>'
export BOS_MODEL='<YOUR_ALLOWED_MODEL_ID>'
curl "$BOS_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $BOS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"model":"'"$BOS_MODEL"'","messages":[{"role":"user","content":"Hello"}]}'

After success, inspect the response and match the model, key, status, and tokens in gateway usage and request records. For errors, use the checks below.

API integration and request examples
07

Connect your client

Follow the CC Switch import guide, or use Vary AI to manage client configurations.

08

Troubleshoot common issues

Missing dependencies / install failure
Check Docker, Compose, Buildx, and ports. Resolve the installer’s dependency errors and avoid a second default instance.
No available channel model
Check the enabled channel, model ID, upstream credentials, and protocol.
401 / 403 access denied
Check the gateway key, organization access, allowed models, and providers.
429 rate or quota limit
Check key/organization QPS, rolling quotas, and upstream balance.
Security policy block
Use the request ID to review security events, rules, coverage, and actions. Resolve the cause rather than bypassing protection.
Open troubleshooting

Need team or enterprise support?

Explore plans and sales
BOS API · TYPEX

Sales consultation is unavailable

Sales reception could not be initialized. Please try again later. Documentation and free self-hosting remain available.

Read the docsSelf-host for free