Storage Configuration

Storage configuration determines where Reflexio stores data.

Default Storage (Open Source)

The open-source version uses SQLite by default — no storage configuration is needed. Reflexio automatically creates and manages a local SQLite database, so you can start using it immediately without any setup.

# No storage configuration required — SQLite is used automatically
client = ReflexioClient()  # see Quickstart for connection options
config = client.get_config()
# config.storage_config is already set to SQLite

curl -X GET "${REFLEXIO_URL:-https://www.reflexio.ai}/api/get_config" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY"

Supabase Storage

For production deployments that need managed cloud storage, you can configure Supabase manually:

from reflexio.models.config_schema import StorageConfigSupabase

storage = StorageConfigSupabase(
    url="https://your-project.supabase.co",
    key="your_service_role_key",
    db_url="postgresql://reflexio_user:replace-me@host:5432/postgres",
    # Optional reader credentials for search traffic. Search reads use these
    # credentials; writes and consistency-sensitive reads still use url/key.
    read_url="https://your-reader.supabase.co",
    read_key="your_reader_service_role_key",
)
config.storage_config = storage
client.set_config(config)

curl -X POST "${REFLEXIO_URL:-https://www.reflexio.ai}/api/set_config" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "...": "updated full config object"
}
JSON

Search uses reader credentials when provided, so search results can be bounded-stale on replicated infrastructure. Mutations and publish/generation consistency reads continue to use the writer credentials.

PostgreSQL Storage

from reflexio.models.config_schema import StorageConfigPostgres

storage = StorageConfigPostgres(
    db_url="postgresql://reflexio_user:replace-me@host:5432/database",
    schema="public",
    # Optional reader pool for search traffic
    read_db_url="postgresql://reflexio_reader:replace-me@reader:5432/database",
    read_pool_size=10,
)
config.storage_config = storage
client.set_config(config)

curl -X POST "${REFLEXIO_URL:-https://www.reflexio.ai}/api/set_config" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "...": "updated full config object"
}
JSON

PostgreSQL storage requires PostgreSQL 14+ with pgvector available.

The pool is shared by all concurrent work for an organization. When in-flight queries exceed pool_size, additional queries queue for up to pool_acquire_timeout seconds rather than failing immediately; only a query that waits longer than the timeout raises an error. Because pool_size is per organization, the total server-side connection count scales with the number of active organizations — size it against your database's max_connections.

In self-host deployments, pool settings can be set without editing config via REFLEXIO_POSTGRES_POOL_SIZE, REFLEXIO_POSTGRES_POOL_ACQUIRE_TIMEOUT, REFLEXIO_POSTGRES_READ_DB_URL, REFLEXIO_POSTGRES_READ_POOL_SIZE, and REFLEXIO_POSTGRES_READ_POOL_ACQUIRE_TIMEOUT.

Search/read timeout knobs are also available for production deployments: REFLEXIO_SUPABASE_HTTP_TIMEOUT_SECONDS for Supabase/PostgREST and REFLEXIO_POSTGRES_STATEMENT_TIMEOUT_MS for native Postgres.

Config Encryption

Generate a key with:

uv run python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

Keep Fernet keys in your secret manager or deployment environment; never commit them. Set FERNET_REQUIRED=true only after valid keys are deployed and existing configuration rows have been re-encrypted. Required mode fails closed: if no valid Fernet key is available, Reflexio refuses to store plaintext configuration. During key rotation, deploy the new key first in the FERNET_KEYS list, re-encrypt existing rows, then remove retired keys after all running instances can read the newly encrypted values.

Row Retention

Reflexio applies high-water row limits to data tables on the publish path. When an eligible table reaches its limit, the server deletes the oldest 20% of rows for that table by created_at.

# Defaults to 250000 rows per target
REFLEXIO_ROW_LIMIT_INTERACTIONS=500000
REFLEXIO_ROW_LIMIT_PROFILES=250000

# Set a target to 0 to disable its cleanup
REFLEXIO_ROW_LIMIT_PLAYBOOK_OPTIMIZATION_EVENTS=0

# Defaults to 300 seconds. Set to 0 or a negative value to disable the periodic
# cleanup sweep.
REFLEXIO_RETENTION_CLEANUP_INTERVAL_SECONDS=300

The legacy INTERACTION_CLEANUP_THRESHOLD variable still applies to interactions when REFLEXIO_ROW_LIMIT_INTERACTIONS is unset.

Enterprise Self-Host Single Database

For Supabase self-host, configure DATA_SUPABASE_URL, DATA_SUPABASE_KEY, and DATA_DB_URL. For vanilla Postgres self-host, configure DATA_DB_URL. Startup applies auth and data migrations to that same database and stores the generated configuration_json in public.organizations.

Usage-metering WAL volume (self-host)

In multi-instance deployments, give each replica its own persistent WAL directory. Reflexio generates a stable instance id and persists it at REFLEXIO_USAGE_WAL_PATH/instance_id; that file is the preferred identity for usage shipping and replay protection. Set REFLEXIO_INSTANCE_ID only when your orchestrator guarantees uniqueness, such as a Kubernetes StatefulSet ordinal combined with a per-replica PVC. In Kubernetes, either use that ordinal+PVC pattern or let Reflexio keep its generated id on each replica's PVC. If the WAL files become unreadable, startup fails closed and you must recover from the original preserved files rather than starting from an empty directory.

Activating a Self-Host Data Plane

# The activation key shown once in the Reflexio admin portal.
BYOC_DEPLOYMENT_SECRET="rflx-dep-…"
# Optional — the Reflexio control-plane base URL. Defaults to the Reflexio cloud
# control plane (https://www.reflexio.ai); set it only to target a different one.
# CONTROL_PLANE_URL="https://www.reflexio.ai"

CONTROL_PLANE_URL is the canonical setting. Older deployments that still set CONTROL_PLANE_INGEST_URL continue to work as a fallback, but new deployments should use CONTROL_PLANE_URL.

On startup the data plane calls POST /api/billing/byoc/activate with the activation key in the X-Deployment-Secret header. The control plane confirms the key→deployment binding and returns your deployment id, org id, and central public key.

After activation, the data plane ships usage and pulls its entitlement lease automatically. You do not need to set BYOC_DEPLOYMENT_ID or CONTROL_PLANE_PUBLIC_KEY; the activation handshake supplies them.

The activation key is your deployment's credential: keep it secret, and rotate it from the admin portal if exposed. Credential enforcement for legacy BYOC registration and ingest is controlled on the control plane with BYOC_ENFORCE_REGISTER_CREDENTIAL and BYOC_ENFORCE_INGEST_CREDENTIAL. Data plane operators normally do not set those flags; the data plane only needs the per-deployment activation key shown above.