Bring your own storage

The short version

By default, documents you add to a workspace's knowledge base are stored in Protobox's own object storage (see Where your data lives for the region it lands in). If you configure your own S3-compatible bucket instead, every document ingested after that point is written there — never to Protobox's storage.

What you need

Any S3-compatible bucket works — AWS S3 itself, or a self-hosted/alternative provider (MinIO, Cloudflare R2, Backblaze B2, and similar) that speaks the S3 API. You'll need:

• A bucket, created ahead of time
• An access key id + secret access key with read, write, and delete access to that bucket (Protobox verifies all three before saving the config)
• The bucket's endpoint URL, if it's not AWS S3 itself

Set it up

protobox storage set \
  --bucket my-company-docs \
  --access-key-id AKIA... \
  --secret-access-key ... \
  --endpoint https://s3.us-west-2.amazonaws.com \
  --region us-west-2

Protobox verifies the bucket before saving anything: it checks the bucket is reachable, writes a small probe object, then deletes it. If any step fails — bucket doesn't exist, credential lacks write access, and so on — the command fails and names exactly what went wrong, and nothing is saved. Your secret access key is encrypted at rest; it's never returned by any read call.

Check what's configured:

protobox storage show

Revert to Protobox-managed storage at any time — this only changes where future documents go, it does not touch anything already written to your bucket:

protobox storage remove

The same operations are available through the SDK:

await sdk.workspace.storage.set({
  bucket: 'my-company-docs',
  accessKeyId: 'AKIA...',
  secretAccessKey: '...',
  endpoint: 'https://s3.us-west-2.amazonaws.com',
  region: 'us-west-2',
});

const config = await sdk.workspace.storage.get(); // null if using Protobox storage
await sdk.workspace.storage.remove();

What happens if your credential stops working

If your bucket becomes unreachable — a revoked key, a deleted bucket, a permissions change — ingest for that workspace fails outright rather than silently falling back to Protobox's own storage. That's deliberate: a workspace that opted into BYO storage should never have a document land somewhere it didn't ask for. Fix the credential (or bucket) and retry.

Data residency vs. bring-your-own storage

These are two different questions. Region answers which of Protobox's own regions does my file land in. BYO storage answers whose account is it in at all. If you configure BYO storage, it takes priority — the region setting no longer applies to your uploads, since the bucket is entirely outside Protobox's infrastructure.