Skip to content

feat: Add cloud session storage for horizontal scaling #466

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
cdnsteve wants to merge 1 commit into
base: main
Choose a base branch
from
Open

feat: Add cloud session storage for horizontal scaling #466

cdnsteve wants to merge 1 commit into from
+3,904 −5

Conversation

@cdnsteve
Copy link

@cdnsteve cdnsteve commented Jan 9, 2026

Summary

Adds SessionStorage protocol with S3 and GCS implementations for cloud-based session persistence.

Use cases:

  • Horizontal scaling (shared sessions across servers)
  • Ephemeral filesystems (containers, serverless)
  • Custom backends (protocol is extensible)

Installation

pip install claude-agent-sdk[s3]   # AWS S3, DO Spaces, R2, MinIO
pip install claude-agent-sdk[gcs]  # Google Cloud Storage
pip install claude-agent-sdk[cloud] # Both

Usage

from claude_agent_sdk import ClaudeAgentOptions
from claude_agent_sdk.session_storage import S3SessionStorage, S3Config

storage = S3SessionStorage(S3Config(bucket="my-sessions", region="us-east-1"))
options = ClaudeAgentOptions(session_storage=storage)
# Sessions auto-sync to cloud

What's included

  • SessionStorage protocol + BaseSessionStorage ABC
  • S3SessionStorage (works with S3-compatible services)
  • GCSSessionStorage
  • Auto-upload on session end via Stop hook
  • Auto-download on resume
  • 60 unit tests
  • Examples with caching patterns

Note: Cloud storage adds 50-500ms latency per operation. Docs include caching patterns for production scale.

Closes #432

@cdnsteve
feat: Add cloud session storage for horizontal scaling
4768beb 
Implements SessionStorage protocol with S3 and GCS reference implementations
to enable cloud persistence for session transcripts. This supports:

- Horizontal scaling across multiple servers with shared sessions
- Ephemeral filesystem environments (containers, serverless)
- Extensible architecture for custom backends (Azure Blob, etc.)

Key changes:
- Add SessionStorage protocol and BaseSessionStorage ABC
- Add S3SessionStorage with support for S3-compatible services
  (DigitalOcean Spaces, Cloudflare R2, MinIO)
- Add GCSSessionStorage for Google Cloud Storage
- Add SessionSyncManager for automatic sync via hooks
- Add session_storage field to ClaudeAgentOptions
- Add optional dependencies: [s3], [gcs], [cloud]
- Add SessionStorageError for storage failures
- Add 60 unit tests for session storage
- Add examples for basic usage and caching patterns
- Update README with session storage documentation

Closes anthropics#432
@cdnsteve cdnsteve mentioned this pull request Jan 9, 2026
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Feature Request: Cloud-Based Session Storage for Session Management

1 participant

@cdnsteve