How It Works

clstr.io breaks down distributed systems into stages you build incrementally: databases, caches, message queues, lock services, and more. Each challenge teaches a different pattern (consensus, replication, partitioning, fault tolerance), starting simple and adding complexity one stage at a time.

Tests verify behavior against real-world scenarios: network failures, crash recovery, concurrent access. They check what your system does, not how it’s built, so you’re free to choose your own data structures and algorithms.

Each stage explains what to implement and links out to good resources. Here’s how to get started.

Installation

See this guide on how to install the CLI on your system.

Pick a Challenge

Run clstr list to see all available challenges. Start with the distributed key-value store challenge.

Scaffolding

Run clstr init kv-store --language go to create a new challenge directory with:

• Dockerfile - Builds and runs your server in a container
• README.md - Challenge overview and requirements
• clstr.yaml - Tracks your progress
• .gitignore - Files to .gitignore

Build in Any Language

Write your implementation in any language (Go, Rust, Python, whatever), then update the Dockerfile to build and start your server. The test runner builds your image and runs one container per node in the cluster.

Run the Tests

Run clstr test. Tests are black-box: they interact with your system only through HTTP and can’t inspect internals, read your data files, or access implementation state.

Depending on the stage, tests will kill nodes (SIGKILL), partition nodes off from each other to simulate network splits, and verify your system recovers correctly: elects a new leader, refuses writes without quorum, recovers committed data on restart. You’re tested on behavior under failure conditions, not just the happy path.

Advance

When you pass, run clstr next to unlock the next stage. Each stage builds on the previous one, gradually adding complexity. CI runs clstr test --so-far on every push, so your implementation must continue satisfying all earlier stages as you advance.

At any point, run clstr status to see your current progress and a link to the stage guide.

Good luck! 🚀