Collector

A local server that receives, stores, and serves your agent's observability data.

What it does

The collector is the backend of the AOP stack. It:

  • Receives events via HTTP POST at /events
  • Stores events in a local SQLite database at ~/.aop/events.db
  • Streams events via Server-Sent Events (SSE) at /stream
  • Serves the dashboard UI on the same port
  • Exposes a REST API for querying sessions and events

Everything runs locally on your machine. No cloud, no account, no data leaving your environment.

Quick start

The fastest way to run the collector is with npx — no installation required:

npx @useaop/collector start

This starts the collector on port 4317 and opens the dashboard in your browser.

Install as a dependency

If you prefer to pin the version or include it in your project:

npm install --save-dev @useaop/collector

# Then run via npx or a package.json script
npx @useaop/collector start

Storage

Events are persisted in a SQLite database at:

~/.aop/events.db

The database is created automatically on first run. You can customize the path via the --db-path flag or the dbPath config option. To reset all data, simply delete the file.

Programmatic usage

You can start the collector programmatically from Node.js:

import { startCollector } from '@useaop/collector'

const server = await startCollector({
  port: 4317,
  dbPath: './my-events.db',
  openBrowser: false
})

// Later, shut it down
await server.close()

This is useful for integration tests, CI pipelines, or custom tooling.

The collector is designed to be ephemeral and lightweight. It uses SQLite with WAL mode for fast writes and minimal disk footprint. A typical agent session produces less than 1 MB of data.

Next steps