Skip to main content
IronClaw stores conversations, events, memory, and runtime state locally by default. No database server is required to get started. Served and multi-user deployments move that state to PostgreSQL.

​
Local Storage

Under the default local-dev profile, IronClaw keeps state in embedded database files inside your IronClaw home:
Nothing to install, nothing to configure. Back it up by copying the directory while IronClaw is stopped. This is the right choice for personal use on your own machine.

​
PostgreSQL

Move to PostgreSQL when you serve the web interface to more than one person, run on a host where local disk is ephemeral, or want a database you can back up and replicate independently.
1

Provision a database

PostgreSQL 15 or later. Managed providers work; so does a local container:
The pgvector image is used so embeddings-backed search works. See Memory.
2

Switch to a profile that accepts a database

Do this before you add the [storage] block. Only three profiles wire it: hosted-single-tenant, production, and migration-dry-run. Under any other profile a [storage] block is a startup failure, not a warning:
Use production for a multi-user deployment. See Configuration.
hosted-single-tenant-volume does not accept [storage], despite the name. It is a volume-backed variant of local embedded storage, not a PostgreSQL profile. Pairing it with a [storage] block leaves the instance unable to start.
3

Point IronClaw at it

Put the URL in the environment and name the variable in your configuration:
The URL is environment-only. config.toml may name the variable that holds it, but must never contain the URL itself — it carries the database password.
4

Verify

​
Connection Security

Managed remote PostgreSQL must use TLS. Append sslmode=require to the URL:

​
Pool Sizing

storage.pool_max_size defaults to 8. Keep it below your PostgreSQL server’s connection limit — or your managed provider’s session-pool cap — after reserving capacity for restarts and operator sessions. Override it with IRONCLAW_REBORN_POSTGRES_POOL_MAX_SIZE. The process journal opens 2 additional connections of its own, outside this setting. A running turn heartbeats through the journal to keep its lease alive, and when that heartbeat shared the pool above, one turn’s read burst could starve it until the lease expired and the run failed. Budget pool_max_size + 2 connections per running instance.

​
Secrets and the Master Key

Credentials are encrypted before they reach whichever backend you’re using. The master key that protects them lives in the OS keychain, not the database. On a headless host with no keychain, provide it explicitly:
Losing the master key makes every stored credential unrecoverable. Back it up somewhere other than the machine running IronClaw. See Security.

​
Choosing