Skip to main content

Overview

Teams that route their agents’ model traffic through an LLM gateway can record it there, without installing anything on developer machines. beacon-gateway (the gateway/ module in this repository) attaches to the gateway’s hook, decodes each model call, and writes Beacon events in the runtime JSONL schema, marked harness.collection_method: gateway. A gateway sees the conversation as the model receives it: the system prompt, the tool catalog, the user’s turns and the tool results on the way in, and the model’s text, token counts and tool calls on the way out. It does not see the agent’s own lifecycle (approvals, hooks, files the agent wrote without a tool call), so gateway events complement endpoint collection rather than replace it. endpoint on a gateway event is the gateway host, and user is the identity the gateway resolved for the call.

Supported gateways

Each page covers what that gateway exposes, how sessions and identity are named, and how to deploy it. One beacon-gateway process can serve several gateways at once: list one entry per gateway under gateways. Model protocols: Anthropic Messages, OpenAI Chat Completions and OpenAI Responses, as JSON or server-sent events.

Run it

Build and run
gateway/deploy/ holds a commented configuration and example LiteLLM and Envoy configurations. They observe only: LiteLLM lets calls through when the gateway is unreachable, and Envoy streams replies to the client as they arrive. Events go to the JSONL files the outputs section names; beacon scan --log-path <file> runs threat rules over them like any runtime log. To record identifiers, paths, commands, models and token usage but no prompt, reply, instructions, tool arguments or tool results, set:
Metadata only

Deployment notes

These apply whichever gateway you attach to.
  • Fail open. Every shipped configuration lets model calls through unrecorded when beacon-gateway is down or slow. Keep it that way: the open build observes only and never blocks a call.
  • Health and counters. /healthz and /stats are served on the admin listener (admin: 127.0.0.1:4029). /stats counts calls, calls let through unanalyzed when admission was full, analysis failures and records dropped per output.
  • Replicas. The open build’s store is in memory and per process. Run one beacon-gateway per gateway replica (a sidecar), and expect a session whose calls land on several replicas to record its system text and tool definitions once per replica.
  • Load. pipeline.max_in_flight (default two per CPU), pipeline.max_body_bytes and pipeline.queue_wait bound the work in progress; a call that waits longer than queue_wait goes through unrecorded. gc.memory_limit defaults to 80% of the container’s memory limit.
  • Outputs. Write beacon.event records to a file your log shipper reads. The file uses the runtime JSONL schema, so the same SIEM mappings apply.
  • Sessions. Clients that send a session header get one session per conversation. Claude Code sends x-claude-code-session-id; other clients can send session_id, x-session-id or conversation_id, or set pipeline.session_headers.

What gets recorded

Tool calls are recorded when the model makes them, before the agent acts on them. Replies carry gen_ai.response.id, the provider’s message id, which is the same id the endpoint’s session readers record, so a gateway’s and an endpoint’s record of one model call can be matched.

Endpoint event schema

Fields and provenance markers, including the gateway collection method.

Integration model

How Beacon collects from each kind of agent runtime.

LiteLLM

Guardrail API setup for the LiteLLM proxy.

Envoy, Envoy Gateway, Istio

External Processing setup for Envoy-based gateways.

Portkey

Webhook guardrail setup for Portkey.