Chronos data management

You own the data

Chronos by Intelligex is an open source, self-hosted control plane for AI agents and MCP tools.

The data philosophy follows from the deployment model: data and state lives on infrastructure you control. Configurations, conversations, credentials, document embeddings, schedule history, audit logs — on disks you control.

This page maps where data resides and how it scales.

The two storage layers

Chronos persists data in two primary places:

1. The .chronos directory — a local filesystem directory holding the SQLite database, the encryption key, file uploads, and logs.
2. The relational database — a TypeORM-backed schema across SQLite (default) or PostgreSQL (recommended for production).

The split lets you start with zero configuration (SQLite + local disk) and move to production-grade backend setup (Postgres + S3 type) by supplying environment variables to Chronos.

For the deep-dive in directory, table, and data migrations see how and where Chronos stores data.

The .chronos directory

When Chronos starts, it creates .chronos/ in the running user's home directory if it isn't already there. Default layout:

~/.chronos/
├── database.sqlite      # SQLite database (default backend)
├── encryption.key       # AES key for credential encryption
├── storage/             # Blob storage for uploaded files
└── logs/                # Application logs

Every path is overridable via Chronos environment variables DATABASE_PATH, SECRETKEY_PATH, BLOB_STORAGE_PATH, LOG_PATH — mostly used in containerised deployments where you want state on a mounted volume so it survives container restarts. Mounting ~/.chronos/ onto persistent storage is the simplest pattern; redirecting individual paths to dedicated volumes is another option.

The relational backend

Chronos supports two relational backends through TypeORM:

• SQLite (default) — zero-configuration, file-based at ~/.chronos/database.sqlite. Right for single-host development and small-team self-hosting.
• PostgreSQL — recommended database for production. Right for any deployment with multiple Chronos replicas or enough throughput that SQLite write-locks become a bottleneck.

Selection is controlled via DATABASE_TYPE plus the standard DATABASE_HOST / DATABASE_PORT / DATABASE_NAME / DATABASE_USER / DATABASE_PASSWORD environment variables.

Schema migrations are organised per backend in packages/server/src/database/migrations/{sqlite,postgres} and are run on the server startup.

Credential encryption

Credentials — LLM API keys, MCP server tokens, agent outbound-auth secrets, OAuth refresh tokens — are stored as ciphertext in the database Credential table. Plaintext values are always encrypted before writing to DB.

The encryption key lives at ~/.chronos/encryption.key - you can change with SECRETKEY_PATH.

On the first boot, Chronos generates a fresh key if it doesn't exist. Treat this file like any other production secret. Back it up — losing the key means every encrypted credential becomes unrecoverable.

Mount it on persistent secure storage in any containerised deployment so it survives container restarts. Rotate when compromised.

Decryption happens only at the gateway boundary — when a tool callback resolves an MCP server's outbound auth, or when an HTTP-agent dispatch resolves the agent's outbound auth. Plaintext credentials do not reach the agent process or Chronos UI layer.

Blob storage

Three backends are supported for uploaded files (document store sources, attachments, agent-generated artifacts):

1. Local (default) — files under ~/.chronos/storage/. Fine for single-host deployments.
2. S3 compatible — AWS S3 or any S3-compatible service (R2, MinIO, GCS-via-S3-compat, etc.).
3. GCS — Google Cloud Storage.

Selection is controlled via STORAGE_TYPE. The recommended choice beyond a single Chronos replica is to store these artefacts in S3 compatible service.

Logging and observability

Logging uses Winston with daily rotation. Three streams ship by default:

• server.log — general application logs.
• server-error.log — error-level logs.
• server-requests.log.jsonl — HTTP request logs in JSONL.

Sensitive fields (passwords, API keys, authorization headers) are stripped from log output before write. The same pipeline emits the v1.6 audit lines from the MCP gateway (event=mcp.tool.invoke).

Chronos will introduce the persistent tool_invocation_audit concept in the near future.

What "you own the data" means in practice

A handful of operational consequences fall out of the self-hosted model:

• Backups. Snapshot the relational database, the .chronos directory (or its constituent paths), and the blob bucket. Together they're the full state.
• Audit-trail residency is yours. The audit table sits in database you control. Compliance review queries will run against your database as well.
• Credential rotation. The vault is a file you own; you have to define the rotation cadence; the audit of who accessed what is managed by you.
• No vendors. Chronos does not depend on a managed service to invoke an agent, dispatch a tool call, or write an audit row. If you run your own LLM models, air-gapped deployments work.
• No Data-residency constraints. You control servers, region, and where the data is hosted.

The trade-off, of course, is that operational responsibility is yours to manage.

Get hands-on

• How and where Chronos stores data — the deep dive: every entity, every path, every environment variable.
• Hosting Chronos — advanced examples — production-shaped docker-compose recipes, including Postgres + worker mode + queue / Redis.
• Chronos self-hosted quickstart — get a single-instance Chronos running in five minutes.
• Chronos governance — how the audit, encryption, and access-control surfaces compose.