astra-aigate — Unified AI Service Gateway

One web UI to configure, monitor and route LLM providers (290), MCP servers and auxiliary services.

Overview

astra-aigate is a self-hosted AI gateway console managing three categories of services:

1. LLM Providers — provider management, combo routing and fallback (carried from OmniRoute)

2. MCP Servers — MCP gateway host: one server exposing multiple MCP endpoints (registered self-hosted MCPs)

3. Auxiliary Services — health monitoring and reverse proxying for non-MCP tools (Camofox, SearXNG, etc.)

Built on OmniRoute (MIT): LLM provider management, combo routing and fallback, and the API-key auth model are inherited from it; the frontend (Expo design language, Next.js 16 + React 19), the MCP gateway and the auxiliary-service layer are original work. See Credits for the complete list of upstream projects.

Related MCP server: MCP Gateway

Features

• Expo design language — luminous monochrome UI with pure-black (#000000) primary actions

• Data-driven sidebar — sections.ts is the single source of truth for navigation; collapsible sub-groups (Routing & Access, Combos); media-providers entry; no redundant redirect stubs

• Independent scrolling — fixed-height layout with sidebar-internal scrolling and main-content scroll resets on route change

• i18n — 43 locales (English (British), zh-CN, zh-TW, and 40 more); language switcher in Settings > Appearance and docs layout

• Pluggable database — SQLite by default (zero-ops), optional PostgreSQL via DB_DRIVER=postgres; unified async DatabaseAdapter interface with a dialect translation layer

• Skill hub — multi-source skill aggregation: pull skills from git repos (tarball), SSH hosts or built-in catalogs, with dependency-aware artifact packaging for AI agents

• Podman deployment — multi-stage standalone build, no Turbopack (webpack-only)

Quick Start

# Pull the published image from GHCR (tagged releases, e.g. v0.5.1):
podman pull ghcr.io/alrcatraz/astra-aigate:latest
# Run it on the target host (IPv4 only):
podman run -d --name astra-aigate --env-file .env -p <port>:20128 ghcr.io/alrcatraz/astra-aigate:latest
# Open http://<host>:<port> — first login uses INITIAL_PASSWORD from .env

Images are built automatically by GitHub Actions (build-image.yml) on release tags (v* → :vX.Y.Z + :latest) and development pushes (:development); a local build with the multi-stage Dockerfile is equivalent.

If you use a dual-stack network (IPv4/IPv6), or expose the gateway as a public service, add dual-stack support with the following guidance. The gateway itself is dual-stack ready, but rootless Podman's pasta port forwarding binds IPv4 only. If a hostname resolves to both A and AAAA records and a client prefers IPv6 (e.g. a ULA fd.. address on your LAN), connections to the published port can hang or return empty responses — the IPv6 listener simply does not exist:

1. Publish v4 explicitly and rely on Happy Eyeballs for v6 clients to fall back: podman run -p 0.0.0.0:20128:20128 ... (pasta already binds v4 only — the risk is on clients that resolve v6 first and do not retry).

2. Front with a reverse proxy (nginx / Caddy / Camofox): terminate TLS on a dual-stack listener and proxy to 127.0.0.1:20128 (or the container's published v4 port). One stable hostname, working v4 + v6.

3. Verify both stacks after deploy: curl -6 https://<host>/v1/models and curl -4 https://<host>/v1/models must both return 200. If only v4 works, check the proxy listener, not the gateway.

4. Container-to-host traffic uses host.containers.internal (rootless Podman cannot reach the host IP directly) — this resolves to the host's v4 address; do not rely on IPv6 for upstream services.

PostgreSQL (optional)

Set DB_DRIVER=postgres and DATABASE_URL in .env to back the gateway with PostgreSQL instead of SQLite. The schema is created automatically on a fresh database; migrate an existing SQLite deployment with scripts/migrate-sqlite-to-pg.ts. In containers, reach the host database via host.containers.internal (see the dual-stack note above).

Tech Stack

Project Layout

src/shared/constants/sidebarVisibility/sections.ts  # single nav data source
src/shared/components/Sidebar.tsx                   # sidebar (collapsible sub-groups)
src/shared/components/layouts/DashboardLayout.tsx   # fixed-height layout + scroll reset
src/i18n/messages/*.json                        # 43 locales (British English base)
scripts/test/regression-final.mjs                   # Playwright regression suite

Usage

# Route an LLM request through a provider combo (fallback built in):
curl http://<host>:<port>/v1/chat/completions \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{"model":"<combo-name>","messages":[{"role":"user","content":"Hello"}]}'

# Call a registered MCP endpoint (gateway mode — one server, many endpoints):
# /api/mcp/servers/<id>/sse (SSE transport) or /stream (streamable HTTP)
curl http://<host>:<port>/api/mcp/servers/aigate-omniroute/stream \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Full configuration reference lives in .env.example; the web dashboard (Providers / Combos / MCP / Services) covers day-to-day management.

Documentation

• AGENTS.md — project context for AI agents

• DESIGN.md — Expo design system specification

• docs/ — operational references (incident response, performance budgets)

Credits

This project builds on the following open-source work:

• OmniRoute (MIT) — the unified AI service gateway this project was seeded from; upstream attribution is retained in the source tree.

• awesome-design-md — source of the design-spec template used for DESIGN.md.

• Expo — the visual design language (bright airy canvas, pill-shaped geometry) our UI shell is based on.

Licence

MIT. Seeded from OmniRoute (MIT) — upstream attribution retained in the source tree.

astra-aigate（中文版）

astra-aigate — 统一 AI 服务网关

一个 Web 界面统一配置、监控和路由 LLM 提供商、MCP 服务器和辅助服务。

概述

astra-aigate 是一个自托管的 AI 网关控制台，管理三类服务：

1. LLM 提供商 — 提供商管理、组合路由和故障转移（继承自 OmniRoute）

2. MCP 服务器 — MCP 网关宿主：一个服务端暴露多个 MCP 端点，登记 自部署 MCP（本机 stdio + 远端 HTTP/SSE）

3. 辅助服务 — 非 MCP 工具（Camofox、SearXNG 等）的健康监控和反向代理

本项目基于 OmniRoute（MIT）构建：LLM 提供商管理、组合路由与故障转移、API 密钥认证模型均继承自它；前端（Expo 设计语言、Next.js 16 + React 19）、MCP 网关与辅助服务层为原创。完整上游项目列表见致谢。

特性

• Expo 设计语言 — 明亮单色 UI，纯黑（#000000）主按钮

• 数据驱动侧边栏 — sections.ts 是导航的唯一数据源；可折叠子分组（Routing & Access、Combos）；media-providers 入口；无纯重定向冗余项

• 独立滚动 — 固定高度布局，侧边栏内部滚动 + 路由切换时主内容滚动归零

• i18n — 43 个 locale（英语（英式）、zh-CN、zh-TW 及另外 40 种）；Settings > Appearance 和 docs 布局中有语言切换器

• 可插拔数据库 — 默认 SQLite（零运维），可选 PostgreSQL（DB_DRIVER=postgres）；统一异步 DatabaseAdapter 接口 + 方言翻译层

• Skill 中心 — 多源技能聚合：从 git 仓库（tarball）、SSH 主机或内置目录拉取技能，带依赖感知的产物打包供 AI 智能体使用

• Podman 部署 — 多阶段 standalone 构建，仅 webpack（禁用 Turbopack）

快速开始

# 在目标主机上运行预构建镜像（仅 IPv4）：
podman run -d --name astra-aigate --env-file .env -p <port>:20128 localhost/astra-aigate:latest
# 打开 http://<host>:<port> — 首次登录使用 .env 中的 INITIAL_PASSWORD

如果你使用双栈网络（IPv4/IPv6），或作为公开服务提供，则可以参考以下命令 实现双栈网络支持。网关本身支持双栈，但 rootless Podman 的 pasta 端口转发 仅绑定 IPv4。如果主机名同时解析出 A 和 AAAA 记录，而客户端优先使用 IPv6 （例如局域网中的 ULA fd.. 地址），对已发布端口的连接可能挂起或返回空 响应——IPv6 监听根本不存在：

1. 显式发布 v4，依靠 Happy Eyeballs 让 v6 客户端回退： podman run -p 0.0.0.0:20128:20128 ...（pasta 本就只绑 v4——风险在 客户端先解析 v6 且不重试）。

2. 前置反向代理（nginx / Caddy / Camofox）：在双栈监听器上终止 TLS， 代理到 127.0.0.1:20128（或容器已发布的 v4 端口）。一个稳定主机名， v4 + v6 同时可用。

3. 部署后验证双栈：curl -6 https://<host>/v1/models 与 curl -4 https://<host>/v1/models 都必须返回 200。只有 v4 通时，检查 代理监听器而非网关。

4. 容器到宿主流量 使用 host.containers.internal（rootless Podman 无法直连宿主 IP）——它解析为宿主的 v4 地址；上游服务不要依赖 IPv6。

PostgreSQL（可选）

在 .env 中设置 DB_DRIVER=postgres 和 DATABASE_URL，即可用 PostgreSQL 替代 SQLite 作为网关存储。新库自动建表；迁移现有 SQLite 数据用 scripts/migrate-sqlite-to-pg.ts。容器内访问宿主数据库须用 host.containers.internal（见上文双栈说明）。

技术栈

项目结构

src/shared/constants/sidebarVisibility/sections.ts  # 导航唯一数据源
src/shared/components/Sidebar.tsx                   # 侧边栏（可折叠子分组）
src/shared/components/layouts/DashboardLayout.tsx   # 固定高度布局 + 滚动重置
src/i18n/messages/*.json                        # 43 个 locale（英式英语为基准）
scripts/test/regression-final.mjs                   # Playwright 回归套件

用法

# 通过提供商组合路由 LLM 请求（内置故障转移）：
curl http://<host>:<port>/v1/chat/completions \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{"model":"<combo-name>","messages":[{"role":"user","content":"你好"}]}'

# 调用已登记的 MCP 端点（网关模式——一个服务端、多个端点）：
# /api/mcp/servers/<id>/sse（SSE 传输）或 /stream（Streamable HTTP）
curl http://<host>:<port>/api/mcp/servers/aigate-omniroute/stream \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

完整配置参考见 .env.example；日常管理由 Web 控制台 （Providers / Combos / MCP / Services）覆盖。

文档

• AGENTS.md — AI 代理项目上下文

• DESIGN.md — Expo 设计系统规范

• docs/ — 运维参考（事件响应、性能预算）

致谢

本项目基于以下开源成果：

• OmniRoute（MIT）—— 本项目的种子来源（统一 AI 服务网关）；上游署名保留在源码树中。

• awesome-design-md —— DESIGN.md 设计规范模板的来源。

• Expo —— UI 外壳所采用的视觉设计语言（明亮通透的画布、胶囊形几何）。

许可证

MIT。种子代码来自 OmniRoute（MIT）——上游署名保留在源码树中。