Skip to main content

​
Quick start

This guide will walk you through setting up S2 Lite locally and creating your first basin and stream. You’ll be reading and writing records in just a few minutes.

​
Prerequisites

​
Start S2 Lite

S2 Lite is embedded in the CLI and provides a fully functional S2 API that runs in-memory. Start it with: 
s2 lite --port 8080
This starts S2 Lite on port 8080 with in-memory storage. No external dependencies required.
For production use, you can configure S2 Lite to use object storage like AWS S3 or Tigris. See the S2 Lite documentation for details.

​
Configure the CLI

In a new terminal, set these environment variables to point the CLI at your local S2 Lite instance: 
export S2_ACCOUNT_ENDPOINT="http://localhost:8080"
export S2_BASIN_ENDPOINT="http://localhost:8080"
export S2_ACCESS_TOKEN="ignored"
S2 Lite doesn’t require authentication for local development, but you still need to set S2_ACCESS_TOKEN to any value.

​
Verify the server is ready

Check that S2 Lite is running: 
curl http://localhost:8080/health
You should see a 200 OK response.

​
Create a basin

Create your first basin with automatic stream creation enabled: 
s2 create-basin quickstart --create-stream-on-append --create-stream-on-read
This creates a basin named quickstart that automatically creates streams when you append to or read from them.
1

Create a basin

The basin is created with automatic stream creation enabled
2

Append records

Write your first records to a stream
3

Read records

Read the records back from the stream

​
Write records to a stream

Append some records to a new stream: 
echo "Hello, S2!" | s2 append s2://quickstart/my-stream
echo "This is my first record" | s2 append s2://quickstart/my-stream
echo "Streaming is fun" | s2 append s2://quickstart/my-stream
Each line becomes a separate record in the stream. The stream is created automatically because we enabled --create-stream-on-append.

​
Read records from a stream

Read all records from the stream: 
s2 read s2://quickstart/my-stream
You should see all three records printed to stdout. 
# Read all historical records
s2 read s2://quickstart/my-stream

​
Try real-time streaming

Open two terminals to see real-time streaming in action. Terminal 1 - Start a live reader: 
s2 read s2://quickstart/live-demo --follow 2>/dev/null
Terminal 2 - Stream data in: 
for i in {1..10}; do 
  echo "Message $i" | s2 append s2://quickstart/live-demo
  sleep 1
done
You’ll see messages appear in Terminal 1 as they’re written in Terminal 2.
Try the Star Wars streaming demo for something more fun:
# Terminal 1: Start reading
s2 read s2://quickstart/starwars 2>/dev/null

# Terminal 2: Stream Star Wars
nc starwars.s2.dev 23 | s2 append s2://quickstart/starwars

​
Benchmark performance

Test S2 Lite’s performance with the built-in benchmark: 
s2 bench quickstart --target-mibps 10 --duration 5s --catchup-delay 0s
This writes and reads data at 10 MiB/s for 5 seconds, showing throughput and latency metrics.

​
Next steps with the SDK

Now that you have S2 Lite running, try using the SDK to build applications.

​
Rust SDK example

Add the SDK to your project: 
cargo add s2-sdk tokio futures
Write and read records programmatically: 
use s2_sdk::{
    S2,
    producer::ProducerConfig,
    types::{AppendRecord, S2Config},
};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = S2::new(S2Config::new(std::env::var("S2_ACCESS_TOKEN")?))?;
    let stream = client.basin("quickstart".parse()?)
                       .stream("my-stream".parse()?);
    
    let producer = stream.producer(ProducerConfig::new());
    
    let ticket = producer.submit(AppendRecord::new("Hello from Rust!")?).await?;
    let ack = ticket.await?;
    
    println!("Record written with seq_num: {}", ack.seq_num);
    
    producer.close().await?;
    Ok(())
}
Remember to export the environment variables pointing to your S2 Lite instance before running SDK examples.

​
Using S2 cloud

To use the managed S2 service instead of S2 Lite:
1

Sign up

Create an account at s2.dev
2

Generate access token

Generate an access token from the dashboard
3

Configure CLI

Set your access token:
export S2_ACCESS_TOKEN="your-token-here"
Remove the endpoint overrides (or unset them):
unset S2_ACCOUNT_ENDPOINT
unset S2_BASIN_ENDPOINT
4

Create resources

Use the same commands to create basins and streams

​
Troubleshooting

If you see connection errors, make sure S2 Lite is running and the environment variables are set correctly.

​
Common issues

Connection refused
  • Check that s2 lite is running
  • Verify the port matches your S2_ACCOUNT_ENDPOINT and S2_BASIN_ENDPOINT
Stream not found
  • Make sure you created the basin with --create-stream-on-append or --create-stream-on-read
  • Or manually create the stream with s2 create-stream
Environment variables not set
  • Re-export the environment variables in each new terminal session
  • Or add them to your shell profile (~/.bashrc, ~/.zshrc, etc.)

​
Learn more

Build docs developers (and LLMs) love

Get started for freeTalk to us