Skip to main content
The capture plugin stores opted-in traffic for chat completions, messages, and responses. Request and response content is gzip-compressed in blob storage. FrogBot stores only identifiers, timestamps, status, model, blob location, and byte size in the ai-captures collection. Nothing is captured unless you enable capture globally or for an API key.

Install

The filesystem adapter defaults to .frogbot/captures. Production deployments should pass a shared, durable storage adapter implementing put, get, delete, and list.

Capture policy

enabled defaults to false. sampleRate accepts a value from 0 to 1 and defaults to 1 for enabled traffic. When the API keys plugin is also listed, in any order, capture adds capture and captureSampleRate fields to API keys. capture accepts inherit, enabled, or disabled; an explicit key setting overrides the global setting. The plugin does not require the API keys plugin.

Privacy and limits

Incoming HTTP headers are never persisted. Set maxBodyBytes to reject captures whose serialized request, response, or error envelope exceeds the limit. The default is 10 MiB. The first release does not scrub fields inside messages, tools, responses, or errors. Treat the blob store as sensitive data and control access separately from ordinary admin access. Pass access to control who can read index rows. Capture writes run out of band. A storage or index failure is logged but does not fail the AI request. Because the blob and index are separate writes, an interrupted write can leave an unindexed blob. Content is never written to the primary database.

Retention

Set retention: { days, cron? } to register the pruning task frogbot-prune-<collectionSlug>. If you omit retention, captures are retained until you delete them.
  • Schedule. The task runs at midnight daily unless you set cron, on the default queue, so a jobs runner that covers default prunes without extra setup.
  • Each run deletes captures whose requestedAt is older than days, 100 at a time. It deletes each blob before its index row. A storage or delete error fails the job.

Export

aiCapturePlugin() adds the export:captures and export:training-data commands to the FrogBot CLI, even when enabled is false. export:captures exports captures as JSON Lines:
Each line is one decompressed capture record, in requestedAt order. Every flag takes a value, either as the next argument or as --flag=value. Unknown flags and invalid dates fail the command.

Options