Agent Zero Gateway

Gateway and registry for connecting clients to multiple Agent Zero instances.

The gateway is intentionally separate from agent-zero:

• agent-zero is one runnable agent runtime with sessions and tools.
• agent-zero-gateway discovers, health-checks, and proxies many Agent Zero instances.
• Clients authenticate/connect to one gateway instead of managing every agent endpoint directly.

See ROADMAP.md for planned dynamic agent self-registration, heartbeat leases, TTL expiry for sandbox/k8s agents, and richer inventory support.

Quick start

cp agents.example.json agents.json
npm install
npm run dev

Default URL:

http://127.0.0.1:7400

Optional gateway auth, CORS, health-check interval, and rate limiting:

AGENT_ZERO_GATEWAY_TOKEN=change-me \
AGENT_ZERO_GATEWAY_CORS=http://localhost:5173 \
AGENT_ZERO_GATEWAY_HEALTH_INTERVAL_MS=15000 \
AGENT_ZERO_GATEWAY_RATE_LIMIT=120/1m \
npm start

When AGENT_ZERO_GATEWAY_TOKEN is set, all endpoints except /health require:

Authorization: Bearer <token>

Configuration

agents.json:

{
  "agents": [
    {
      "id": "local-research",
      "name": "Local Research Agent",
      "baseUrl": "http://127.0.0.1:7331",
      "token": null
    }
  ]
}

Tokens may also come from the environment:

{ "token": "env:RESEARCH_AGENT_TOKEN" }

Config path can be overridden:

AGENT_ZERO_GATEWAY_CONFIG=/path/to/agents.json npm start

API

Gateway

GET /health
GET /agents
POST /agents/register
POST /agents/:agentId/heartbeat
DELETE /agents/:agentId/registration
GET /sessions
POST /sessions
GET /sessions/:gatewaySessionId/turns
GET /memory/health
GET /memories
POST /memories
POST /memory/search
POST /memory/context
DELETE /sessions?source=discovered
GET /audit

Admin agent proxy

GET    /admin/agents/:agentId/health
GET    /admin/agents/:agentId/sessions
POST   /admin/agents/:agentId/sessions
GET    /admin/agents/:agentId/sessions/:sessionId/messages

SSE streams are proxied through the gateway while preserving upstream Agent Zero event payloads.

Scripts

npm run dev            # watch mode with tsx
npm run build          # compile TypeScript to dist
npm start              # run compiled server
npm run check          # type-check
npm run smoke          # live gateway smoke test
npm run smoke:registration # validates agent self-registration leases
npm run smoke:memory   # validates local-memory agent against agent-zero-memory
npm run smoke:memory-proxy # validates gateway memory proxy endpoints
npm run smoke:turns    # validates persisted turn/work summaries
npm run smoke:restart  # validates gateway session persistence across restart
npm run smoke:multi    # validates multi-agent routing when 2+ agents are configured
npm run smoke:sse      # validates metadata-enriched SSE proxying