Skip to main content

​
What is S2 Lite?

S2 Lite is a self-hostable server implementation of the S2 API. It provides a single-node binary with no external dependencies beyond object storage, making it easy to deploy and manage.

​
Key Features

  • Fully Compatible: Implements the complete S2 API specification
  • Object Storage Native: Uses SlateDB as its storage engine, relying entirely on object storage for durability
  • Single Binary: No additional services or dependencies required
  • Flexible Storage: Works with AWS S3, Tigris, Cloudflare R2, and any S3-compatible object store
  • In-Memory Mode: Can run entirely in-memory for testing and development
  • Production Ready: Data is always durable on object storage before being acknowledged

​
When to Use S2 Lite

Development & Testing

Run in-memory mode for integration tests and local development without any external dependencies.

Self-Hosted Production

Deploy on your own infrastructure with full control over data location and compliance.

Edge Deployments

Run closer to your data sources using regional object storage like Cloudflare R2 or Tigris.

Cost Optimization

Leverage lower-cost object storage tiers for specific workloads.

​
Deployment Modes

​
In-Memory (Development)

s2 lite --port 8080
Perfect for:
  • Local development
  • Integration testing
  • CI/CD pipelines
  • Quick experimentation
In-memory mode loses all data when the process stops. Use only for development and testing.

​
Local Filesystem (Testing)

s2 lite --local-root ./s2-data --port 8080
Perfect for:
  • Persistent local testing
  • Single-node development environments
  • Data that needs to survive restarts
Local filesystem mode is not recommended for production as it lacks the durability guarantees of object storage.

​
Object Storage (Production)

s2 lite --bucket my-s2-bucket --path s2lite --port 8080
Perfect for:
  • Production deployments
  • Multi-region setups
  • Durable, scalable storage
  • Kubernetes environments

​
Architecture

​
Internal Components

  • HTTP Server: Built with axum for high-performance async I/O
  • Streamer Tasks: Each stream has a dedicated Tokio task that owns the tail position and broadcasts to followers
  • SlateDB Engine: Provides durable key-value storage backed entirely by object storage
  • Pipelining: Appends are pipelined to improve performance against high-latency object storage
Pipelining is currently disabled by default. Enable with S2LITE_PIPELINE=true to preview future performance improvements.

​
SDK Compatibility

S2 Lite is compatible with all official S2 SDKs:
SDKStatusMinimum Version
CLI✅ Supportedv0.26+
TypeScript SDK✅ Supportedv0.22+
Go SDK✅ Supportedv0.11+
Rust SDK✅ Supportedv0.22+
Python SDK🚧 Migration needed-
Java SDK🚧 Migration needed-

​
API Coverage

S2 Lite implements the complete S2 API specification:
EndpointSupport
/basins✅ Supported
/streams✅ Supported
/streams/{stream}/records✅ Supported
/access-tokens❌ Not supported (#28)
/metrics❌ Not supported
Unlike the cloud service, requests to /streams/* must include the S2-Basin header. The SDKs handle this automatically.

​
Monitoring & Observability

S2 Lite includes built-in monitoring endpoints:
  • /health: Returns 200 OK for readiness and liveness checks
  • /metrics: Prometheus-compatible metrics in text format

​
Next Steps

S3 Setup

Configure S3, Tigris, or R2 for production deployments

Production Deployment

Deploy S2 Lite with Kubernetes and Helm

Backup & Restore

Learn backup strategies and disaster recovery

API Reference

Explore the complete S2 API specification

Build docs developers (and LLMs) love

Get started for freeTalk to us