DS DevShelfHub Projects · AI tools
Tutorials / CrewAI / Reference / Classes / CheckpointConfig
Class flows

CheckpointConfig: Reference Guide

By DevShelfHub

Bundles the storage provider and policy used by @persist.

See the CrewAI API reference index, CrewAI introduction, and core concepts for surrounding context.

What is CheckpointConfig?

CheckpointConfig is the object you pass to @persist so Flows know which storage backend materializes state snapshots — SqliteProvider by default, JsonProvider for human-readable files during development, or your own StorageProvider when you need Postgres, Redis, or DynamoDB. The config may also carry knobs for retention, encryption at rest, or table names depending on provider capabilities.

Treat CheckpointConfig like database connection settings: construct it once per process from environment variables, validate paths exist on disk before accepting traffic, and never point multiple unrelated flows at the same storage file without namespacing keys. When you change providers, plan a migration path for in-flight state_ids because restore_from_id semantics are only compatible within the same logical backend.

Pair this type with Flow documentation on mutating state in place: persistence serializes the Flow's state object, so references you replace wholesale may not round-trip the way you expect across versions.

When to Use

Any Flow using @persist that needs a non-default backend, custom db_path, or explicit storage wiring in tests.

Use Cases

  • • Custom backends
  • • Container volume paths
  • • Restore-from-state-id flows
  • • CI fixtures with JsonProvider

Key Features

  • ✓ Pluggable storage
  • ✓ Composes with SqliteProvider / JsonProvider
  • ✓ Flow persistence entry point

When NOT to Use

Ephemeral flows where losing state on restart is acceptable — omit @persist entirely.

Notes

Single-writer semantics

SqliteProvider is correct for single-host flows. Multiple machines writing one file leads to corruption — move to a networked backend via a custom StorageProvider when you scale horizontally.

Disk lifecycle in containers

Default paths under ~/.crewai are often ephemeral in Kubernetes. Mount a volume and pass db_path explicitly so checkpoints survive pod restarts.

Secrets in state blobs

Persisted JSON may contain API tokens if you stash them on Flow state. Redact before persistence or keep secrets outside the serialized state object.

Import

python 
from crewai.state.checkpoint_config import CheckpointConfig

Key Parameters

Parameter Type Default Purpose
storage StorageProvider SqliteProvider() Backend implementation.

Code Examples

JsonProvider for local debugging

python 
from crewai.state import JsonProvider
from crewai.state.checkpoint_config import CheckpointConfig

cfg = CheckpointConfig(storage=JsonProvider())

SqliteProvider with explicit db_path

python 
from pathlib import Path
from crewai.state import SqliteProvider
from crewai.state.checkpoint_config import CheckpointConfig

cfg = CheckpointConfig(storage=SqliteProvider(db_path=Path('/data/flows.db')))

Wire into @persist

python 
from crewai.flow.flow import Flow, listen, start
from crewai.state.checkpoint_config import CheckpointConfig, persist
from crewai.state import SqliteProvider

@persist(config=CheckpointConfig(storage=SqliteProvider()))
class DemoFlow(Flow):
    @start()
    def begin(self):
        self.state['step'] = 1
        return 'ok'

    @listen(begin)
    def tail(self, _):
        self.state['step'] = 2

Common Mistakes

❌ Pointing two different Flow classes at the same Sqlite file without key namespacing

✅ Use distinct db_path values or table_name overrides per flow.

❌ Expecting JsonProvider to give concurrent multi-writer safety

✅ Use SqliteProvider or a server database when parallel writers exist.

CheckpointConfig FAQ

What is CheckpointConfig in CrewAI?

Bundles the storage provider and policy used by @persist. CheckpointConfig is the object you pass to @persist so Flows know which storage backend materializes state snapshots — SqliteProvider by default, JsonProvider for human-readable files during development, or your own StorageProvider when you need Postgres, Redis, or DynamoDB. The config may also carry knobs for retention, encryption at rest, or table names depending on provider capabilities. Treat CheckpointConfig like database connection settings: construct it once per proce…

Which package defines the CrewAI class CheckpointConfig?

DevShelfHub maps CheckpointConfig to Python module crewai.state.checkpoint_config (package path crewai.state.checkpoint_config in this reference). Pin your installed crewai version and match imports to the snippet on this page.

When should I use CheckpointConfig?

Any Flow using @persist that needs a non-default backend, custom db_path, or explicit storage wiring in tests.

When should I avoid using CheckpointConfig?

Ephemeral flows where losing state on restart is acceptable — omit @persist entirely.

How do I import CheckpointConfig in Python?

from crewai.state.checkpoint_config import CheckpointConfig

Where can I explore more CrewAI API reference pages?

Open the CrewAI API reference index on DevShelfHub to search 58 classes, 30 methods, and 16 decorators, each with runnable examples, parameters, common mistakes, and cross-links.