v0.1.0-beta.1 Open Source Gateway Apache 2.0

One Gateway.
All Harnesses.

Bridge your IDEs, code editors, and agent workflows to your local AI coding CLIs through a unified, OpenAI-compatible local API.

Get Started GitHub Repository
Local Loopback Default
Real-time SSE Streaming
Bilingual Dashboard
Gateway Routing Topology
ACTIVE · PORT 3500
POST /v1/chat/completions
Client Request
Afaq Gateway Core Engine
Python 3.12 · FastAPI · POSIX PTY
Auth Boundary JWT / Scoped API Key
Atomic Quotas Two-Phase Reservation
Process Manager 64KB Bounded Ring
Registered CLI Adapters 18 Adapters Registered
Claude Code claude -p
OpenAI Codex codex exec --json
Antigravity agy models
OpenCode opencode models
Command Code cmd --list-models
Pi pi --list-models
Model prefix: codex//model-from-v1-models 
curl http://127.0.0.1:3500/v1/chat/completions \
  -H "Authorization: Bearer afaq_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "REPLACE_WITH_ID_FROM_V1_MODELS",
    "messages": [
      {"role": "system", "content": "You are a code refactoring expert."},
      {"role": "user", "content": "Refactor parse_stream() to handle reconnects cleanly."}
    ],
    "stream": true
  }'
Note: Query GET /v1/models first to discover available models for your installed harnesses, then copy an authoritative id into your request.
Universal CLI Adapter Engine

Run Supported AI Harnesses on Your Machine

The gateway maps OpenAI-format requests directly to your local CLI subprocesses. Each harness is registered in the core registry.

Important Infrastructure Boundary: Afaq Harness Gateway is an orchestration gateway, not an AI provider. A harness becomes available in /v1/models only when its CLI binary is installed locally and signed in with provider credentials.
Custom Built Adapters Full CLI contract & discovery
Claude Code Custom
bin: claude

Runs claude -p with stream-json output and plan permission mode; exposes the adapter’s standard model choices when installed.

format: claude//model-from-v1-models
OpenAI Codex Custom
bin: codex

Runs codex exec --json in a read-only sandbox; reads ~/.codex/models_cache.json with fallback choices.

format: codex//model-from-v1-models
OpenCode Custom
bin: opencode

Runs opencode run --format json; discovers models with opencode models.

format: opencode//provider/model-from-v1-models
Command Code Custom
bin: cmd

Runs cmd --print with JSON output and plan permission mode; discovers models with cmd --list-models.

format: commandcode//model-from-v1-models
Google Antigravity Custom
bin: agy

Runs agy --print with JSON output and plan mode; discovers models with agy models and has documented fallback choices.

format: agy//model-from-v1-models
Pi Custom
bin: pi

Runs pi -p with JSON output; discovers provider/model pairs with pi --list-models.

format: pi//provider/model-from-v1-models
Generic Text Adapters Standard process lifecycle
Minimax Generic
bin:minimax

Registered generic text adapter for the minimax executable (install: npm install -g minimax-cli).

Aider Generic
bin:aider

Registered generic text adapter for the aider executable.

Cline Generic
bin:cline

Registered generic text adapter for the cline executable (install: npm install -g @cline/cli).

Cursor Agent Generic
bin:cursor-agent

Registered generic text adapter for the cursor-agent executable.

Grok Generic
bin:grok

Registered generic text adapter for the grok executable (install: npm install -g @xai-official/grok).

Kimi Generic
bin:kimi

Registered generic text adapter for the kimi executable (install: npm install -g @moonshot/kimi-code).

OMP Generic
bin:omp

Registered generic text adapter for the omp executable.

Qoder Generic
bin:qodercli

Registered generic text adapter for the qodercli executable.

Vibe Generic
bin:vibe

Registered generic text adapter for the vibe executable.

GitHub Copilot (Muse) Generic
bin:copilot

Registered generic text adapter for the copilot executable (install: npm install -g @github/copilot).

Warp Agent Generic
bin:oz

Registered generic text adapter for the oz executable.

ZCode Generic
bin:zcode

Registered generic text adapter for the zcode executable.

Pipeline Architecture

From Application Call to CLI Execution

A deterministic, asynchronous request lifecycle that translates standard OpenAI payloads into isolated subprocess runs.

01

1. Standard API Ingestion

Client applications (Cursor, Cline, OpenAI SDKs, scripts) send standard POST /v1/chat/completions or GET /v1/models requests over HTTP.

Request shape: OpenAI-compatible
02

2. Admission & Quota Gate

The gateway resolves authentication, verifies per-key model allow-lists, and atomically reserves usage quota in SQLite before touching the CLI.

QuotaReservation two-phase lock
03

3. Subprocess Execution

The specific HarnessAdapter spawns the local CLI as an isolated POSIX subprocess, draining stderr into a 64KB bounded ring buffer.

communicate_with_timeout & reaping
04

4. Streaming SSE Delivery

CLI stdout lines are parsed incrementally, mapped into standard delta chunks, streamed via SSE, and closed with atomic quota finalization.

Data: [DONE] on terminal commit
Infrastructure Features

Engineered for Reliability and Control

Grounded in verified architectural capabilities designed for developer security and production stability.

Streaming Chat Completions

Full Server-Sent Events (SSE) support with periodic SSE heartbeats, client cancellation propagation, and per-stream identity isolation.

SSE Heartbeats StreamIdentity

Dynamic Model Discovery

Live CLI discovery runs at startup and on-demand via dashboard, serving verified model IDs from hot in-memory cache with Redis mirroring.

MODEL_CACHE GET /v1/models

Atomic Quota Reservations

Two-phase reservation pattern (QuotaReservation + UsageRecord) guarantees concurrent requests cannot overrun daily or monthly limits.

Two-Phase Lock No Race Conditions

Encrypted Credential Profiles

Provider secrets and tokens are encrypted at rest using Fernet symmetric encryption (CREDENTIALS_KEY). Plaintext secret material is never displayed again.

Fernet Zero Exposure

SQLite with Optional Redis

Runs on SQLite without an external database service for local single-node setups. An optional Redis instance can be configured for shared rate limits and cross-pod SSE replay.

SQLite (No External Service) redis.asyncio

Bilingual Web Dashboard

Intuitive browser dashboard in Arabic and English for conversations, harness installation, API key rotation, and usage metrics.

Arabic / English Key Rotation

Administrator OS Terminal

Interactive browser PTY shell powered by WebSocket and os.posix_spawn. Enables direct CLI management and maintenance from the dashboard.

POSIX PTY JWT Admin Only

Subprocess Hardening

Deterministic subprocess timeouts, zombie process reaping, and bounded 64KB stderr drainers prevent OS pipe deadlocks.

Zombie Reaping 64KB Ring Buffer

Structured JSON & Tool Calling

Normalized function and tool call objects (response_format and tools) mapped transparently between client and harness CLI output.

Tools response_format
Security Invariants

Strict Trust Boundaries by Design

The gateway treats host security as a core architectural responsibility with defense-in-depth boundaries.

OS Terminal Security Warning:

The browser OS Terminal runs with the exact same operating system privileges as the gateway host user. Deploy strictly on trusted machines or behind authenticated access layers. Never expose port 3500 unauthenticated to the public internet.

Authentication Boundary Separation

Hardened Auth

API keys (afaq_...) are restricted exclusively to /v1/* inference routes. Dashboard, administration APIs, and terminal sessions require signed JWTs.

Loopback-First & Private Deployment

Network Defense

Binds to 127.0.0.1:3500 by default. Docker Compose strictly publishes to the host loopback interface, keeping internal Redis networks private.

Fail-Fast Production Secrets

Zero Defaults

When DEBUG=false, startup fails immediately if SECRET_KEY or CREDENTIALS_KEY are missing, shorter than 32 characters, or match example placeholders.

Trusted Proxy Resolution & Bcrypt Ceiling

IP & Crypto Safe

Client IP resolution strictly uses socket peers unless explicitly whitelisted in TRUSTED_PROXIES. Bcrypt enforces a 72-byte ceiling to prevent silent password truncation.

Developer Quick Start

Up and Running in Under Five Minutes

Choose your preferred workflow. Both paths guide you directly to the first-time administrator setup wizard.

  1. 1 Clone repository

    Fetch the official repository and switch into the project directory. 

    git clone https://github.com/afaqhost/afaq-harness-gateway.git
cd afaq-harness-gateway
  2. 2 Run interactive setup wizard

    The automated wizard verifies Python 3.10+, pip, venv, creates .env with strong secrets, and prepares dependencies. 

    make setup
  3. 3 Start gateway development server

    Launches Uvicorn on http://127.0.0.1:3500 with hot reload and automatic database initialization. 

    make dev

Next steps after launch:

1. Open http://127.0.0.1:3500/setup to create the first administrator account.

2. In the dashboard, open Harnesses to review or install CLI tools.

3. Open API Keys, generate a key, and query GET /v1/models.

Beta Release Status (0.1.0-beta.1)

Core gateway and proxy workflows are tested (331 tests without warnings). APIs, configurations, and database schemas may still evolve prior to the 1.0 stable release. Always back up your SQLite database before updating.

View Changelog & Release Notes