Agent architecture

Current implementation

cmd/seagull-agent reads configuration, applies logging and Go memory settings, reports privilege posture, opens private installation state and the key provider, and composes the configuration component into the runtime. It exposes local CLI commands and responds to process signals. Module supervision exists but is not connected to a real collector.

The runtime owns lifecycle and knows neither contracts nor collectors. Identity owns installation state, not network addresses. PKI owns signers, not TLS connections. Configuration validates paths but leaves each owner to open the state or material it names.

Target V2 architecture

Endpoint · Seagull agentBackend · implemented

Operating system sources

Validated configurationsigned policy planned

Configured collectors

Bounded typed admission

Durable spool

Delivery and retry

Installation and key provider

mTLS transport

ingest-gateway

security.events.raw

security.inventory.raw

acknowledgement statedurable ACK

Connections: Operating system sources to Configured collectors; Validated configuration to Configured collectors; Configured collectors to Bounded typed admission; Bounded typed admission to Durable spool; Durable spool to Delivery and retry; Delivery and retry to Durable spool (acknowledgement state); Delivery and retry to mTLS transport; Installation and key provider to mTLS transport; mTLS transport to ingest-gateway; ingest-gateway to security.events.raw; ingest-gateway to security.inventory.raw; ingest-gateway to Delivery and retry (durable ACK).

• Host
• Component
• Redpanda topic
• Planned
• Data flow
• Configuration and signing
• Acknowledgement
• Hover or tap a box to highlight its connections

Dashed boxes are planned agent components. Configuration and the key provider exist today; the gateway and its topics are implemented in the backend.

The whole collection-to-delivery path in this diagram is a target. The implemented identity/configuration foundations are prerequisites, not proof of a running telemetry pipeline.

In-process boundaries

The target prefers one modular daemon with the smallest necessary OS privileges. Modules in a Go process share memory and privileges. Separate goroutines do not isolate a compromised collector. A privileged helper would need a justified OS boundary, authenticated local caller identity, a narrow typed interface, bounded messages, and constrained targets. None exists today.

Admission and source progress

The plan requires a collector to advance its source checkpoint only after the relevant observation is durably admitted. A queue enqueue in memory cannot satisfy that receipt. Event and inventory records remain typed and distinct throughout admission and spool handling.

The agent roadmap records the source plan and milestones. The architecture tests protect package boundaries before the future components are introduced.

Source evidence

Reviewed against the source baseline. Seagull-agent-v2/cmd/seagull-agent/main.go · Seagull-agent-v2/tests/architecture/ownership_test.go · Seagull-agent-v2/README.md.