How It Works

clstr.io breaks down distributed systems into stages you build incrementally. Each challenge covers different patterns, from consensus and replication to partitioning and fault tolerance.

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. They simulate real failure conditions, killing nodes, partitioning the network, and verifying your system recovers correctly. The implementation is up to you.

  Your Code
      |
      v
  Dockerfile --> Docker Image
                           |
  +------------------------v------------------------------+
  |                                                       |
  |             clstr-net - 10.0.42.0/24                  |
  |                                                       |
  |  +-------------+   +-------------+   +-------------+  |
  |  |     n1      |   |     n2      |   |     n3      |  |
  |  | 10.0.42.101 |   | 10.0.42.102 |   | 10.0.42.103 |  |
  |  +------+------+   +------+------+   +------+------+  |
  |  +------+------+   +------+------+   +------+------+  |
  |  |  /app/data  |   |  /app/data  |   |  /app/data  |  |
  |  +-------------+   +-------------+   +-------------+  |
  |                                                       |
  +------------------------+------------------------------+
                           ^ HTTP :8080
                      +----+------+
                      | clstr CLI |
                      +-----------+

Installation

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

Pick a Challenge

Run clstr list to see all available challenges. The distributed key-value store is the first challenge in clstr.io’s distributed systems series.

Run clstr init kv-store --language <lang> to scaffold a new challenge directory with Dockerfile, README.md, and clstr.yaml files.

Build in Any Language

Write your server in any language. Update the Dockerfile to build and start it, and the test runner takes care of the rest: it builds your image and starts one container per node on a shared Docker network. See the test environment guide for a full breakdown.

Run the Tests

Run clstr test. If something fails, the CLI tells you what went wrong and links to the relevant stage guide. Fix it and run again.

Advance

When you pass, run clstr next to unlock the next stage. Each stage builds on the previous one, gradually adding complexity.

Run clstr status at any point to see your progress. CI runs clstr test --so-far on every push, so all earlier stages must continue to pass as you advance.