- Rust 89.1%
- Shell 3.5%
- Nix 2.6%
- Python 2.1%
- Nushell 1.9%
- Other 0.6%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
Link koan.vaked.dev from every docs page so portail joins the one front door
like the rest of the constellation.
💘 Generated with Crush
Assisted-by: Crush:deepseek-v4-flash
|
||
| .cargo | ||
| .deepseek/state | ||
| .devcontainer | ||
| .github | ||
| .harness-memory | ||
| .opencode | ||
| .qwen/skills | ||
| .wrangler/cache | ||
| benches | ||
| crates | ||
| docs | ||
| nix | ||
| notebooks | ||
| nushell | ||
| packaging | ||
| plugins/portail-mcp | ||
| scripts | ||
| src | ||
| tests | ||
| .dockerignore | ||
| .editorconfig | ||
| .env.example | ||
| .envrc | ||
| .envrc.example | ||
| .gitattributes | ||
| .gitignore | ||
| .ignore | ||
| .versions | ||
| _next_task.md | ||
| AGENTS.md | ||
| build.rs | ||
| Cargo.lock | ||
| Cargo.toml | ||
| CHANGELOG.md | ||
| CODEOWNERS | ||
| CONTRIBUTING.md | ||
| deny.toml | ||
| Dockerfile | ||
| flake.lock | ||
| flake.nix | ||
| justfile | ||
| LICENSE | ||
| LOOP_STATE.md | ||
| opencode.json | ||
| PHILOSOPHY.md | ||
| portail.example.toml | ||
| portail.toml.history | ||
| README.md | ||
| robots.txt | ||
| rust-toolchain.toml | ||
| SECURITY.md | ||
| spec.routes.toml | ||
| START_HERE.md | ||
| Taskfile.yml | ||
| TASKS.md | ||
Portail
Unified proxy/gateway: AI Gateway + MCP Gateway + CDN cache + Agent protocol + DNS + Observability
Blog · GitHub · X/Twitter · Patreon · Chat
v2.0.0 · 201 tests · 0 warnings · 7 CI agents · MIT-licensed since 2026. Read the philosophy:
PHILOSOPHY.md
graph TD
%% Abstract Architectural Concept
subgraph Ecosystem [Constellation Mesh]
P((Portail)):::core
AI[AI Gateway]:::node
MCP[MCP Socket]:::node
CDN[Edge CDN]:::node
A2A[A2A Swarm]:::node
P -.->|streams| AI
P -.->|executes| MCP
P -.->|caches| CDN
P -.->|routes| A2A
end
classDef core fill:#00d4ff,stroke:#0a0a0a,stroke-width:2px,color:#0a0a0a;
classDef node fill:#111,stroke:#00d4ff,stroke-width:1px,color:#fff;
style Ecosystem fill:transparent,stroke:#333,stroke-dasharray: 5 5;
Portail is a high-performance, self-hosted proxy and gateway giving you a single control plane for AI infrastructure. Built in Rust. Start in 5 minutes. Scale to fleet.
One binary. Proxy, cache, hooks, agents, DNS, observability, loop engine. Everything.
Features
- AI Gateway — Stream proxy to LiteLLM, OpenAI, Anthropic, Ollama
- MCP Gateway — Unix socket sidecar for MCP tool execution
- Constellation Router — Decentralized agent routing across vaked.dev constellation surfaces (art, music, proposal, pocoo, quant-love, axiomquant)
- CDN Cache — Two-tier (Moka in-memory + blake3 disk) with mmap zero-copy reads
- A2A Protocol — Google Agent-to-Agent: agent cards, task lifecycle, WebSocket streaming
- A2C Chat — Human-facing chat API with tool use, streaming, tokens
- Hook Injection — Per-message/per-event prompt injection, CRUD API
- Event System — Ring buffer + broadcast + SSE + NATS bridge for distributed events
- DNS — DoH resolution, network isolation, TTL cache, fallback chain
- Sovereign Key Auth — Offline Ed25519 cryptographic token verification (
Authorization: Sovereign <TOKEN>) with signature proofs - Sentinel Fleet Watchdog — Real-time
/v1/sentinel/fleetliveness endpoint monitoring constellation nodes with automatic HTTP latency and probe checks - Security — Rate limiting (token bucket, per-key/per-endpoint), JWT/API-key auth, HSTS, Sovereign Ed25519 keys
- Self-healing — Config file watcher, auto-reload, validation, version history + rollback
- TUI Dashboard — Live sparklines, cache ratios, config health, keyboard navigation
- Event Store — SQLite (WAL, retention) with pluggable Turso/libSQL backend
- 6 CI Agents — Advisory-only: complexity, drift-detect, spec-verify, fuzz-route, chore-bot, clippy
- Type Hardened — BoundedMeta (max 16 entries, key≤128B, val≤512B) replaces FxHashMap on hot paths
- Loop Engine — 5 building blocks (Schedule, Worktree, Skill, Plugin, Sub-agent) + Memory/State + plan→execute→evaluate→decide pipeline
- Circuit Breaker — Auto-stop after N consecutive failures, manual reset
- Council Decisions — Ship / Iterate / Escalate with token budget enforcement
- Config Wizard —
portail initinteractive generator, zero-config startup - GraphQL API — Async-graphql schema, query events + publish mutations
- Keyboards CLI — Status, events, hooks, cache, health, config — all HTTP-connected to running server
Quick Start
# Install
cargo install portail
# Generate config (optional — works without it)
portail init
# Start server (zero config)
portail serve
# Interactive dashboard
portail
# Check health
portail health
curl http://localhost:8787/dashboard | jq
Installation
| Method | Command |
|---|---|
| Cargo | cargo install portail |
| Nix | nix profile install github:peterlodri-sec/portail |
| Docker | docker run -p 8787:8787 ghcr.io/peterlodri-sec/portail:latest |
| Quick script | curl -fsSL https://raw.githubusercontent.com/peterlodri-sec/portail/main/scripts/install.sh | bash |
| From source | git clone && cargo build --release |
API Endpoints
| Endpoint | Method | Description |
|---|---|---|
/healthz |
GET | Health check |
/readyz |
GET | Readiness (dependencies) |
/dashboard |
GET | Health snapshot: config, rate, auth, CDN |
/metrics |
GET | Prometheus metrics |
/v1/chat/completions |
POST | OpenAI-compatible chat |
/v1/messages |
POST | Anthropic-compatible messages |
/.well-known/agent.json |
GET | A2A agent card |
/a2a/tasks |
POST | Create A2A task |
/a2a/tasks/{id} |
GET | Get A2A task |
/a2a/ws |
WebSocket | A2A real-time streaming |
/a2c/chat |
POST | Agent-to-Consumer chat |
/events |
GET/POST | Recent events / publish |
/events/stream |
GET | SSE event stream |
/hooks |
GET/POST | List / create hooks |
/hooks/{id} |
DELETE | Delete hook |
/graphql |
POST/GET | GraphQL API |
/sessions |
GET | Session list |
/sessions/{id} |
GET | Session detail |
/supervisor/status |
GET | Background task status |
/file-cache/{key} |
PUT/GET/DELETE | Content-addressable file cache |
/file-cache/stats |
GET | File cache stats |
/cdn/{*path} |
* | CDN cache proxy |
/mcp/{*path} |
* | MCP sidecar proxy |
CLI
portail # Interactive TUI dashboard
portail serve # Start server (zero config)
portail init # Interactive config wizard
portail status # Version, config, server check
portail events # Recent events (from running server)
portail hooks list # List hooks
portail hooks add # Add hook via JSON
portail health # Health check
portail config show # Show config (TOML)
portail config validate # Validate config file
portail config rollback # Rollback to previous version
portail complexity # Big-O complexity analysis
portail docs # Generate docs, open in browser
portail learn <topic> # Learn networking concepts
portail setup # Domain + TLS certificate setup
portail loop run <sched> # Run loop iterations
portail loop prompt # Generate _next-prompt.md for handoff
portail loop council <id> # Manual council override
portail loop config # Show loop engine configuration
portail loop schedules # List registered schedules
Hardware Optimizations
- mimalloc — Global allocator, 2-3x alloc throughput
- blake3 — Native SIMD (SSE2/AVX2/NEON) for cache keys
- AHash — DoS-resistant HashMap with per-process random seed
- UPX — Compressed release binary (<10MB)
- LTO + PGO — fat-LTO, codegen-units=1, strip symbols
- io_uring / DPDK — Feature-gated high-performance I/O engines
CI & Agents
7 CI agents run on every push/PR:
| Agent | Blocks CI? | Status |
|---|---|---|
| complexity | ❌ advisory only | ✅ |
| drift-detect | ❌ advisory only | ✅ |
| spec-verify | ❌ advisory only | ✅ |
| fuzz-route | ⚠️ only on crash | ✅ |
| chore-bot | ❌ advisory only | ✅ |
| clippy | ✅ always | ✅ |
| test | ✅ always (174 passing) | ✅ |
All advisory agents post comments, never fail the build.
Development
task c # cargo check (fast)
task t # cargo test (174 passing)
task lint # clippy + fmt check
task counts # test + warning counts
task chore-check # auto-fixable issues
task bench # criterion benchmarks
task docs # generate + open docs
Explore:
AGENTS.md— codebase cross-reference hub.
Philosophy:PHILOSOPHY.md— project values and principles.
Product:docs/architecture/PRODUCT.md— strategy + positioning.
Architecture:docs/architecture/DESIGN.md+NETWORK_DESIGN.md.
Roadmap:LOOP_STATE.md— current state + next milestones.
Loop Engine:crates/loopeng/src/lib.rs— 5 building blocks + 4-phase pipeline + circuit breaker.
Contribute:docs/contributors/CONTRIBUTING.md.
License
MIT