Skip to main content

S3 / Object Store

Tasks

Export AIControls audit events to any S3-compatible object store — AWS S3, Google Cloud Storage, Azure Blob Storage, or MinIO. Useful for long-term retention, compliance archiving, and feeding events into a SIEM.

Prerequisites​

  • An S3 bucket (or GCS/Azure Blob container) with write access
  • An access key ID and secret (or service account credentials) with s3:PutObject permission
  • AIControls admin access

Configure the integration​

  1. Go to Settings → Integrations → S3 / Object Store and click Add integration.
  2. Select your provider: AWS S3, Google Cloud Storage, Azure Blob Storage, or S3-compatible (MinIO, Cloudflare R2, etc.).
  3. Enter the bucket name, region, and credentials. For S3-compatible providers, enter a custom endpoint URL.
  4. Set the key prefix (e.g. aicontrols/audit/). Objects are written as <prefix>YYYY/MM/DD/<timestamp>.ndjson.gz.
  5. Click Test connection — AIControls writes a small test object and reads it back. Confirm success before saving.
  6. Click Save. Audit events begin streaming to the bucket within minutes.

Export format​

Events are exported as newline-delimited JSON (.ndjson), gzip-compressed. Each line is one audit event with the same schema as the Audit Log API:

{"event_type":"tool_call","timestamp":"2026-06-30T12:34:56Z","agent":"claude-code","tool":"bash","decision":"allow","identity":"alice@example.com"}
{"event_type":"llm_request","timestamp":"2026-06-30T12:35:01Z","agent":"claude-code","model":"claude-sonnet-4-6","decision":"allow","tokens_in":1200,"tokens_out":340}

Retention and rotation​

AIControls batches events and flushes to S3 every 5 minutes or when the batch reaches 10 MB — whichever comes first. Objects are named by UTC timestamp so they sort chronologically in any S3 browser.

Set lifecycle rules on the bucket directly in your cloud provider to enforce retention (e.g. expire objects after 90 days, transition to Glacier after 30 days).

note

S3 export complements — not replaces — the built-in SQLite audit store. AIControls retains events locally for the configured session_retention_days window regardless of whether S3 export is enabled.

Troubleshooting​

Test connection fails​

Check that the credentials have s3:PutObject and s3:GetObject on the target bucket and prefix. Some bucket policies also require s3:ListBucket for the test — add it temporarily if needed.

Events delayed or missing​

Events are batched — up to a 5-minute delay is expected. If objects stop appearing entirely, check Settings → Integrations → S3 → Delivery log for export errors. Common causes: expired credentials, full bucket quota, or a changed bucket policy.

Last updated on