Skip to main content

AxonFlow v8.4.0 Release Notes

Released 2026-05-28. Adds an OpenAI-compatible gateway endpoint for drop-in SDK governance, aligns the self-hosted docker-compose.enterprise.yml with the production CFN templates, and ships a bundled OTel + Tempo + Grafana stack in axonflow-install so Decision Mode traces are visible out of the box on non-AWS deployments. No breaking changes. No new SDK versions in this release — SDKs remain at v8.3.0.

Headline: OpenAI-compatible gateway — change baseURL, get governance​

Existing OpenAI SDK users can now route calls through AxonFlow by changing a single line. No new SDK to learn, no request-format changes — the endpoint accepts and returns standard OpenAI Chat Completions wire format. Policy enforcement runs before the upstream provider call; audit captures token usage, cost, latency, and policy decision.

Quick start (Python)​

import os
from openai import OpenAI

client = OpenAI(
    api_key="any-value",                              # AxonFlow auth (community: any value)
    base_url="http://localhost:8080/v1",              # Point at AxonFlow instead of OpenAI
    default_headers={
        "X-Provider-Key": os.environ["OPENAI_API_KEY"]
    }
)

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "What is 2+2?"}]
)
print(response.choices[0].message.content)  # "4"

Quick start (TypeScript)​

import OpenAI from 'openai';

const client = new OpenAI({
    apiKey: 'any-value',
    baseURL: 'http://localhost:8080/v1',
    defaultHeaders: { 'X-Provider-Key': process.env.OPENAI_API_KEY! }
});

const response = await client.chat.completions.create({
    model: 'gpt-4o-mini',
    messages: [{ role: 'user', content: 'What is 2+2?' }]
});

What happens behind the scenes​

  1. Authentication — same apiAuthMiddleware as all other agent endpoints (community: no auth; enterprise: Basic Auth).
  2. Policy evaluation — shared policy engine runs PII detection, SQL injection blocking, dangerous query prevention, and compliance rules against the message content. Same engine as Gateway Mode and Decision Mode.
  3. Deny path — returns HTTP 400 with an OpenAI-compatible error body. The OpenAI SDK parses this as BadRequestError, so existing error handling works unchanged: 
    {
      "error": {
        "message": "Request blocked by policy: Social Security Number detected",
        "type": "policy_violation",
        "code": "policy_denied"
      }
    }
  4. Allow path — forwards the request body verbatim to the upstream provider with Content-Type: application/json and Authorization: Bearer <X-Provider-Key>. Other request headers (e.g. OpenAI-Beta, OpenAI-Organization) are not forwarded in this release.
  5. Audit — writes to llm_call_audits with provider, model, prompt/completion token counts, estimated cost, latency, and policy decision (allow or deny). Denied requests record zero tokens.
  6. Response — provider's response returned unchanged, with two added headers for audit correlation and OTel tracing:
    • X-AxonFlow-Decision-Id — UUID matching the audit row
    • X-AxonFlow-Trace-Id — W3C 32-hex trace ID

When the upstream provider returns a non-2xx (e.g. invalid X-Provider-Key, model not found, rate limit), AxonFlow forwards the error body and status code verbatim. X-AxonFlow-Decision-Id and X-AxonFlow-Trace-Id are still set on the response and an audit row is still written (with zero tokens) so the request is traceable end-to-end.

Provider key handling​

The caller passes the upstream provider API key via the X-Provider-Key header. AxonFlow does not store this key — it is forwarded to the upstream provider for the duration of the request only. Server-side provider key management is planned for a future release.

Limitations in this release​

  • Non-streaming only. Requests with stream: true return HTTP 400 with code: "stream_not_supported". Streaming support is planned.
  • Chat Completions only. Other OpenAI endpoints (embeddings, images, audio) are not proxied.
  • System policies only. Custom tenant policies created in the Portal UI require Proxy Mode.

See the full tutorial at OpenAI-Compatible Gateway.

Self-hosted deployment alignment​

A hand-authoring drift audit between docker-compose.enterprise.yml and the production CloudFormation templates surfaced six contract gaps. Self-hosted deployments on Docker Compose were missing settings that AWS-deployed stacks had been receiving by default. This release closes the drift.

Action required for self-hosted upgrades

Self-hosted deployments upgrading from prior versions on docker-compose.enterprise.yml must set AXONFLOW_INTERNAL_SERVICE_SECRET before starting v8.4.0. Without it, the customer-portal cannot authenticate calls to the agent and the unified-policies UI silently shows 0 system policies. AWS CFN-deployed stacks are unaffected.

What changed in the compose overlay​

ServiceChangeWhy
customer-portalAdded AXONFLOW_INTERNAL_SERVICE_SECRET envRequired for service-to-service auth against agent endpoints.
customer-portalAdded ENVIRONMENT, DEPLOYMENT_MODE, ADMIN_API_KEY envsMirrors production CFN; required for portal admin paths.
agentAdded audit-data named volume mounted at /var/lib/axonflow/audit + AUDIT_FALLBACK_PATH envAudit fallback persistence across container restarts (matches CFN EFS mount).
agent + orchestrator + customer-portalAdded mem_limit + cpus resource limitsMirrors CFN task-definition sizing.
agent + orchestrator + customer-portalHealthcheck wget --spider → curl -fMatches CFN-defined healthcheck commands.
agent + orchestratorDocumented the DEPLOYMENT_KIND=dev overlay defaultPrevents migration 094's prod-safety abort when ORG_ID is still the local-dev-org sentinel.

Generating AXONFLOW_INTERNAL_SERVICE_SECRET​

# Generate a 32-byte hex secret
openssl rand -hex 32 > .axonflow-internal-secret

# Set it in your .env file or shell
echo "AXONFLOW_INTERNAL_SERVICE_SECRET=$(cat .axonflow-internal-secret)" >> .env

The secret must be at least 32 characters. Use the same secret across all three services (agent, orchestrator, customer-portal) — they validate each other's tokens with it.

DEPLOYMENT_KIND prod-safety guardrail​

The overlay keeps DEPLOYMENT_KIND=dev by default. Self-hosted deployments flipping to DEPLOYMENT_KIND=production must also set a real ORG_ID (not the local-dev-org sentinel) in the same change. Migration 094 aborts boot on the (production + local-dev-org) combination to prevent silent dev-sentinel stamping of audit rows.

# Correct: production with real org_id
DEPLOYMENT_KIND=production
ORG_ID=acme-prod-us

# Aborts boot at migration 094:
DEPLOYMENT_KIND=production
ORG_ID=local-dev-org   # ❌ sentinel — migration refuses to stamp audit rows

Bundled OTel + Tempo + Grafana stack (axonflow-install)​

Decision Mode emits OTel spans via the decision tracer (introduced in v8.2.0). Until now, those spans needed customer-side OTel wiring to be visible. The axonflow-install bundled stack now ships an OTel Collector + Tempo + Grafana dashboard out of the box, so Decision Mode traces land in a viewer with zero extra configuration. Targeted at self-hosted deployments on non-AWS (e.g. GCP).

# One-command deploy
git clone https://github.com/getaxonflow/axonflow-install.git
cd axonflow-install
./install.sh

After startup:

  • Agent at http://localhost:8080
  • Orchestrator at http://localhost:8081
  • Decision Mode Traces dashboard at http://localhost:3001/d/decision-mode-traces
  • Tempo trace storage backed by local volume

Every Decision Mode call (POST /api/v1/decide) appears in the dashboard within seconds — verdict distribution, latency percentiles, policy trigger rates, per-tenant breakdown.

SDK versions​

No new SDK versions in this release. SDKs remain at v8.3.0 (Rust v0.5.0). The platform /health continues to advertise:

SDKRecommendedMinimum
Python8.3.08.0.0
TypeScript8.3.08.0.0
Go8.3.08.0.0
Java8.3.08.0.0
Rust (preview)0.5.0—

Existing v8.3.0 SDK callers keep working unchanged. The OpenAI-compatible gateway endpoint is exercised by the OpenAI Python SDK, OpenAI Node SDK, or any HTTP client that targets /v1/chat/completions. It does not require an AxonFlow SDK.

What's NOT changed​

  • No breaking changes. All existing SDKs, plugins, and API consumers continue to work unchanged.
  • Plugin versions: Recommended claude / cursor / codex at v1.5.2; openclaw at v2.6.1. Unchanged from v8.3.0.
  • Existing endpoints: Proxy Mode (POST /api/request), Gateway Mode (POST /api/policy/pre-check), and Decision Mode (POST /api/v1/decide) are all unchanged. The OpenAI-compatible endpoint is additive.

Upgrade notes​

Self-hosted Community (Docker / docker compose up)​

Pull the v8.4.0 image. The base docker-compose.yml (community mode) needs no changes. The OpenAI-compatible endpoint is available immediately at POST /v1/chat/completions.

Self-hosted Enterprise (Docker / docker compose up)​

Required: Before starting v8.4.0, generate and set AXONFLOW_INTERNAL_SERVICE_SECRET in your .env file (see generation steps above). Without it, the unified-policies UI silently shows 0 system policies.

After setting the secret:

docker compose -f docker-compose.yml -f docker-compose.enterprise.yml down
docker compose -f docker-compose.yml -f docker-compose.enterprise.yml pull
docker compose -f docker-compose.yml -f docker-compose.enterprise.yml up -d

If flipping DEPLOYMENT_KIND=production, verify ORG_ID is set to a real org identifier (not local-dev-org) — migration 094 will abort boot otherwise.

In-VPC Enterprise (AWS CFN)​

No action required. CFN-deployed stacks already injected AXONFLOW_INTERNAL_SERVICE_SECRET from InternalServiceSecret — this release brings the docker-compose overlay to parity with what CFN was always doing.

Community-SaaS users​

No action required. The OpenAI-compatible endpoint is available at all tiers.

SDK users​

No SDK changes in this release. The OpenAI-compatible endpoint works with the OpenAI Python SDK (v2.x or later) and OpenAI Node SDK. AxonFlow SDKs remain at v8.3.0.

Migration resources​

Last updated on