Documentation

Get Gatway running

From an empty server to a developer shipping AI-assisted code with a full audit trail — usually under an hour.

Overview

Gatway has three parts:

The gateway exposes an OpenAI-compatible /v1/chat/completions endpoint, so existing tools and scripts can point at it without changes.

Deploy the gateway

Requirements: Ubuntu 22.04+, Python 3.11+, PostgreSQL 14+, Node 20 (to build the dashboard).

git clone <your-repo> /opt/gatway
cd /opt/gatway/ai-gateway
python3 -m venv .venv
./.venv/bin/pip install -r requirements.txt

Create the database:

sudo -u postgres psql
CREATE USER gateway WITH PASSWORD 'a-long-random-password';
CREATE DATABASE gateway OWNER gateway;

Generate your secrets:

# encrypts provider keys at rest
./.venv/bin/python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
openssl rand -hex 32   # ADMIN_KEY
openssl rand -hex 32   # SESSION_SECRET

Write .env, then start it:

DATABASE_URL=postgresql+asyncpg://gateway:...@localhost:5432/gateway
ADMIN_KEY=...
ENCRYPTION_KEY=...
SESSION_SECRET=...
ANTHROPIC_API_KEY=sk-ant-...
NVIDIA_API_KEY=nvapi-...

./.venv/bin/uvicorn app.main:app --host 127.0.0.1 --port 8000
curl localhost:8000/health   # {"status":"ok"}

Database tables are created automatically on first boot — there is no migration step. Build the dashboard with npm ci && npm run build in frontend/ and serve frontend/dist from nginx.

Connect providers

Gatway supports Anthropic, OpenAI, Gemini, NVIDIA and Ollama. Keys can come from .env (gateway-wide fallback) or be added per organization in the dashboard, where they're encrypted at rest.

Sign in to the dashboard → Providers & Models → add a key. Then set:

• Allowed models — leave empty for all, or restrict to an approved list.
• Monthly budget — a hard ceiling; requests are blocked past it.
• Security filter — log, redact or block for secrets leaving to external providers.

Users & keys

Bootstrap the first organization and admin with your master ADMIN_KEY:

curl -X POST https://gatway.example.com/admin/orgs \
  -H "Authorization: Bearer $ADMIN_KEY" -H "Content-Type: application/json" \
  -d '{"name":"Acme"}'

curl -X POST https://gatway.example.com/admin/users \
  -H "Authorization: Bearer $ADMIN_KEY" -H "Content-Type: application/json" \
  -d '{"org_id":"<org-id>","email":"you@acme.com","role":"admin","password":"strong-password"}'

After that, everything happens in the dashboard. Roles:

Issue each developer a key under Users & Keys — it starts with sk-gw- and is shown only once. Keys can be scoped to a project so cost is attributed correctly.

VS Code extension

Install the .vsix: Extensions → ⋯ → Install from VSIX, then reload. Point it at your server in settings:

"gatway.baseUrl": "https://gatway.example.com"

Open the Gatway sidebar and sign in with email/password or your sk-gw- key. You get:

• Chat with project context, plus an agent picker
• Inline autocomplete — toggle with Gatway: Toggle Inline Autocomplete
• Edit-apply — proposed changes shown as a diff, applied only on approval
• Code review — Gatway: Review Changes reviews your git diff

Useful settings:

Project setup

Two files make Gatway understand a repository. Commit both.

.aiconfig

Team rules and stack, applied to every request in this repo. Create it with Gatway: Create .aiconfig.

{
  "stack": ["python", "fastapi", "react"],
  "testing": "pytest",
  "rules": [
    "SQLAlchemy 2.0 style only",
    "Errors follow RFC 7807"
  ],
  "ignore_paths": ["migrations/", "*.lock"],
  "max_context_files": 5
}

PROJECT_STRUCTURE.md

A generated map of the repo, attached as context so the AI understands the layout. Run Gatway: Generate Project Structure once and commit the result.

Agents

Agents explore the codebase with tools and propose multi-file changes. They're declarative — adding one is configuration, not code — and they're layered:

1. Built-in — Coder, Reviewer, Test writer
2. Org-published — created in the dashboard, available to everyone
3. Project — committed in .gatway/agents/*.md

A project agent overrides an org agent with the same id, unless the org marked it locked.

A project agent

---
name: DB Migrator
description: Writes schema migrations
tools: [read_file, search_code, propose_edit, create_file]
model: claude-sonnet-4-5
---
You migrate database schemas. Always include a rollback path
and never edit a migration that has already shipped.

Tools

Code review & CI

Run Gatway: Review Changes to review uncommitted work or a branch against your base. Findings come back with severity, file, line and a suggested fix.

The same endpoint works from CI — gate a merge on the result:

curl -X POST https://gatway.example.com/v1/review \
  -H "Authorization: Bearer $GATWAY_KEY" -H "Content-Type: application/json" \
  -d "$(jq -n --arg d "$(git diff origin/main...HEAD)" '{diff:$d}')"

The response includes approved, a summary, and a findings[] array.

Cost controls

Four mechanisms, all on by default:

• Focused context — sends the target function instead of whole files (~90% less context)
• Prompt analyzer — a cheap model optimizes the prompt and picks the files before the expensive model runs
• Response cache — identical and near-identical requests are served from cache at zero cost
• Auto routing — simple prompts go to a cheap model, complex ones to a strong model

Set hard limits in the dashboard: monthly budget per organization and per project, and a daily token limit per user. Track spend under Overview.

Audit trail

Every prompt is recorded, and every applied change is recorded with its full diff and the prompt that caused it. Leads and admins see it under Changes, filterable by developer, project and date.

Secrets are stripped before anything is stored; PII follows your organization's policy.

Config reference

Troubleshooting