Architecture · AgentSight v1.0.25

Keep capture native, make product features composable, and keep runtime data on Nodes.

AgentSight separates the machine-level capture substrate from independently composable product features, while keeping detailed runtime data authoritative on Nodes. The current Component Model boundary is deliberately narrow: one session parser runs as bounded Wasm today; Direct and Controller remain transports and coordination paths to the same Node protocol.

Open AgentSight See plans and roles

The data boundary

Three planes, with Nodes authoritative for detailed runtime data.

This page describes the released v1.0.25 implementation at 0080545f7c6b. It distinguishes shipped behavior from design ideas and explicit follow-up work in the repository.

Node data plane

The AgentSight Node captures, stores, and serves detailed runtime data. Sessions, snapshots, prompts, process activity, source-reported usage metadata, and other detailed records remain authoritative on the Node.

Controller coordination plane

Controller handles identity, organizations, memberships, plan and entitlement metadata, Node discovery, relay presence, optional encrypted Direct configuration, and authorization decisions. It is not the authoritative telemetry store.

Client and presentation plane

The hosted app, local UI, and CLI reach Nodes locally, through Direct, or through Controller relay. The browser can aggregate bounded Node overviews without persisting that fleet snapshot in Controller.

Extension boundary

Composable does not mean that the capture substrate moved into plugins.

v1.0.23 reorganized independently composable product functionality under ext/ while preserving the existing capture and protocol contracts. The distinction is architectural: platform capture stays native, while higher-level functionality gets an explicit boundary that can be native, build-time, frontend, or a WebAssembly Component depending on the feature.

Boundary 01

Native capture substrate

agentsight-capture keeps platform capture such as eBPF, /proc, SSL, stdio, and system runners. Identity/capability enforcement and transport also remain native host responsibilities.

Boundary 02

Composable product extensions

The canonical ext/ tree now owns session parsing, analysis, semantic pprof, repository visualization, and web presentation boundaries without copying their algorithms into a new abstraction.

Boundary 03

One shipped Wasm Component today

Only ext/session currently exports and executes a wasm32-wasip2 Component. Analysis, pprof, vis, and web are native or build-time boundaries in v1.0.24.

What actually runs as Wasm?

One host-supplied transcript enters one bounded session Component.

The released ext/session parser exports a wasm32-wasip2 Component entrypoint. Native discovery reads the filesystem and handles Cursor subagent aggregation, then supplies one transcript plus bounded metadata to the Component. The production CLI does not dynamically discover arbitrary extensions or dispatch extension-defined commands in v1.0.25.

The Wasmtime host links WASI Preview 2 for ABI compatibility but gives the default Component no inherited arguments, environment, stdio, directories, or network access; TCP and UDP are disabled. AgentSight-specific authority would have to arrive through an explicit capability-bearing host interface. The current host is for trusted Components shipped with AgentSight, not a user-uploaded arbitrary-Wasm execution boundary.

01
64 MiB
Default Component memory limit
02
10 million
Default execution fuel
03
16 MiB
Maximum Component binary and transcript content size
04
64 KiB
Maximum combined session metadata size

Current limitations

The Component boundary is real, but a general runtime plugin system is not shipped yet.

Only session parsing currently crosses the Component Model execution boundary. Analysis,pprof, vis, and web presentation have explicit extension directories but execute natively or at build time. Dynamic extension discovery, extension-defined CLI commands, and opaque Controller-to-Node /ext/* routing are explicitly follow-up work rather than current capabilities.

Existing Controller relay authorization remains route-specific and fail-closed. Published crate names, public agentsight-capture import paths, Node protocol behavior, CLI commands, and binary names remain compatible across the refactor.

Shipped in v1.0.25

Wasm

Single-transcript session parsing through a bounded Component host.

Not shipped

Arbitrary uploaded plugins, dynamic command discovery, or generic remote extension routing.

Current connection paths

Local, Direct, and Controller-managed access share one Node protocol.

Direct is not merely a fallback for Controller relay. A browser-reachable Node can be used by explicit IP or URL even when relay is unavailable or not deployed. Controller adds coordination rather than replacing that path.

01
Local
Run and query AgentSight on one machine. Local capture and saved-session analysis do not require Controller.
02
Direct
A browser reaches a Node by an explicit HTTP(S) endpoint. Direct remains usable without Controller relay and is preferred when a saved Direct path is available.
03
Controller-managed
Controller adds OAuth identity, organization-scoped discovery, plan state, relay connectivity, roles, and authorization before managed remote operations.

Direct pairing

Normal browser access uses a scoped Node capability.

A Direct binding link carries bootstrap authority long enough to identify the Node and mint a scoped capability. The browser stores the returned capability for normal Node requests; the persistent bootstrap authority is not used as the ordinary access token. Long-lived Direct capabilities are persisted locally by the Node with expiry so a restart does not necessarily force immediate re-pairing.

Direct configuration stays in the current browser by default. A signed-in user may explicitly opt in to save a compact Direct endpoint and bootstrap configuration for another browser. Controller stores that optional account copy encrypted; its D1 database does not store the plaintext, and the account copy can be removed separately from the local browser capability.

Transport order

1. Saved Direct path

Use a reachable Node endpoint when one is paired.

2. Controller relay

Use relay when that transport is online and the operation is allowed.

Controller data boundary

Controller coordinates access; it does not persist detailed Node payloads.

Controller stores OAuth identity, organizations and memberships, organization configuration, plan and entitlement metadata, Node registration, relay credentials and presence, optional encrypted Direct configuration, and the authorization decision used before a relayed operation.

v1.0.24 also makes the existing relay reconnect carry the running CLI version. After the relay token is authenticated, Controller refreshes the persisted Node version together with last_seen_at; older Nodes that omit the version header keep their previously stored value. This fixes stale fleet version labels after an upgrade without adding a polling path or requiring Direct re-pairing.

Stored centrally

Identity and coordination state

Users, organizations, roles, plan state, Node discovery, relay state, and organization configuration live in Controller.

Authoritative on Node

Detailed runtime data

Snapshots, session transcripts, prompts, process data, source-reported subscription metadata, and detailed runtime records remain authoritative on Nodes.

Relay behavior

Payloads are not stored as relay history

Relay traffic exists in Controller runtime memory while a request is active; Controller does not persist relay response bodies.

All machines

Fleet aggregation happens in browser memory after reading reachable Nodes.

The signed-in organization landing view queries each reachable Node for a bounded overview through Direct or Relay. The browser combines machine state, active and stopped sessions, reported Tokens, CPU/RSS, Agent Plans, and source-reported subscription windows, then lets the user switch to one Node. Controller supplies the machine directory and access policy; it does not persist the fetched Node snapshots or the aggregate produced from them.

This boundary matters for both privacy and failure semantics. A Node that is unreachable cannot contribute current detail to the fleet view, and the browser-side aggregate is not evidence that Controller has a durable copy of the underlying runtime data.

Fleet read path

Directory

Controller identifies Nodes the user may reach.

Data

The browser reads each reachable Node and combines the bounded results locally.

Authorization

Human roles become semantic actions, then Node-local capabilities.

OAuth authenticates a person. Controller resolves organization membership and the requested semantic action. The Node does not need user, billing, or organization RBAC records; it enforces the scoped capability presented to its protocol surface.

Node capability

`node.info`

Read Node identity and protocol information.

Node capability

`evidence.read`

Read the Node snapshot/runtime surface.

Node capability

`session.read`

Read a session, optionally restricted to one session identifier.

Node capability

`session.message`

Send a message to a session, optionally restricted to one session identifier.

Organization roles

Four built-in roles keep fleet authorization small and inspectable.

Nodes are registered into an organization namespace rather than owned directly by one user. Every account receives a personal organization; team organizations use the same membership model.

Role

Viewer

Inspect organization metadata, Nodes, runtime data, sessions, configuration, and billing state.

Role

Operator

Viewer permissions plus the ability to send session messages.

Role

Admin

Operator permissions plus Node, member, and organization-configuration management.

Role

Owner

Admin permissions plus organization and billing management.

Hosted deployment

The app and Controller deploy from one repository revision in one Worker.

The hosted frontend at app.agentsight.us and Controller API/relay at control.agentsight.us are served by one production Cloudflare Worker revision. D1 stores Controller metadata and a Durable Object carries live relay traffic. This deployment unification does not change the Node-authoritative runtime-data boundary.

01
One revision
Frontend and Controller production surfaces move together.
02
Direct remains independent
A browser can still reach a paired Node without using Controller relay.
03
Preview stays isolated
Non-production builds use separate hosted resources from production.

Plans and hosted preview

The plan catalog exists, but billing gates are not currently enforced in the hosted preview.

Controller exposes the Free, Pro, Team, and Enterprise catalog and keeps persisted billing state separate from effective access. In the current hosted preview, registered users receive an unlimited effective plan, so implemented managed-connectivity and multi-member gates are bypassed without rewriting the stored plan. Pricing documents the catalog separately from today’s preview access.

See the plan catalog Review data handling

Primary sources

Architecture claims are pinned to the released implementation.

Reviewed on 16 August 2026 against AgentSight v1.0.25 at 0080545f7c6b110ec2d4a4af5100b58f514c84d5.