aki-pro-max

v2.4.5

Published

11 days ago

Local-first OpenAI-compatible gateway and control plane for an authorized Postman web session.

0High
0Medium
0Low

khangtudo

openai-compatible gateway postman local-first tool-calling mcp cli

⚡ Aki Pro Max

High-Performance OpenAI-Compatible Local Facade & Gateway for Postman Agent Mode

Unified Local Inference Gateway · Eight Public Model Aliases · Adaptive Context Ingress (>100KB) · Native Tool Calling & Session Continuity

🌟 Overview (Omniroute Style)

Aki Pro Max is a resilient, local-first gateway that bridges closed web-session AI capabilities (such as Postman Agent Mode) into a standardized OpenAI Chat Completions API (/v1/chat/completions). It enables autonomous AI agents (OpenClaw, AICoworker, Cursor, Cline, 9router, Continue) to tap into premier reasoning models (GPT-5.6 Sol, Claude Opus 4.8, GPT-5.6 Terra) seamlessly on local machines or remote VPS servers.

🏢 Hyperframe Architecture: Multi-Tenancy Load Balancing & Dynamic Context Scaling

flowchart TD
    subgraph Clients ["AI Clients & IDEs (Claude Code / OpenClaw / Cursor)"]
        C1["Session A (PID 1)"]
        C2["Session B (PID 2)"]
        C3["Session C (PID 3)"]
    end

    subgraph AkiEngine ["Aki Pro Max Gateway Engine (:8788)"]
        TP["Tenant Pool Manager (tenants.json)\n- Least-Loaded Balancer\n- 5-Minute Sticky Window\n- Concurrency Cap Enforcement"]
        DCL["Dynamic Context Ladder (16k -> 1M)\n- Auto-promotion at >= 80% usage\n- Memory & Payload Guard (3.5MB Max)"]
        FAIL["Auto-Failover Controller\n- Bounded Retry on 429/503\n- Zero-Permit Leak Guarantee"]
    end

    subgraph Workspaces ["Postman Multi-Tenant Cloud Workspaces"]
        W1["Tenant 1 (Subdomain Alpha)\nWorkspace ID: 358aa... (Cap: 3)"]
        W2["Tenant 2 (Subdomain Beta)\nWorkspace ID: b8912... (Cap: 3)"]
        W3["Tenant N (Subdomain Gamma)\nWorkspace ID: 7c4fa... (Cap: 3)"]
    end

    C1 --> TP
    C2 --> TP
    C3 --> TP
    TP --> DCL
    DCL --> FAIL
    FAIL -->|Active Session 1| W1
    FAIL -->|Active Session 2| W2
    FAIL -->|Overloaded 503 Failover| W3

📐 Motion & Data Flow Architecture

flowchart TD
    subgraph Clients ["Autonomous Clients & Agents"]
        OC["AICoworker / OpenClaw"]
        CR["Cursor / Cline / IDEs"]
        NR["9router / LiteLLM Gateway"]
    end

    subgraph Facade ["Aki Pro Max Facade Engine (:8788)"]
        IG["Ingress Guard & Body Reader\n(100MB Capacity)"]
        ACI["Adaptive Context Ingress Engine\n(Head 100KB + Tail 200KB)"]
        SCH["Recursive JSON Schema Validator\n(patternProperties enabled)"]
        TRC["Tool Continuation & Role Normalizer\n(toolResult -> conversational turns)"]
        SSM["Stateful Session Store\n(x-session-id -> conversationId)"]
    end

    subgraph Upstream ["Postman Agent Mode Cloud"]
        GW["Postman Cloud Gateway\n(gateway.postman.com / _gw/chat)"]
        BRK["AWS Bedrock / Azure / Anthropic Upstream"]
    end

    OC -->|Chat Request: System + Tools >90KB| NR
    CR -->|OpenAI standard request| IG
    NR -->|Forward to PMN endpoint| IG

    IG -->|Payload bytes >6000| ACI
    ACI -->|Virtual File: selectedContext >400KB| GW
    ACI -->|Active Query turn <=4000 bytes| GW

    IG -->|Validate Function Parameters| SCH
    SCH --> TRC
    TRC -->|Correlate toolResponses| SSM
    SSM -->|HTTPS Streamable EventStream| GW

    GW --> BRK
    BRK -->|SSE Chunks: textChunk, toolCallChunk| Facade
    Facade -->|OpenAI Stream Response / tool_calls| Clients

    style Facade fill:#0f172a,stroke:#38bdf8,stroke-width:2px,color:#f8fafc
    style Clients fill:#1e293b,stroke:#94a3b8,stroke-width:1px,color:#f8fafc
    style Upstream fill:#1e1b4b,stroke:#818cf8,stroke-width:1px,color:#f8fafc

⚡ 1-Line Quick Deploy (NPX / NPM)

Deploy instantly on any personal computer or remote Linux VPS without manual Git cloning:

Option 1: Instant Launch with NPX

# Set your authenticated Postman session cookie and start
export POSTMAN_SESSION_COOKIE="c936e68742abd76e..."
npx aki-pro-max start

Option 2: Global Install via NPM

npm install -g aki-pro-max
# Start the proxy (server + local Control Plane):
aki-pro-max start

Option 3: Windows Server + Tray Helper + Control Plane

# Installs the global server command, Start Menu helper shortcuts (tray-style launcher),
# and the local Aki Pro Max Control Plane link:
irm https://raw.githubusercontent.com/khangtudo/aki-pro-max/main/scripts/install-local.ps1 | iex

The installer provides:

Server: aki-pro-max start
Tray-style background launcher shortcut: Start Aki Pro Max Control
Control Plane shortcut: http://127.0.0.1:8788/admin

Safe Manual Update (Control Plane Flow)

When the Control Plane shows Update Available, follow this exact order:

Stop the old proxy completely by PID (do not update while it is processing a request):

Get-NetTCPConnection -LocalPort 8788 -State Listen | ForEach-Object { Stop-Process -Id $_.OwningProcess -Force }

Run the update in a new PowerShell window:
```
npm install -g aki-pro-max@latest
```
Return to the Control Plane and click Reload Control Plane, then run aki-pro-max start to obtain a new proxy PID.

Option 4: Traditional Git Clone

git clone https://github.com/khangtudo/aki-pro-max.git
cd aki-pro-max
cp .env.example .env
npm install
npm test
npm start

Local Admin Control Plane: http://127.0.0.1:8788/admin
OpenAI Compatible Endpoint: http://127.0.0.1:8788/v1/chat/completions

🚀 Key Technical Breakthroughs (v2.3.2)

Adaptive Context Ingress (>100KB Payload Ceiling Breaker):
- Postman's cloud gateway enforces a strict ~9.500 bytes ceiling on input.query.
- Aki Pro Max transparently offloads extensive system prompts, tool definitions (~90KB), and past conversation turns into virtual file attachments (selectedContext) while keeping the active query concise (≤ 6.000 bytes UTF-8).
Recursive JSON Schema Validator (patternProperties):
- Seamlessly validates all 34+ native OpenClaw/AICoworker tools (including exec.env).
Tool Continuation & Role Normalization:
- Gracefully converts non-standard OpenClaw role: "toolResult" and complex thinking blocks into clean conversational feedback, eliminating 404 unknown_tool_call and RPC timeouts.
Massive Multi-Agent Room Scale (100MB Body):
- Ingress limit scaled to 100MB (MAX_BODY_BYTES=104857600) with an intelligent Head (100KB) + Tail (200KB) truncation window to safely handle sprawling multi-agent collaborative sessions.
Universal Model Support:
- Whitelisted global.anthropic.claude-opus-4-7, ensuring 100% 200 OK delivery across all 8 models.

🧠 Model Catalog

| Public Model ID | Upstream Model Engine | Thinking Mode | Max Context | |---|---|:---:|:---:| | gpt-5.6-sol | GPT_56_SOL | ❌ | 400.000 tokens | | gpt-5.6-sol-thinking | GPT_56_SOL | ✅ | 400.000 tokens | | gpt-5.6-terra | GPT_56_TERRA | ❌ | 400.000 tokens | | gpt-5.6-terra-thinking | GPT_56_TERRA | ✅ | 400.000 tokens | | claude-opus-4-8 | CLAUDE_OPUS_48_BEDROCK | ❌ | 400.000 tokens | | claude-opus-4-8-thinking | CLAUDE_OPUS_48_BEDROCK | ✅ | 400.000 tokens | | claude-opus-4-7 | CLAUDE_OPUS_47_BEDROCK | ❌ | 400.000 tokens | | claude-opus-4-7-thinking | CLAUDE_OPUS_47_BEDROCK | ✅ | 400.000 tokens |

❓ FAQ — Deployment, Resources & Connection

What resources does Aki Pro Max need?

Runtime: Node.js >=22.15, npm, and an active browser/web-session credential for the authorized upstream account.
Hardware: It is a protocol facade — inference runs upstream — so 2 CPU cores, 2GB free RAM, and 1GB free disk is sufficient for a single-user VPS/PC deployment. Use more RAM if you expect many concurrent streaming clients.
Network: The server binds to loopback (127.0.0.1) by default. Put a reverse proxy with TLS and separate authentication in front only if you intentionally expose it to a private network.

How does authentication work?

Aki Pro Max supports two explicit modes in .env:

access_token — provide an authorized upstream access token.
web_session — provide a current authenticated session cookie, workspace subdomain, workspace ID, and upstream selected model.

Copy .env.example to .env, choose one mode, and populate only the values for that mode. Never commit .env, session cookies, bearer tokens, or API keys. The Control Plane deliberately masks credentials and never stores them in browser storage.

Which models can I use?

The included catalog exposes eight aliases: gpt-5.6-sol, gpt-5.6-sol-thinking, gpt-5.6-terra, gpt-5.6-terra-thinking, claude-opus-4-8, claude-opus-4-8-thinking, claude-opus-4-7, and claude-opus-4-7-thinking. Availability still depends on the upstream account and the exact observed-model allowlist in .env.

What URL do I configure in my client?

Use the OpenAI-compatible base URL:

http://127.0.0.1:8788/v1

Examples:

OpenAI SDK: baseURL: 'http://127.0.0.1:8788/v1'
9router / LiteLLM: provider base URL http://127.0.0.1:8788/v1
Control Plane: http://127.0.0.1:8788/admin

How do I create an API key for local clients?

Set a strong opaque value in .env:

PROVIDER_API_KEY=replace-with-a-long-random-local-bearer

Generate one locally:

node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"

Then send it to clients as Authorization: Bearer <PROVIDER_API_KEY>. It is the local facade key, not the upstream web-session cookie.

What does the 1-line installer install?

On Windows, the installer creates the global server command (aki-pro-max), a Start Menu background/tray-style launcher shortcut, and an Aki Pro Max Control shortcut. The actual proxy starts only when you run aki-pro-max start or select the launcher; no auto-start service is installed silently.

How do I update safely?

When Aki Pro Max Control shows an update banner, follow its three steps exactly: stop the active server PID, run npm install -g aki-pro-max@latest in PowerShell, then reload the Control Plane and start a new proxy PID. The banner checks version metadata with a short timeout and fails open — an offline machine keeps working normally. If npm reports an error, reinstall the last known version explicitly (for example npm install -g [email protected]) before restarting.

🧩 Verified Test Suite

# tests 109
# pass 109
# fail 0
All contracts, tools, event parsers, and multi-turn continuations verified 100% passing.

🔒 Security & Privacy

Loopback Only: Bound exclusively to 127.0.0.1.
Zero Raw Secret Leaks: Authenticated credentials, raw cookies, and session tokens are strictly redacted from logs, error payloads, and git commits.
Fail-Closed Safety: Mismatched schemas or unauthorized models fail closed without silent fallback.