Installation
This guide walks through installing the Radicalbit AI Gateway with Docker Compose. It gets the full stack running on your machine in a few minutes.
This guide covers the open source edition, self-hosted with Docker. See Enterprise for the additional governance features available on top of it.
Prerequisites
- Docker, with Compose support (Docker Desktop, or Docker Engine plus the Compose plugin)
- Git
- An API key for at least one supported provider (e.g. OpenAI), to call a model once the gateway is running
1. Get the Code
Clone the repository:
git clone git@github.com:radicalbit/radicalbit-ai-gateway.git
cd radicalbit-ai-gateway
2. Add Your Provider Credentials
The gateway reads model credentials from a secrets.yaml file in the project root. Create it by copying the provided template:
cp secrets-dummy.yaml secrets.yaml
Then add your provider keys:
OPENAI_API_KEY: sk-your-key-here
Add one line per provider you plan to use. See Secrets Management for other ways to store credentials, including cloud secret managers.
3. Start the Stack
There are two ways to start the gateway:
Use pre-built images (fastest):
GATEWAY_TAG=latest docker compose up -d
Build from source:
docker compose up --build -d
Both commands start the same stack: the gateway, its UI, and the services it depends on. Wait 20-30 seconds for everything to become healthy, then open http://localhost:9000. You should see the Gateway UI.
4. What Gets Started
Docker Compose brings up these core services:
| Service | Port | Purpose |
|---|---|---|
| Gateway | 9000 | API and UI |
| Postgres | 5432 | Stores projects, routes, and configuration |
| Valkey | 6379 | Task queue (Celery broker) |
| Valkey Cache | 6380 | Backs the response cache (exact and semantic caching) |
| ClickHouse | 8123 / 9002 | Stores traces and metrics |
| OTel Collector | n/a | Forwards traces to ClickHouse |
| Metrics Worker | n/a | Processes usage metrics and alert rules |
A few optional tools are also started, useful for inspecting data while testing locally:
| Tool | Port | Purpose |
|---|---|---|
| Adminer | 8090 | Browse the Postgres database |
| ClickHouse UI | 5521 | Browse traces and metrics |
| RedisInsight | 5540 | Browse both Valkey instances (task queue and cache) |
5. Verify the Installation
Check that the gateway is healthy:
curl http://localhost:9000/health
Then open http://localhost:9000 in your browser. You should land on the Gateway UI with no projects yet. That's expected on a fresh install.
6. (Optional) Enable the AI Config Generator
The gateway can generate configuration from plain English, using an LLM. To enable it, set a real OpenAI API key in CONFIG_GENERATOR_OPENAI_API_KEY before starting the gateway.
docker-compose.yaml ships with a placeholder value (sk-123). Replace it with a real key, or the generator will not work.
See Basic Configuration for details.
Stopping the Gateway
docker compose down
To also remove stored data (database, cache, traces):
docker compose down -v
Next Steps
- Quick Start - Create your first project, route, and API key
- Basic Configuration - Understand the configuration format
- Secrets Management - Store credentials outside
secrets.yaml